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.

Getting Started

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

``sh
npx @guidepup/setup
`

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

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

Install @guidepup/playwright to your project:

`sh
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.

$3

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

`ts
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.

$3

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:

`ts
// 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:

`ts
// ... 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
`

$3

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

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

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

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

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

$3

playwright.config.ts:

`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:

`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();
});
});
`

$3

playwright.config.ts:

`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:

`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