@guidepup/guidepup

Guidepup

Screen reader driver for test automation.

Reliable automation for your screen reader a11y workflows through JavaScript supporting:

VoiceOver on MacOS

NVDA on Windows

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 you can automate your screen reader test workflows the same you as would for mouse or keyboard based scenarios, no sweat!

Quick Features

• Full Control - if a screen reader has a keyboard command, then Guidepup 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.

Get Started

Set up your environment for screen reader automation with @guidepup/setup:

npx @guidepup/setup

Install Guidepup to your project:

npm install @guidepup/guidepup

And get cracking with your first screen reader automation code!

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start your screen reader instance
  await voiceOver.start();

  // Navigate your environment with screen readers just as your users do
  await voiceOver.next();

  // Assert on what your users really see and hear when using screen readers
  console.log(await voiceOver.lastSpokenPhrase());

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

Documentation

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

Alternatively, you can also check out the typedoc API documentation.

Examples

Check out these awesome examples to learn how you could use Guidepup in your projects.

Alternatively check out this project to check out the Guidepup compatibility against https://github.com/w3c/aria-at test suite.

See Also

Check out some of the other Guidepup modules:

• @guidepup/setup - set up your local or CI environment for screen reader test automation.
• @guidepup/playwright - seemless integration of Guidepup with Playwright.
• @guidepup/virtual-screen-reader - reliable unit testing for your screen reader a11y workflows.
• @guidepup/jest - jest matchers for reliable unit testing of your screen reader a11y workflows.

If you are using GitHub Actions, check out the dedicated guidepup/setup-action to set up your CI ready for screen reader automation.

- name: Set Up Environment
  uses: guidepup/setup-action

Support

Full support is available for:

• VoiceOver on MacOS
• NVDA on Windows

Similar

Here are some similar unaffiliated projects:

• at-driver
• nvda-at-automation
• @accesslint/voiceover
• screen-reader-reader
• web-test-runner-voiceover
• nvda-testing-driver
• assistive-webdriver
• screen-reader-testing-library

License

MIT