Skip to main content

Virtual Screen Reader

Guidepup Virtual Screen Reader is a screen reader simulator for unit tests.

This package aims to supplement your testing by enabling you to automate a Virtual Screen Reader for unit test workflows the same you as would for mouse or keyboard based scenarios.

  • Mirrors Screen Reader Functionality - simulate and assert on what users can do when using screen readers.
  • Test Framework Agnostic - run with Jest, Vitest, Web Test Runner, in Storybook, 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 real screen reader by running virtually over the provided DOM.

Important

This package should not replace but augment your screen reader testing, there is no substitute for testing with real screen readers and with real users.

If you are looking to automate real screen readers, check out the @guidepup/guidepup package.

If you are looking to for quick and easy Jest snapshot testing, check out the @guidepup/jest package.

Contents​

Installation​

Install Guidepup Virtual Screen Reader to your project:

yarn add -D @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.

./example.test.ts
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 the Virtual Screen Reader.
  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 the Virtual Screen Reader.
  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.