@guidepup/virtual-screen-reader

Virtual Screen Reader

Virtual screen reader driver for unit test automation.

Reliable unit testing for your screen reader a11y workflows through JavaScript.

Intro

A11y static analysis tools only cover 25% of WCAG and don't assure on the quality of the user experience for screen reader users. This means teams need to perform lots of manual tests with multiple screen readers to ensure great UX which can take a lot of time...

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, no sweat!

Note: This package should not replace your manual 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.

Features

• Mirrors Screen Reader Experience - simulate and assert on what users would 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.

Getting Started

Install Virtual Screen Reader to your project:

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

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

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

function setupBasicPage() {
  document.body.innerHTML = `
  <nav>Nav Text</nav>
  <section>
    <h1>Section Heading</h1>
    <p>Section Text</p>
    <article>
      <header>
        <h1>Article Header Heading</h1>
        <p>Article Header Text</p>
      </header>
      <p>Article Text</p>
    </article> 
  </section>
  <footer>Footer</footer>
  `;
}

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",
      "region",
      "heading, Section Heading, level 1",
      "Section Text",
      "article",
      "banner",
      "heading, Article Header Heading, level 1",
      "Article Header Text",
      "end of banner",
      "Article Text",
      "end of article",
      "end of region",
      "contentinfo",
      "Footer",
      "end of contentinfo",
      "end of document",
    ]);

    // Stop your virtual screen reader instance
    await virtual.stop();
  });
});

Documentation

Read the docs at guidepup.dev.

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 Rich Internet Applications (WAI-ARIA) 1.2
• Accessible Name and Description Computation (ACCNAME) 1.2
• ARIA in HTML (HTML-ARIA)
• HTML Accessibility API Mappings (HTML-AAM) 1.0

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

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

Please note that 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.

See Also

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/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
• aria-query
• dom-accessibility-api
• aria-at

License

MIT