Getting started

Guidepup is a screen reader automation library for testing.

It aims to provide a reliable set of APIs to automate your screen reader a11y workflows through JavaScript. Specifically to accommodate the needs of a11y testing and alleviate the overhead of manual testing with real screen readers.

Contents

• Machine setup
• Installation
• First screen reader code

Machine setup

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

npx @guidepup/setup setup

On some machines, screen reader automation is tightly controlled. This command configures your machine for screen reader automation and only needs to be run once per machine.

For further information, see this guide to set up your machine.

Installation

Install Guidepup to your project:

yarn add @guidepup/guidepup

Yarn

yarn add @guidepup/guidepup

NPM

npm install @guidepup/guidepup

Install the screen reader assets required by your installed version of Guidepup:

npx @guidepup/setup install

Run this command again after upgrading @guidepup/guidepup so that the matching assets are available.

First screen reader code

Let's automate a screen reader!

Create example.js (or example.ts for TypeScript) to define your screen reader code.

Typescript

./example.ts

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

(async () => {
  // Start the default screen reader for your OS.
  await screenReader.start();

  try {
    // Move to the next item.
    await screenReader.next();

    // Inspect what the screen reader announced.
    const spokenPhrase = await screenReader.lastSpokenPhrase();
    console.log(`Screen reader announced: ${spokenPhrase}`);
  } finally {
    // Always stop the screen reader once the checks are complete.
    await screenReader.stop();
  }
})();

JavaScript

./example.js

const { screenReader } = require("@guidepup/guidepup");

(async () => {
  // Start the default screen reader for your OS.
  await screenReader.start();

  try {
    // Move to the next item.
    await screenReader.next();

    // Inspect what the screen reader announced.
    const spokenPhrase = await screenReader.lastSpokenPhrase();
    console.log(`Screen reader announced: ${spokenPhrase}`);
  } finally {
    // Always stop the screen reader once the checks are complete.
    await screenReader.stop();
  }
})();

Now run your code to see an automated screen reader!

TypeScript

npx ts-node example.ts

JavaScript

node example.js