Skip to main content

Getting started

The Virtual Screen Reader is a screen reader simulator for testing.

Install it in your test project and use it to automate screen reader style workflows over a DOM container.

This package should supplement your wider screen reader testing strategy. It gives you fast coverage of common navigation and output expectations without replacing real screen reader coverage.

Installation​

Install the Virtual Screen Reader package:

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

Your first Virtual Screen Reader test​

Create a DOM fixture, start the Virtual Screen Reader, navigate to the current item, and assert the spoken phrase.

./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..."/>
  `;

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

  try {
    await virtual.next();
    await virtual.next();

    expect(await virtual.lastSpokenPhrase()).toEqual(
      "textbox, Search for topics, placeholder Search...",
    );
  } finally {
    await virtual.stop();
  }
});

This is the basic pattern for the Virtual Screen Reader: start it against a DOM container, move through the page, observe what it speaks, and stop it when the test is done.

The package is best used as a fast way to gain coverage over common screen reader scenarios, while real screen readers remain the source of highest fidelity coverage.

When you need a framework-specific example, see using with Jest, Vitest, and Testing Library.