Getting started

This page covers how to install Guidepup and run a first screen reader test.

Machine setup

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

npx @guidepup/setup setup

On some machines, screen reader automation requires additional configuration. This command configures your machine and only needs to be run once per machine.

For more information, see the machine setup guide.

Installation

Install Guidepup in your project:

npm

npm install @guidepup/guidepup

Yarn

yarn add @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.

Your first screen reader test

Create example.ts (or example.js for JavaScript):

TypeScript

./example.ts

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

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

  try {
    await screenReader.next();

    const spokenPhrase = await screenReader.lastSpokenPhrase();
    console.log(`Screen reader announced: ${spokenPhrase}`);
  } finally {
    await screenReader.stop();
  }
})();

JavaScript

./example.js

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

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

  try {
    await screenReader.next();

    const spokenPhrase = await screenReader.lastSpokenPhrase();
    console.log(`Screen reader announced: ${spokenPhrase}`);
  } finally {
    await screenReader.stop();
  }
})();

Run the example:

TypeScript

npx ts-node example.ts

JavaScript

node example.js

Guidepup starts the screen reader, moves to the next item, captures what was spoken, and then stops the screen reader.

From here, you can start writing screen reader tests around your application's real user journeys.

See the real world example to see how Guidepup can be used with Playwright.