Skip to content

Screen reader driver for test automation.

License

Notifications You must be signed in to change notification settings

guidepup/guidepup

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Guidepup

Guidepup available on NPM Guidepup test workflows Guidepup uses the MIT license

MacOS Monetary Support MacOS Ventura Support MacOS Sonoma Support Windows 10 Support Windows Server 2019 Support Windows Server 2022 Support

Guidepup is a screen reader driver for test automation.

It enables testing for VoiceOver on MacOS and NVDA on Windows with a single API.

Capabilities

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

Getting 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!

Examples

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

You can also check out these awesome examples to learn how you could use Guidepup in your projects.

Alternatively check out this project which runs several thousand tests to assert screen reader compatibility against W3C ARIA-AT test suite.

Basic Navigation

VoiceOver

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

(async () => {
  await voiceOver.start();

  await voiceOver.next();
  console.log(await voiceOver.spokenPhraseLog());

  await voiceOver.stop();
})();

NVDA

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

(async () => {
  await nvda.start();

  await nvda.next();
  console.log(await nvda.spokenPhraseLog());

  await nvda.stop();
})();

Complex Navigation

VoiceOver

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

(async () => {
  await voiceOver.start();

  await voiceOver.perform(voiceOver.keyboardCommands.findNextHeading);
  console.log(await voiceOver.itemText());

  await voiceOver.perform(voiceOver.keyboardCommands.findNextControl);
  console.log(await voiceOver.lastSpokenPhrase());

  await voiceOver.stop();
})();

NVDA

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

(async () => {
  await nvda.start();

  await nvda.perform(nvda.keyboardCommands.moveToNextHeading);
  console.log(await nvda.itemText());

  await nvda.perform(nvda.keyboardCommands.moveToNextFormField);
  console.log(await nvda.lastSpokenPhrase());

  await nvda.stop();
})();

Powerful Tooling

Check out some of the other Guidepup modules:

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 For Screen Reader Automation
  uses: guidepup/setup-action

Similar

Here are some similar unaffiliated projects:

Resources