Virtual Screen Reader

Guidepup Virtual Screen Reader is a headless screen reader driver for unit test automation.

It aims to provide a reliable set of APIs to automate your screen reader unit test workflows in JavaScript the same you as would for mouse or keyboard based scenarios.

• Mirrors Real User Experience - assert on what users really do and hear when using screen readers.
• Test Framework Agnostic - run with Jest, with Playwright, as an independent script, no vendor lock-in.
• UI Framework Agnostic - want to use React, Vue, Solid, Svelte, etc.? All good here! Works with any UI framework, and plays nicely with the Testing Library suite.
• Fast Feedback - avoid the cumbersome overhead of running an e2e test with a running screen reader by running virtually over the provided DOM.

Contents

• Installation
• First Virtual Screen Reader Code

Installation

Install Guidepup to your project:

Yarn

yarn add -D @guidepup/virtual-screen-reader

NPM

npm install --save-dev @guidepup/virtual-screen-reader

First Virtual Screen Reader Code

Let's automate our Virtual Screen Reader!

Using Jest as our test runner, create example.test.js (or example.test.ts for TypeScript) to define your screen reader unit test code.

Typescript

import { virtual } from "@guidepup/virtual-screen-reader";

test("should navigate to the input and announce the placeholder", async () => {
  document.body.innerHTML = `
  <label id="label1">Search for topics</label>
  <input type="text" aria-labelledby="label1" value="" placeholder="Search..."/>
  `;

  // Start Virtual.
  await virtual.start({ container: document.body });

  // Move to the label element.
  await virtual.next();

  // Move to the input element.
  await virtual.next();

  // Expect on the spoken phrase for the input element.
  expect(await virtual.lastSpokenPhrase()).toEqual(
    "textbox, Search for topics, placeholder Search..."
  );

  // Stop Virtual.
  await virtual.stop();
});

JavaScript

const { virtual } = require("@guidepup/virtual-screen-reader");

test("should navigate to the input and announce the placeholder", async () => {
  document.body.innerHTML = `
  <label id="label1">Search for topics</label>
  <input type="text" aria-labelledby="label1" value="" placeholder="Search..."/>
  `;

  // Start Virtual.
  await virtual.start({ container: document.body });

  // Move to the label element.
  await virtual.next();

  // Move to the input element.
  await virtual.next();

  // Expect on the spoken phrase for the input element.
  expect(await virtual.lastSpokenPhrase()).toEqual(
    "textbox, Search for topics, placeholder Search..."
  );

  // Stop Virtual.
  await virtual.stop();
});

Running our test with Jest we should see something like:

PASS  test/virtual.test.ts
  ✓ should navigate to the input and announce the placeholder (42 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        0.361 s
Ran all test suites matching /virtual.test/i.

Watch Usage: Press w to show more.