Virtual Screen Reader

A screen reader simulator for unit tests.

AccessibilityTesting
guidepup/virtual-screen-readerguidepup.dev@guidepup/virtual-screen-reader

README

Virtual Screen Reader


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](https://github.com/guidepup/guidepup) package.

If you are looking to for quick and easy Jest snapshot testing, check out the [@guidepup/jest](https://github.com/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.

The current status of the WPT coverage is:

| Passing | Failing | Skipped |
| :-----: | :-----: | :-----: |
|   184   |   118   |   294   |

The included tests, skipped tests, and expected failures can be found in the WPT configuration file.

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:

  1. ```bash
  2. npm install --save-dev @guidepup/virtual-screen-reader
  3. ```

  1. ```bash
  2. yarn add -D @guidepup/virtual-screen-reader
  3. ```

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.