feat!: OS agnostic screen reader instance (#40)

Author: cmorten

.github/workflows/test-screenreader.yml

@@ -0,0 +1,39 @@
+name: Test Screen Reader
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test-screenreader:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-14, macos-15, macos-26, windows-2022, windows-2025]
+        browser: [chromium]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+      - name: Guidepup Setup
+        uses: guidepup/setup-action@0.20.0
+        with:
+          record: true
+      - run: yarn install --frozen-lockfile
+      - run: yarn pretest
+      - run: yarn test:screenreader:${{ matrix.browser }}
+      - uses: actions/upload-artifact@v4
+        if: always()
+        continue-on-error: true
+        with:
+          name: artifacts-${{ matrix.os }}-${{ matrix.browser }}
+          path: |
+            **/test-results/**/*
+            **/recordings/**/*

examples/logIncludesExpectedPhrases.ts

@@ -1,12 +1,14 @@
 export const logIncludesExpectedPhrases = (
   log: string[],
-  expectedPhrases: string[]
+  expectedPhrases: string[],
 ) => {
   const failures: string[] = [];
 
   for (const expectedPhrase of expectedPhrases) {
-    const foundExpectedPhrase = !!log.find((logItem) =>
-      logItem.includes(expectedPhrase)
+    const foundExpectedPhrase = !!log.find(
+      (logItem) =>
+        logItem.includes(expectedPhrase) ||
+        logItem.replaceAll(/\s/g, "").includes(expectedPhrase),
     );
 
     if (!foundExpectedPhrase) {
@@ -16,7 +18,7 @@ export const logIncludesExpectedPhrases = (
 
   if (failures.length) {
     throw new Error(
-      `Did not find the following expected text:\n- ${failures.join("\n- ")}`
+      `Did not find the following expected text:\n- ${failures.join("\n- ")}`,
     );
   }
 };

examples/playwright-nvda/tests/chromium/chromium.spec.ts

@@ -8,7 +8,7 @@ import { nvdaTest as test } from "../../../../src";
 test.use({ nvdaStartOptions: { capture: "initial" } });
 
 test.describe("Chromium Playwright NVDA", () => {
-  test("I can navigate the Guidepup Github page", async ({
+  test("I can navigate the Guidepup documentation site", async ({
     browser,
     browserName,
     page,

examples/playwright-nvda/tests/firefox/firefox.spec.ts

@@ -8,7 +8,7 @@ import { nvdaTest as test } from "../../../../src";
 test.use({ nvdaStartOptions: { capture: "initial" } });
 
 test.describe("Firefox Playwright VoiceOver", () => {
-  test("I can navigate the Guidepup Github page", async ({
+  test("I can navigate the Guidepup documentation site", async ({
     browser,
     browserName,
     page,

examples/playwright-screenreader/README.md

@@ -0,0 +1,18 @@
+# Screen Reader Example
+
+An example demonstrating using Guidepup for testing the default screen reader automation with [Playwright](https://playwright.dev/).
+
+Run this example's test with the following from the root directory:
+
+```console
+npm run test
+```
+
+> Note: please ensure you have [setup you environment](https://www.guidepup.dev/docs/guides/automated-environment-setup) for NVDA or VoiceOver automation before running this example.
+
+## Test flow
+
+1. The test launches the browser using Playwright
+2. Navigates to the GitHub website
+3. Moves through the website using the default screen reader for the environment, controlled by Guidepup
+4. Traverses headings until the Guidepup heading in the README.md is found

examples/playwright-screenreader/chromium.config.ts

@@ -0,0 +1,18 @@
+import { devices, PlaywrightTestConfig } from "@playwright/test";
+import { screenReaderConfig } from "../../src";
+
+const config: PlaywrightTestConfig = {
+  ...screenReaderConfig,
+  reportSlowTests: null,
+  timeout: 5 * 60 * 1000,
+  retries: 1,
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"], headless: false },
+    },
+  ],
+  reporter: process.env.CI ? [["github"], ["html", { open: "never" }]] : "list",
+};
+
+export default config;

examples/playwright-screenreader/tests/chromium/chromium.spec.ts

@@ -0,0 +1,40 @@
+import { platform, release } from "os";
+import { headerNavigation } from "../headerNavigation";
+import { logIncludesExpectedPhrases } from "../../../logIncludesExpectedPhrases";
+import spokenPhraseSnapshot from "./chromium.spokenPhrase.snapshot.json";
+import { screenReaderTest as test } from "../../../../src";
+
+test.describe("Chromium Playwright Screen Reader", () => {
+  test("I can navigate the Guidepup documentation site", async ({
+    browser,
+    browserName,
+    page,
+    screenReader,
+  }) => {
+    const osName = platform();
+    const osVersion = release();
+    const browserVersion = browser.version();
+    const { retry } = test.info();
+
+    console.table({
+      osName,
+      osVersion,
+      browserName,
+      browserVersion,
+      retry,
+    });
+
+    await headerNavigation({ page, screenReader });
+
+    // Assert that we've ended up where we expected and what we were told on
+    // the way there is as expected.
+
+    const itemTextLog = await screenReader.itemTextLog();
+    const spokenPhraseLog = await screenReader.spokenPhraseLog();
+
+    console.log(JSON.stringify(itemTextLog, undefined, 2));
+    console.log(JSON.stringify(spokenPhraseLog, undefined, 2));
+
+    logIncludesExpectedPhrases(spokenPhraseLog, spokenPhraseSnapshot);
+  });
+});

examples/playwright-screenreader/tests/chromium/chromium.spokenPhrase.snapshot.json

@@ -0,0 +1 @@
+["Guidepup", "Docs", "API", "GitHub"]

examples/playwright-screenreader/tests/headerNavigation.ts

@@ -0,0 +1,50 @@
+import { log } from "../../log";
+import { Page } from "@playwright/test";
+import type { ScreenReaderPlaywright } from "../../../src";
+
+const MAX_NAVIGATION_LOOP = 10;
+
+export async function delay(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function headerNavigation({
+  page,
+  screenReader,
+}: {
+  page: Page;
+  screenReader: ScreenReaderPlaywright;
+}) {
+  // Navigate to Guidepup Website 🎉
+  log("Navigating to URL: https://www.guidepup.dev.");
+  await page.goto("https://www.guidepup.dev", {
+    waitUntil: "load",
+  });
+
+  // Wait for page to be ready and interact 🙌
+  const header = page.locator("h1");
+  await header.waitFor();
+  await delay(500);
+
+  // Make sure interacting with the web content
+  await screenReader.navigateToWebContent();
+  await delay(500);
+
+  let navigationCount = 0;
+
+  // Move across the content
+  while (
+    !(await screenReader.itemText()).replaceAll(/\s/g, "").includes("GitHub") &&
+    navigationCount <= MAX_NAVIGATION_LOOP
+  ) {
+    navigationCount++;
+
+    log(`Performing command: next`);
+    await screenReader.next();
+    log(`Screen reader output: "${await screenReader.lastSpokenPhrase()}".`);
+  }
+
+  log(`Performing command: act`);
+  await screenReader.act();
+  log(`Screen reader output: "${await screenReader.lastSpokenPhrase()}".`);
+}

examples/playwright-voiceover/tests/chromium/chromium.spec.ts

@@ -9,7 +9,7 @@ import { voiceOverTest as test } from "../../../../src";
 test.use({ voiceOverStartOptions: { capture: "initial" } });
 
 test.describe("Chromium Playwright VoiceOver", () => {
-  test("I can navigate the Guidepup Github page", async ({
+  test("I can navigate the Guidepup documentation site", async ({
     browser,
     browserName,
     page,