@guidepup/playwright

Guidepup Playwright

Documentation | API Reference

This package provides Guidepup integration with Playwright for writing screen reader tests that automate VoiceOver on MacOS and NVDA on Windows.

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

If you are using GitHub Actions, check out the dedicated guidepup/setup-action:

- name: Setup Environment
  uses: guidepup/setup-action

Install @guidepup/playwright to your project:

npm install --save-dev @guidepup/playwright @guidepup/guidepup @playwright/test

Note: you require @guidepup/guidepup and @playwright/test as they are peer dependencies to this project.

And get cracking with your first screen reader tests in Playwright!

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 with Playwright in your projects.

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

Playwright Config

In your playwright.config.ts add the following for the best results with Guidepup for Screen Reader automation:

import { devices, PlaywrightTestConfig } from "@playwright/test";
import { screenReaderConfig } from "@guidepup/playwright";

const config: PlaywrightTestConfig = {
  ...screenReaderConfig,

  // ... your custom config
};

export default config;

Check out the configuration this adds in the config.ts file.

Web Content Navigation

In addition to the Guidepup APIs the voiceOver and nvda instances provided by the Guidepup Playwright setup have an additional utility method .navigateToWebContent().

This method will navigate the screen reader to the first element of the document body in the browser.

Use this method after you navigate to a page and have made any necessary checks that the page has loaded as expected. For example, this is how you might use the method with NVDA:

// Navigate to the desired page
await page.goto("https://github.com/guidepup/guidepup", {
  waitUntil: "load",
});

// Wait for page to be ready
await page.locator('header[role="banner"]').waitFor();

// Navigate to the web content
await nvda.navigateToWebContent();

// ... some commands

Note: This command clears all logs meaning .spokenPhraseLog() and .itemTextLog() are emptied. If logs from prior to the command are required, first store the logs in a variable for later use:

// ... some commands

// Store spoken phrases
const spokenPhrases = await nvda.spokenPhraseLog();

// Navigate to the web content
await nvda.navigateToWebContent();

// ... some commands

// Collect all spoken phrases
const allSpokenPhrases = [...spokenPhrases, ...(await nvda.spokenPhraseLog())];

// ... do something with spoken phrases

Providing Screen Reader Start Options

The options provided to nvda.start([options]) or voiceOver.start([options]) can be configured using test.use(config) as follows:

// VoiceOver Example
import { voiceOverTest as test } from "@guidepup/playwright";

test.use({ voiceOverStartOptions: { capture: "initial" } });

// NVDA Example
import { nvdaTest as test } from "@guidepup/playwright";

test.use({ nvdaStartOptions: { capture: "initial" } });

VoiceOver Example

playwright.config.ts:

import { devices, PlaywrightTestConfig } from "@playwright/test";
import { screenReaderConfig } from "@guidepup/playwright";

const config: PlaywrightTestConfig = {
  ...screenReaderConfig,
  reportSlowTests: null,
  timeout: 5 * 60 * 1000,
  retries: 2,
  projects: [
    {
      name: "webkit",
      use: { ...devices["Desktop Safari"], headless: false },
    },
  ],
};

export default config;

voiceOver.spec.ts:

import { voiceOverTest as test } from "@guidepup/playwright";
import { expect } from "@playwright/test";

test.describe("Playwright VoiceOver", () => {
  test("I can navigate the Guidepup Github page with VoiceOver", async ({
    page,
    voiceOver,
  }) => {
    // Navigate to Guidepup GitHub page
    await page.goto("https://github.com/guidepup/guidepup", {
      waitUntil: "load",
    });

    // Wait for page to be ready
    const header = page.locator('header[role="banner"]');
    await header.waitFor();

    // Interact with the page
    await voiceOver.navigateToWebContent();

    // Move across the page menu to the Guidepup heading using VoiceOver
    while ((await voiceOver.itemText()) !== "Guidepup heading level 1") {
      await voiceOver.perform(voiceOver.keyboardCommands.findNextHeading);
    }

    // Assert that the spoken phrases are as expected
    expect(JSON.stringify(await voiceOver.spokenPhraseLog())).toMatchSnapshot();
  });
});

NVDA Example

playwright.config.ts:

import { devices, PlaywrightTestConfig } from "@playwright/test";
import { screenReaderConfig } from "@guidepup/playwright";

const config: PlaywrightTestConfig = {
  ...screenReaderConfig,
  reportSlowTests: null,
  timeout: 5 * 60 * 1000,
  retries: 2,
  projects: [
    {
      name: "firefox",
      use: { ...devices["Desktop Firefox"], headless: false },
    },
  ],
};

export default config;

nvda.spec.ts:

import { nvdaTest as test } from "@guidepup/playwright";
import { expect } from "@playwright/test";

test.describe("Playwright NVDA", () => {
  test("I can navigate the Guidepup Github page with NVDA", async ({
    page,
    nvda,
  }) => {
    // Navigate to Guidepup GitHub page
    await page.goto("https://github.com/guidepup/guidepup", {
      waitUntil: "load",
    });

    // Wait for page to be ready and setup
    const header = page.locator('header[role="banner"]');
    await header.waitFor();

    // Interact with the page
    await nvda.navigateToWebContent();

    // Move across the page menu to the Guidepup heading using NVDA
    while (
      !(await nvda.lastSpokenPhrase()).includes("Guidepup, heading, level 1")
    ) {
      await nvda.perform(nvda.keyboardCommands.moveToNextHeading);
    }

    // Assert that the spoken phrases are as expected
    expect(JSON.stringify(await nvda.spokenPhraseLog())).toMatchSnapshot();
  });
});

Powerful Tooling

Check out some of the other Guidepup modules:

• @guidepup/guidepup - Reliable automation for your screen reader a11y workflows through JavaScript supporting VoiceOver and NVDA.
• @guidepup/setup - Set up your local or CI environment for screen reader test automation.
• @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