@guidepup/virtual-screen-reader

Guidepup 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... not anymore!

With Guidepup Virtual Screen Reader you can automate your screen reader unit test workflows the same you as would for mouse or keyboard based scenarios, no sweat!

Upcoming Features

🚧🚧🚧 WIP 🚧🚧🚧

This project is currently a work in progress, but here are some of the features you can expect from this package as it matures:

• Full Control - if a screen reader has a keyboard command, then the Guidepup Virtual Screen Reader supports it.
• Mirrors Real User Experience - assert on what users really do and hear when using screen readers.
• Framework Agnostic - run with Jest, with Playwright, as an independent script, no vendor lock-in.
• Fast Feedback - avoid the cumbersome overhead of running an e2e test with a running screen reader by running virtually over provided DOM.

Getting Started

Install Guidepup to your project:

npm install @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 1</h1>
    <p>Section Text</p>
    <article>
      <header>
        <h1>Article Header Heading 1</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", () => {
    // 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 just as your users would
    while ((await virtual.lastSpokenPhrase()) !== "end of contentinfo") {
      await virtual.next();
    }

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

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

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 - seemless integration of Guidepup with Playwright.

Similar

Here are some similar unaffiliated projects:

• @testing-library/dom

License

MIT