Guidepup Documentation

Guidepup provides several specialized modules to extend its capabilities:

• @guidepup/setup: Environment setup for local or CI automation.
• @guidepup/playwright: Seamless integration with the Playwright testing framework.
• @guidepup/virtual-screen-reader: Enables reliable unit testing for screen reader accessibility (a11y) workflows without a real screen reader.
• @guidepup/jest: Provides Jest matchers for testing a11y workflows.

The Playwright VoiceOver example demonstrates a typical accessibility automation flow:

1. Browser Launch: The test launches Safari via Playwright.
2. Navigation: It navigates to a target URL (e.g., GitHub).
3. VoiceOver Interaction: It uses Guidepup to control VoiceOver to move through the page.
4. Semantic Traversal: It traverses semantic elements (like headings) until a specific target is located (e.g., a specific heading in a README file).

The Playwright Screen Reader example demonstrates how Guidepup automates screen reader interactions within a Playwright test. The typical flow involves:

1. Launching Chromium via Playwright.
2. Navigating to a target URL (e.g., GitHub).
3. Using the OS's default screen reader (controlled by Guidepup) to move through the page.
4. Performing semantic navigation, such as traversing headings to find specific content.

To run VoiceOver testing within a CircleCI pipeline, you can use a CircleCI configuration file (config.yml) designed for Guidepup.

1. Copy the config.yml from the example repository into your project's .circleci directory.
2. Customize the steps in the configuration to include your specific project setup (e.g., installing dependencies, building the application) and the execution of your Guidepup tests.

For a complete implementation reference, visit the circleci-voiceover-example repository.

The examples/ directory provides self-contained starting points and code snippets for integrating Guidepup into your projects. You can use these examples to learn how to control different screen readers and integrate them with testing frameworks like Playwright or CI/CD pipelines.

Available examples include:

• Basic Screen Reader Control: hello-nvda (NVDA) and hello-voiceover (VoiceOver/Safari).
• Playwright Integration: playwright-nvda and playwright-voiceover for automated web testing.
• CI/CD Workflows: github-actions-voiceover and circleci-voiceover for running VoiceOver tests in automated pipelines.

To use Guidepup for screen reader automation, follow these three steps to prepare your machine, install the library, and download the necessary assets:

1. Set up your machine: Run the setup command to configure your local or CI environment.
2. Install the package: Add @guidepup/guidepup to your project.
3. Install assets: Download the required screen reader assets.

Supported platforms include MacOS (Sonoma, Sequoia, Tahoe) and Windows Server (2022, 2025).

# Set up your machine
npx @guidepup/setup setup

# Install Guidepup to your project
npm install @guidepup/guidepup

# Install the Guidepup screen reader assets
npx @guidepup/setup install

Before running specific examples, you must initialize the Guidepup environment on your local machine using the @guidepup/setup utility.

npx @guidepup/setup setup

To run VoiceOver testing within a GitHub Actions workflow, copy the provided test.yml configuration into your project's .github/workflows/ directory.

Note that you must modify the steps in the workflow to include your project's specific setup (e.g., installing dependencies, building the application) and the specific execution commands required to run your Guidepup tests.

To run the Playwright Screen Reader example, follow these steps in order:

1. Initialize the environment: Run npx @guidepup/setup setup once on your machine.
2. Install root dependencies: From the repository root, run npm ci and npx @guidepup/setup install.
3. Setup the example: Navigate to the example directory, install its dependencies, rebuild ffmpeg-static, and run the browsers and tests.

Note: Ensure you have met all environment prerequisites before proceeding.

# Once on your machine
npx @guidepup/setup setup

# In the root directory:
npm ci
npx @guidepup/setup install

# Then in the example directory:
cd ./examples/playwright-screenreader
npm ci
npm rebuild ffmpeg-static --ignore-scripts=false
npm run browsers
npm run test

To run the VoiceOver automation example using Playwright, follow these steps in order. Note that you must have already completed the VoiceOver prerequisites on your machine.

1. Initialize Guidepup environment: Run the setup command.
2. Install root dependencies: Install packages and Guidepup tools in the repository root.
3. Setup example directory: Navigate to the specific example folder, install its dependencies, rebuild ffmpeg-static to ensure media support, install browsers, and execute the tests.

# 1. Once on your machine
npx @guidepup/setup setup

# 2. In the root directory:
npm ci
npx @guidepup/setup install

# 3. Then in the example directory:
cd ./examples/playwright-voiceover
npm ci
npm rebuild ffmpeg-static --ignore-scripts=false
npm run browsers
npm run test

The VoiceOver class provides a high-level API for controlling the VoiceOver screen reader on macOS. It allows for starting/stopping the service, navigating the UI via cursor movements, performing keyboard and mouse actions, and inspecting spoken content or item text.

Note that many commands require VoiceOver to be running. You must call .start() before invoking most other methods and .stop() when finished to ensure a clean state.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // ... perform some commands.

  // Stop VoiceOver.
  await voiceOver.stop();
})();