Documentation | API Reference

Guidepup is a screen reader automation library for testing.

It enables testing for NVDA on Windows, Orca on Linux, and VoiceOver on macOS 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 machine for screen reader automation:

npx @guidepup/setup setup

Install Guidepup to your project:

npm install @guidepup/guidepup

Install the Guidepup screen reader assets:

npx @guidepup/setup install

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 examples to learn how you could use Guidepup in your projects.

Basic Navigation

Cross-Platform

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

(async () => {
  // On Linux starts Orca, on macOS starts VoiceOver, and on Windows starts NVDA.
  await screenReader.start();

  await screenReader.next();
  await screenReader.nextHeading();
  await screenReader.nextLink();
  await screenReader.nextLandmark();
  await screenReader.previous();
  await screenReader.act();

  console.log(await screenReader.spokenPhraseLog());

  await screenReader.stop();
})();

NVDA

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

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

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

  await nvda.perform(nvda.keyboardCommands.moveToNextFormField);

  console.log(await nvda.lastSpokenPhrase());

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

Orca

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

(async () => {
  await orca.start();
  await orca.next();
  await orca.nextHeading();

  console.log(await orca.spokenPhraseLog());

  await orca.perform(orca.keyboardCommands.StructuralNavigator.NextFormField);

  console.log(await orca.lastSpokenPhrase());

  await orca.stop();
})();

VoiceOver

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

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

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

  await voiceOver.perform(voiceOver.keyboardCommands.findNextControl);

  console.log(await voiceOver.lastSpokenPhrase());

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

Powerful Tooling

Check out some of the other Guidepup tooling:

• @guidepup/setup - Set up your local or CI environment for screen reader test automation.
• @guidepup/playwright - Seemless integration of Guidepup with Playwright.
• ghcr.io/guidepup/guidepup - Seemless integration of Guidepup in Docker.
• @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.

Resources

• Documentation
• API Reference
• Contributing
• Changelog
• MIT License