@guidepup/playwright 0.12.0 → 0.13.1

package/README.md

@@ -1,46 +1,44 @@
-<h1 align="center">Guidepup Playwright</h1>
-<p align="center">
-  <i>Screen reader driver for Playwright tests.</i>
-</p>
-<p align="center">
-  <a href="https://www.npmjs.com/package/@guidepup/playwright"><img alt="@guidepup/playwright available on NPM" src="https://img.shields.io/npm/v/@guidepup/playwright" /></a>
-  <a href="https://www.npmjs.com/package/@guidepup/playwright"><img alt="@guidepup/playwright available on NPM" src="https://img.shields.io/npm/dt/@guidepup/playwright"></a>
-  <a href="https://github.com/guidepup/guidepup-playwright/actions/workflows/test.yml"><img alt="@guidepup/playwright test workflows" src="https://github.com/guidepup/guidepup-playwright/workflows/Test/badge.svg" /></a>
-  <a href="https://github.com/guidepup/guidepup-playwright/blob/main/LICENSE"><img alt="@guidepup/playwright uses the MIT license" src="https://img.shields.io/github/license/guidepup/guidepup-playwright" /></a>
-</p>
-<p align="center">
-  Reliable automation for your screen reader a11y workflows in Playwright supporting:
-</p>
-<p align="center">
-  <a href="https://www.guidepup.dev/docs/api/class-voiceover"><b>VoiceOver on MacOS</b></a>
-</p>
-<p align="center">
-  <b>NVDA on Windows</b> - <a href="https://github.com/guidepup/guidepup/pull/33">Coming Soon!</a>
-</p>
-
-## Intro
-
-A11y static analysis tools [only cover 25% of WCAG](https://karlgroves.com/web-accessibility-testing-what-can-be-tested-and-how/) and don't assure on the quality of the user experience for screen reader users. This means teams need to perform lots of manual tests with multiple screen readers to ensure great UX which can take a lot of time... **not anymore!**
-
-With [Guidepup](https://www.guidepup.dev/) you can automate your screen reader test workflows the same you as would for mouse or keyboard based scenarios, no sweat!
-
-## Quick Features
-
-- **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.
+# Guidepup Playwright
+
+<a href="https://www.npmjs.com/package/@guidepup/playwright"><img alt="@guidepup/playwright available on NPM" src="https://img.shields.io/npm/v/@guidepup/playwright" /></a>
+<a href="https://github.com/guidepup/guidepup-playwright/actions/workflows/test.yml"><img alt="@guidepup/playwright test workflows" src="https://github.com/guidepup/guidepup-playwright/workflows/Test/badge.svg" /></a>
+<a href="https://github.com/guidepup/guidepup-playwright/blob/main/LICENSE"><img alt="@guidepup/playwright uses the MIT license" src="https://img.shields.io/github/license/guidepup/guidepup-playwright" /></a>
+
+## [Documentation](https://guidepup.dev) | [API Reference](https://www.guidepup.dev/docs/api/class-guidepup)
+
+[![MacOS Big Sur Support](https://img.shields.io/badge/macos-Big_Sur-blue.svg?logo=apple)](https://apps.apple.com/id/app/macos-big-sur/id1526878132)
+[![MacOS Monetary Support](https://img.shields.io/badge/macos-Monetary-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-monterey/id1576738294)
+[![MacOS Ventura Support](https://img.shields.io/badge/macos-Ventura-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-ventura/id1638787999)
+[![Windows 10 Support](https://img.shields.io/badge/windows-10-blue.svg?logo=windows10)](https://www.microsoft.com/en-gb/software-download/windows10ISO)
+[![Windows Server 2019 Support](https://img.shields.io/badge/windows_server-2019-blue.svg?logo=windows)](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2019)
+[![Windows Server 2022 Support](https://img.shields.io/badge/windows_server-2022-blue.svg?logo=windows)](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2022)
+
+This package provides [Guidepup](https://github.com/guidepup/guidepup) integration with [Playwright](https://playwright.dev/) for writing screen reader tests that automate <a href="https://www.guidepup.dev/docs/api/class-voiceover"><b>VoiceOver on MacOS</b></a> and <a href="https://www.guidepup.dev/docs/api/class-nvda"><b>NVDA on Windows</b></a>.
+
+## 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`](https://github.com/guidepup/setup):
 
-```console
+```sh
 npx @guidepup/setup
 ```
 
+If you are using GitHub Actions, check out the dedicated [`guidepup/setup-action`](https://github.com/marketplace/actions/guidepup-setup):
+
+```yaml
+- name: Setup Environment
+  uses: guidepup/setup-action
+```
+
 Install `@guidepup/playwright` to your project:
 
-```console
+```sh
 npm install --save-dev @guidepup/playwright @guidepup/guidepup @playwright/test
 ```
 
@@ -48,80 +46,206 @@ Note: you require `@guidepup/guidepup` and `@playwright/test` as they are peer d
 
 And get cracking with your first screen reader tests in Playwright!
 
+## Examples
+
+Head over to the [Guidepup Website](https://www.guidepup.dev/) for guides, real world examples, environment setup, and complete API documentation with examples.
+
+You can also check out these [awesome examples](https://github.com/guidepup/guidepup/tree/main/examples) to learn how you could use Guidepup with Playwright in your projects.
+
+Alternatively check out [this project](https://github.com/guidepup/aria-at-tests) which runs several thousand tests to assert screen reader compatibility against [W3C ARIA-AT](https://github.com/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:
+
+```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](./src/config.ts).
+
+### 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:
+
+```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
-import { voTest as test } from "@guidepup/playwright";
+// ... some commands
+
+// Store spoken phrases
+const spokenPhrases = await nvda.spokenPhraseLog();
+
+// Navigate to the web content
+await nvda.navigateToWebContent();
+
+// ... some commands
+
+// Collect all spoken phrasees
+const allSpokenPhrases = [...spokenPhrases, ...(await nvda.spokenPhraseLog())];
+
+// ... do something with spoken phrases
+```
+
+### VoiceOver Example
+
+`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", async ({
+  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: "domcontentloaded",
+      waitUntil: "load",
     });
 
-    // Wait for page to be ready and interact
-    await expect(page.locator('header[role="banner"]')).toBeVisible();
-    await voiceOver.interact();
+    // 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.keyboard.commands.findNextHeading);
+      await voiceOver.perform(voiceOver.keyboardCommands.findNextHeading);
     }
+
+    // Assert that the spoken phrases are as expected
+    expect(JSON.stringify(await voiceOver.spokenPhraseLog())).toMatchSnapshot();
+  });
 });
 ```
 
-## Playwright Config
+### NVDA Example
 
-In your `playwright.config.ts` add the following for the best results with
-Guidepup for VoiceOver automation.
+`playwright.config.ts`:
 
 ```ts
 import { devices, PlaywrightTestConfig } from "@playwright/test";
-import { voConfig } from "@guidepup/playwright";
+import { screenReaderConfig } from "@guidepup/playwright";
 
 const config: PlaywrightTestConfig = {
-  ...voConfig,
-
-  // Your custom config ...
+  ...screenReaderConfig,
+  reportSlowTests: null,
+  timeout: 5 * 60 * 1000,
+  retries: 2,
+  projects: [
+    {
+      name: "firefox",
+      use: { ...devices["Desktop Firefox"], headless: false },
+    },
+  ],
 };
 
 export default config;
 ```
 
-Check out the configuration this adds [in the voConfig.ts file](./src/voConfig.ts).
-
-## Environment Setup
+`nvda.spec.ts`:
 
-Set up your environment for screen-read automation with [`@guidepup/setup`](https://github.com/guidepup/setup):
-
-```console
-npx @guidepup/setup
-```
+```ts
+import { nvdaTest as test } from "@guidepup/playwright";
+import { expect } from "@playwright/test";
 
-If you are using GitHub Actions, check out the dedicated [`guidepup/setup-action`](https://github.com/marketplace/actions/guidepup-setup):
+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",
+    });
 
-```yaml
-- name: Setup Environment
-  uses: guidepup/setup-action@0.13.0
-```
+    // Wait for page to be ready and setup
+    const header = page.locator('header[role="banner"]');
+    await header.waitFor();
 
-## Documentation
+    // Interact with the page
+    await nvda.navigateToWebContent();
 
-Head over to the [Guidepup Website](https://www.guidepup.dev/) for guides, real world examples, environment setup, and complete Guidepup API documentation with examples.
+    // 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);
+    }
 
-## Example
+    // Assert that the spoken phrases are as expected
+    expect(JSON.stringify(await nvda.spokenPhraseLog())).toMatchSnapshot();
+  });
+});
+```
 
-Check out [this cross-browser VoiceOver example](./example/).
+## Powerful Tooling
 
-## See Also
+Check out some of the other Guidepup modules:
 
-Checkout the core [`@guidepup/guidepup`](https://github.com/guidepup/guidepup)
-project to learn more about how you can automate your screen reader workflows
-using Guidepup.
+- [`@guidepup/guidepup`](https://github.com/guidepup/guidepup/) - Reliable automation for your screen reader a11y workflows through JavaScript supporting VoiceOver and NVDA.
+- [`@guidepup/setup`](https://github.com/guidepup/setup/) - Set up your local or CI environment for screen reader test automation.
+- [`@guidepup/virtual-screen-reader`](https://github.com/guidepup/virtual-screen-reader/) - Reliable unit testing for your screen reader a11y workflows.
+- [`@guidepup/jest`](https://github.com/guidepup/jest/) - Jest matchers for reliable unit testing of your screen reader a11y workflows.
 
-## License
+## Resources
 
-[MIT](https://github.com/guidepup/guidepup/blob/main/LICENSE)
+- [Documentation](https://www.guidepup.dev/docs/example)
+- [API Reference](https://www.guidepup.dev/docs/api/class-guidepup)
+- [Contributing](.github/CONTRIBUTING.md)
+- [Changelog](https://github.com/guidepup/guidepup-playwright/releases)
+- [MIT License](https://github.com/guidepup/guidepup-playwright/blob/main/LICENSE)

package/lib/applicationNameMap.d.ts

@@ -0,0 +1,10 @@
+export declare const applicationNameMap: {
+    chromium: string;
+    chrome: string;
+    "chrome-beta": string;
+    msedge: string;
+    "msedge-beta": string;
+    "msedge-dev": string;
+    firefox: string;
+    webkit: string;
+};

package/lib/applicationNameMap.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applicationNameMap = void 0;
+exports.applicationNameMap = {
+    chromium: "Chromium",
+    chrome: "Google Chrome",
+    "chrome-beta": "Google Chrome Beta",
+    msedge: "Microsoft Edge",
+    "msedge-beta": "Microsoft Edge Beta",
+    "msedge-dev": "Microsoft Edge Dev",
+    firefox: "Nightly",
+    webkit: "Playwright",
+};

package/lib/index.d.ts

@@ -1,2 +1,5 @@
-export { voTest } from "./voTest";
-export { voConfig } from "./voConfig";
+export { nvdaTest } from "./nvdaTest";
+export type { NVDAPlaywright } from "./nvdaTest";
+export { screenReaderConfig } from "./screenReaderConfig";
+export { voiceOverTest } from "./voiceOverTest";
+export type { VoiceOverPlaywright } from "./voiceOverTest";

package/lib/index.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.voConfig = exports.voTest = void 0;
-var voTest_1 = require("./voTest");
-Object.defineProperty(exports, "voTest", { enumerable: true, get: function () { return voTest_1.voTest; } });
-var voConfig_1 = require("./voConfig");
-Object.defineProperty(exports, "voConfig", { enumerable: true, get: function () { return voConfig_1.voConfig; } });
+exports.voiceOverTest = exports.screenReaderConfig = exports.nvdaTest = void 0;
+var nvdaTest_1 = require("./nvdaTest");
+Object.defineProperty(exports, "nvdaTest", { enumerable: true, get: function () { return nvdaTest_1.nvdaTest; } });
+var screenReaderConfig_1 = require("./screenReaderConfig");
+Object.defineProperty(exports, "screenReaderConfig", { enumerable: true, get: function () { return screenReaderConfig_1.screenReaderConfig; } });
+var voiceOverTest_1 = require("./voiceOverTest");
+Object.defineProperty(exports, "voiceOverTest", { enumerable: true, get: function () { return voiceOverTest_1.voiceOverTest; } });

package/lib/nvdaTest.d.ts

@@ -0,0 +1,65 @@
+import type { NVDA } from "@guidepup/guidepup";
+/**
+ * [API Reference](https://www.guidepup.dev/docs/api/class-nvda)
+ *
+ * This object can be used to launch and control NVDA.
+ *
+ * Here's a typical example:
+ *
+ * ```ts
+ * import { nvda } from "@guidepup/guidepup";
+ *
+ * (async () => {
+ *   // Start NVDA.
+ *   await nvda.start();
+ *
+ *   // Move to the next item.
+ *   await nvda.next();
+ *
+ *   // Stop NVDA.
+ *   await nvda.stop();
+ * })();
+ * ```
+ */
+export interface NVDAPlaywright extends NVDA {
+    /**
+     * Guidepup Playwright specific command that navigates NVDA to the beginning
+     * of the browser's web content.
+     *
+     * This command should be used after page navigation.
+     *
+     * Note: this command clears all logs.
+     */
+    navigateToWebContent(): Promise<void>;
+}
+/**
+ * These tests extend the default Playwright environment that launches the
+ * browser with a running instance of the NVDA screen reader for Windows.
+ *
+ * A fresh started NVDA instance `nvda` is provided to each test.
+ */
+export declare const nvdaTest: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    /**
+     * [API Reference](https://www.guidepup.dev/docs/api/class-nvda)
+     *
+     * This object can be used to launch and control NVDA.
+     *
+     * Here's a typical example:
+     *
+     * ```ts
+     * import { nvda } from "@guidepup/guidepup";
+     *
+     * (async () => {
+     *   // Start NVDA.
+     *   await nvda.start();
+     *
+     *   // Move to the next item.
+     *   await nvda.next();
+     *
+     *   // Stop NVDA.
+     *   await nvda.stop();
+     * })();
+     * ```
+     */
+    nvda: NVDAPlaywright;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;

package/lib/nvdaTest.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nvdaTest = void 0;
+const test_1 = require("@playwright/test");
+const guidepup_1 = require("@guidepup/guidepup");
+const applicationNameMap_1 = require("./applicationNameMap");
+const nvdaPlaywright = guidepup_1.nvda;
+const MAX_APPLICATION_SWITCH_RETRY_COUNT = 10;
+const SWITCH_APPLICATION = {
+    keyCode: [guidepup_1.WindowsKeyCodes.Escape],
+    modifiers: [guidepup_1.WindowsModifiers.Alt],
+};
+const MOVE_TO_TOP = {
+    keyCode: [guidepup_1.WindowsKeyCodes.Home],
+    modifiers: [guidepup_1.WindowsModifiers.Control],
+};
+const focusBrowser = async ({ applicationName, }) => {
+    await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
+    let windowTitle = await nvdaPlaywright.lastSpokenPhrase();
+    if (windowTitle.includes(applicationName)) {
+        return;
+    }
+    let applicationSwitchRetryCount = 0;
+    while (applicationSwitchRetryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
+        applicationSwitchRetryCount++;
+        await nvdaPlaywright.perform(SWITCH_APPLICATION);
+        await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
+        windowTitle = await nvdaPlaywright.lastSpokenPhrase();
+        if (windowTitle.includes(applicationName)) {
+            break;
+        }
+    }
+};
+/**
+ * These tests extend the default Playwright environment that launches the
+ * browser with a running instance of the NVDA screen reader for Windows.
+ *
+ * A fresh started NVDA instance `nvda` is provided to each test.
+ */
+exports.nvdaTest = test_1.test.extend({
+    nvda: async ({ browserName, page }, use) => {
+        try {
+            const applicationName = applicationNameMap_1.applicationNameMap[browserName];
+            if (!applicationName) {
+                throw new Error(`Browser ${browserName} is not installed.`);
+            }
+            await page.goto("about:blank", { waitUntil: "load" });
+            await page.bringToFront();
+            nvdaPlaywright.navigateToWebContent = async () => {
+                // Make sure NVDA is not in focus mode.
+                await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.exitFocusMode);
+                // Ensure application is brought to front and focused.
+                await focusBrowser({ applicationName });
+                // NVDA appears to not work well with Firefox when switching between
+                // applications resulting in the entire browser window having NVDA focus
+                // with focus mode.
+                //
+                // One workaround is to tab to the next focusable item. From there we can
+                // toggle into (yes although we are already in it...) focus mode and back
+                // out. In case this ever transpires to not happen as expect, we then ensure
+                // we exit focus mode and move NVDA to the top of the page.
+                //
+                // REF: https://github.com/nvaccess/nvda/issues/5758
+                await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.readNextFocusableItem);
+                await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.toggleBetweenBrowseAndFocusMode);
+                await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.toggleBetweenBrowseAndFocusMode);
+                await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.exitFocusMode);
+                await nvdaPlaywright.perform(MOVE_TO_TOP);
+                // Clear out logs.
+                await nvdaPlaywright.clearItemTextLog();
+                await nvdaPlaywright.clearSpokenPhraseLog();
+            };
+            await nvdaPlaywright.start();
+            await use(nvdaPlaywright);
+        }
+        finally {
+            try {
+                await nvdaPlaywright.stop();
+            }
+            catch {
+                // swallow stop failure
+            }
+        }
+    },
+});

package/lib/screenReaderConfig.d.ts

@@ -0,0 +1,6 @@
+import { PlaywrightTestConfig } from "@playwright/test";
+export type ScreenReaderPlaywrightTestConfig = PlaywrightTestConfig;
+/**
+ * Minimal required configuration for Screen Reader tests in Playwright.
+ */
+export declare const screenReaderConfig: ScreenReaderPlaywrightTestConfig;

package/lib/screenReaderConfig.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.screenReaderConfig = void 0;
+/**
+ * Minimal required configuration for Screen Reader tests in Playwright.
+ */
+exports.screenReaderConfig = {
+    /**
+     * We can only run a single instance of Screen Readers, so we must run a
+     * single test at a time.
+     */
+    workers: 1,
+    /**
+     * We can't parallelize Screen Reader tests as they are singletons, you can't
+     * start multiple instances at once.
+     */
+    fullyParallel: false,
+    use: {
+        /**
+         * Screen Readers don't work against headless browsers.
+         */
+        headless: false,
+    },
+};

package/lib/voiceOverTest.d.ts

@@ -0,0 +1,69 @@
+import type { VoiceOver } from "@guidepup/guidepup";
+/**
+ * [API Reference](https://www.guidepup.dev/docs/api/class-voiceover)
+ *
+ * This object can be used to launch and control VoiceOver.
+ *
+ * Here's a typical example:
+ *
+ * ```ts
+ * import { voiceOver } from "@guidepup/guidepup";
+ *
+ * (async () => {
+ *   // Start VoiceOver.
+ *   await voiceOver.start();
+ *
+ *   // Move to the next item.
+ *   await voiceOver.next();
+ *
+ *   // ... perform some commands.
+ *
+ *   // Stop VoiceOver.
+ *   await voiceOver.stop();
+ * })();
+ * ```
+ */
+export interface VoiceOverPlaywright extends VoiceOver {
+    /**
+     * Guidepup Playwright specific command that navigates VoiceOver to the beginning
+     * of the browser's web content.
+     *
+     * This command should be used after page navigation.
+     *
+     * Note: this command clears all logs.
+     */
+    navigateToWebContent(): Promise<void>;
+}
+/**
+ * These tests extend the default Playwright environment that launches the
+ * browser with a running instance of the VoiceOver screen reader for MacOS.
+ *
+ * A fresh started VoiceOver instance `voiceOver` is provided to each test.
+ */
+export declare const voiceOverTest: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    /**
+     * [API Reference](https://www.guidepup.dev/docs/api/class-voiceover)
+     *
+     * This object can be used to launch and control VoiceOver.
+     *
+     * Here's a typical example:
+     *
+     * ```ts
+     * import { voiceOver } from "@guidepup/guidepup";
+     *
+     * (async () => {
+     *   // Start VoiceOver.
+     *   await voiceOver.start();
+     *
+     *   // Move to the next item.
+     *   await voiceOver.next();
+     *
+     *   // ... perform some commands.
+     *
+     *   // Stop VoiceOver.
+     *   await voiceOver.stop();
+     * })();
+     * ```
+     */
+    voiceOver: VoiceOverPlaywright;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;

package/lib/voiceOverTest.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.voiceOverTest = void 0;
+const test_1 = require("@playwright/test");
+const guidepup_1 = require("@guidepup/guidepup");
+const applicationNameMap_1 = require("./applicationNameMap");
+const voiceOverPlaywright = guidepup_1.voiceOver;
+/**
+ * These tests extend the default Playwright environment that launches the
+ * browser with a running instance of the VoiceOver screen reader for MacOS.
+ *
+ * A fresh started VoiceOver instance `voiceOver` is provided to each test.
+ */
+exports.voiceOverTest = test_1.test.extend({
+    voiceOver: async ({ browserName, page }, use) => {
+        try {
+            const applicationName = applicationNameMap_1.applicationNameMap[browserName];
+            if (!applicationName) {
+                throw new Error(`Browser ${browserName} is not installed.`);
+            }
+            voiceOverPlaywright.navigateToWebContent = async () => {
+                // Ensure application is brought to front and focused.
+                await (0, guidepup_1.macOSActivate)(applicationName);
+                // Ensure the document is ready and focused.
+                await page.bringToFront();
+                await page.locator("body").waitFor();
+                await page.locator("body").focus();
+                // Navigate to the beginning of the web content.
+                await voiceOverPlaywright.interact();
+                await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.jumpToLeftEdge);
+                // Clear out logs.
+                await voiceOverPlaywright.clearItemTextLog();
+                await voiceOverPlaywright.clearSpokenPhraseLog();
+            };
+            await voiceOverPlaywright.start();
+            await (0, guidepup_1.macOSActivate)(applicationName);
+            await use(voiceOverPlaywright);
+        }
+        finally {
+            try {
+                await voiceOverPlaywright.stop();
+            }
+            catch {
+                // swallow stop failure
+            }
+        }
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidepup/playwright",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Screen reader driver for Playwright tests.",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -24,33 +24,36 @@
   "scripts": {
     "build": "yarn clean && yarn compile",
     "ci": "yarn clean && yarn lint && yarn build",
-    "clean": "rimraf lib",
+    "clean": "rimraf lib test-results recordings",
     "compile": "tsc",
     "lint": "eslint . --ext .ts",
     "lint:fix": "yarn lint --fix",
     "prepublish": "yarn build",
     "pretest": "npx playwright install chromium firefox webkit",
-    "test": "yarn test:chromium && yarn test:firefox && yarn test:webkit",
-    "test:chromium": "playwright test --config ./example/chromium.config.ts ./example/tests/chromium/",
-    "test:firefox": "playwright test --config ./example/firefox.config.ts ./example/tests/firefox/",
-    "test:webkit": "playwright test --config ./example/webkit.config.ts ./example/tests/webkit/"
+    "test:nvda": "yarn test:nvda:chromium && yarn test:nvda:firefox",
+    "test:voiceover": "yarn test:voiceover:chromium && yarn test:voiceover:firefox && yarn test:voiceover:webkit",
+    "test:nvda:chromium": "playwright test --config ./examples/playwright-nvda/chromium.config.ts ./examples/playwright-nvda/tests/chromium/",
+    "test:nvda:firefox": "playwright test --config ./examples/playwright-nvda/firefox.config.ts ./examples/playwright-nvda/tests/firefox/",
+    "test:voiceover:chromium": "playwright test --config ./examples/playwright-voiceover/chromium.config.ts ./examples/playwright-voiceover/tests/chromium/",
+    "test:voiceover:firefox": "playwright test --config ./examples/playwright-voiceover/firefox.config.ts ./examples/playwright-voiceover/tests/firefox/",
+    "test:voiceover:webkit": "playwright test --config ./examples/playwright-voiceover/webkit.config.ts ./examples/playwright-voiceover/tests/webkit/"
   },
   "devDependencies": {
-    "@guidepup/guidepup": "^0.21.0",
+    "@guidepup/guidepup": "^0.22.0",
     "@playwright/test": "^1.40.1",
-    "@types/node": "^20.10.5",
-    "@typescript-eslint/eslint-plugin": "^6.16.0",
-    "@typescript-eslint/parser": "^6.16.0",
+    "@types/node": "^20.10.6",
+    "@typescript-eslint/eslint-plugin": "^6.18.0",
+    "@typescript-eslint/parser": "^6.18.0",
     "eslint": "^8.56.0",
     "eslint-config-prettier": "^9.1.0",
     "rimraf": "^5.0.5",
     "ts-node": "^10.9.2",
-    "typedoc": "^0.25.4",
+    "typedoc": "^0.25.6",
     "typescript": "^5.3.3"
   },
   "peerDependencies": {
-    "@guidepup/guidepup": "^0.21.0",
-    "@playwright/test": "^1.29.2"
+    "@guidepup/guidepup": "^0.22.0",
+    "@playwright/test": "^1.40.1"
   },
   "resolutions": {
     "strip-ansi": "6.0.1",

package/lib/voConfig.d.ts

@@ -1,6 +0,0 @@
-import { PlaywrightTestConfig } from "@playwright/test";
-export type VoiceOverPlaywrightTestConfig = PlaywrightTestConfig;
-/**
- * Minimal required configuration for VoiceOver tests in Playwright.
- */
-export declare const voConfig: VoiceOverPlaywrightTestConfig;

package/lib/voConfig.js

@@ -1,20 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.voConfig = void 0;
-/**
- * Minimal required configuration for VoiceOver tests in Playwright.
- */
-exports.voConfig = {
-    /**
-     * We can only run a single instance of VoiceOver, so we must run a single
-     * test at a time.
-     */
-    workers: 1,
-    use: {
-        /**
-         * Although VoiceOver can interact with headless applications, not all
-         * behaviours work as expected.
-         */
-        headless: false,
-    },
-};

package/lib/voTest.d.ts

@@ -1,11 +0,0 @@
-import type { VoiceOver } from "@guidepup/guidepup";
-/**
- * These tests extend the default Playwright environment that launches the
- * browser with a running instance of the VoiceOver screen reader for MacOS.
- *
- * A fresh started VoiceOver instance `vo` is provided to each test.
- */
-declare const voTest: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
-    voiceOver: VoiceOver;
-}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
-export { voTest };

package/lib/voTest.js

@@ -1,39 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.voTest = void 0;
-const test_1 = require("@playwright/test");
-const guidepup_1 = require("@guidepup/guidepup");
-const applicationNameMap = {
-    chromium: "Chromium",
-    chrome: "Google Chrome",
-    "chrome-beta": "Google Chrome Beta",
-    msedge: "Microsoft Edge",
-    "msedge-beta": "Microsoft Edge Beta",
-    "msedge-dev": "Microsoft Edge Dev",
-    firefox: "Nightly",
-    webkit: "Playwright",
-};
-/**
- * These tests extend the default Playwright environment that launches the
- * browser with a running instance of the VoiceOver screen reader for MacOS.
- *
- * A fresh started VoiceOver instance `vo` is provided to each test.
- */
-const voTest = test_1.test.extend({
-    voiceOver: async ({ browserName }, use) => {
-        try {
-            await guidepup_1.voiceOver.start();
-            await (0, guidepup_1.macOSActivate)(applicationNameMap[browserName]);
-            await use(guidepup_1.voiceOver);
-        }
-        finally {
-            try {
-                await guidepup_1.voiceOver.stop();
-            }
-            catch {
-                // swallow stop failure
-            }
-        }
-    },
-});
-exports.voTest = voTest;