Virtual Screen Reader

Documentation | API Reference

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 as you would for mouse or keyboard based scenarios.

> [!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.

Capabilities

- 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.

Principles

There is currently no explicit specification for screen readers to adhere to, but there are a number of requirements laid out by specifications to inform screen reader expectations. This library aims to meet these requirements so that it can be as "spec compliant" as possible.

Current W3C specifications used:

- Accessible Name and Description Computation (ACCNAME) 1.2
- Core Accessibility API Mappings (CORE-AAM) 1.2
- Digital Publishing Accessibility API Mappings
- Digital Publishing WAI-ARIA Module 1.1
- Graphics Accessibility API Mappings
- WAI-ARIA Graphics Module
- HTML Accessibility API Mappings (HTML-AAM) 1.0
- ARIA in HTML (HTML-ARIA)
- SVG Accessibility API Mappings
- Accessible Rich Internet Applications (WAI-ARIA) 1.2

Extracted requirements from these specifications can be found in docs/requirements.md. If a requirement is not met, please raise an issue.

Internal modules responsible for constructing the Virtual Screen Reader accessibility tree are being tested against Web Platform Tests for the following specs:

- accname
- core-aam
- dpub-aam
- graphics-aria
- html-aam
- svg-aam
- wai-aria

The current status of the WPT coverage is:

| Passing Test Suites | Failing Tests | Skipped Tests |
| :-----------------: | :-----------: | :-----------: |
| 396 | 81 | 338 |

The included tests, skipped tests, and expected failures can be found in the WPT configuration file with reasons as to skips and expected failures. "Tentative" tests are excluded as their behaviour is often not yet confirmed.

In addition to the W3C specifications a11ysupport.io has been used as a guide for test cases in the absence of anything formal for screen reader output. In future we hope to adopt test cases laid out by the ARIA and Assistive Technologies (ARIA-AT) community group.

> [!NOTE]
> This library should not used as a substitute for testing with real screen readers and with real screen reader users, but a means to gain quick coverage and confidence by automating away common scenarios the same as any other unit test.

Getting Started

Install Virtual Screen Reader to your projects:

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

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

And get cracking with your first screen reader unit test automation code!

Examples

Head over to the Guidepup Website for guides, real world examples, and complete API documentation with examples.

Some examples can also be found in the examples section.

You can also check out this project's own integration tests to learn how you could use the Virtual Screen Reader in your projects.

$3

Here is a basic example for navigating through HTML in a Jest test in a Node setup:

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

function setupBasicPage() {
document.body.innerHTML =

Section Heading

Section Text

Article Header Heading

Article Header Text

Article Text

;
}

describe("Screen Reader Tests", () => {
test("should traverse the page announcing the expected roles and content", async () => {
// Setup a page using a framework and testing library of your choice
setupBasicPage();

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

// Navigate your environment with the Virtual Screen Reader similar to how your users would
while ((await virtual.lastSpokenPhrase()) !== "end of document") {
await virtual.next();
}

// Assert on the kind of things your users would see and hear when using screen readers
expect(await virtual.spokenPhraseLog()).toEqual([
"document",
"navigation",
"Nav Text",
"end of navigation",
"heading, Section Heading, level 1",
"paragraph",
"Section Text",
"end of paragraph",
"article",
"heading, Article Header Heading, level 1",
"paragraph",
"Article Header Text",
"end of paragraph",
"paragraph",
"Article Text",
"end of paragraph",
"end of article",
"contentinfo",
"Footer",
"end of contentinfo",
"end of document",
]);

// Stop your Virtual Screen Reader instance
await virtual.stop();
});
});
`

$3

Virtual Screen Reader also supports ESM environments such as browsers.

Try it out on any website in a browser of your choice by executing the following snippet in DevTools:

`ts
const { virtual } = await import(
"https://unpkg.com/@guidepup/virtual-screen-reader/lib/esm/index.browser.js"
);

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

await virtual.next();

console.log(await virtual.spokenPhraseLog());

await virtual.stop();
`

$3

Virtual Screen Reader will feature detect Accessibility Object Model (AOM) support and adopt the browser's computed accessible names and roles when available.

See the Storybook example to learn how to opt into this behaviour.

Powerful Tooling

Check out some of the other Guidepup modules:

- @guidepup/guidepup - Reliable automation for your screen reader a11y workflows through JavaScript supporting VoiceOver and NVDA.
- @guidepup/setup - Set up your local or CI environment for screen reader test automation.
- @guidepup/playwright - Seamless integration of Guidepup with Playwright.
- @guidepup/jest - Jest matchers for reliable unit testing of your screen reader a11y workflows.

Similar

Here are some similar unaffiliated projects:

- @testing-library/dom
- html-aria
- aria-query
- dom-accessibility-api
- aria-at`

Resources

- Documentation
- API Reference
- Contributing
- Changelog
- MIT License