@guidepup/playwright 0.16.3 → 0.18.0

package/README.md

@@ -1,8 +1,13 @@
-# Guidepup Playwright
+<div align="center">
+  <img align="center" alt="" height="120px" width="120px" src="https://github.com/guidepup/guidepup/raw/main/img/logo.png">
+  <h1 align="center">Guidepup for Playwright</h1>
+</div>
 
-<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>
+<div 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://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>
+</div>
 
 ## [Documentation](https://guidepup.dev) | [API Reference](https://www.guidepup.dev/docs/api/class-guidepup)
 
@@ -12,26 +17,21 @@
 [![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)
 [![Windows Server 2025 Support](https://img.shields.io/badge/windows_server-2025-blue.svg?logo=windows)](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2025)
 
-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>.
+Guidepup is a screen reader automation library for testing.
+
+This package provides [Guidepup](https://github.com/guidepup/guidepup) integration with [Playwright](https://playwright.dev/) to enable testing with <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.
 
-## Getting Started
+## Getting started
 
-Set up your environment for screen reader automation with [`@guidepup/setup`](https://github.com/guidepup/setup):
+Set up your machine for screen reader automation:
 
 ```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
+npx @guidepup/setup setup
 ```
 
 Install `@guidepup/playwright` to your project:
@@ -40,7 +40,14 @@ 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.
+> [!NOTE]
+> `@guidepup/guidepup` and `@playwright/test` are required as peer dependencies of this project.
+
+Install the Guidepup screen reader assets:
+
+```sh
+npx @guidepup/setup install
+```
 
 And get cracking with your first screen reader tests in Playwright!
 
@@ -48,11 +55,9 @@ And get cracking with your first screen reader tests in Playwright!
 
 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.
+You can also check out these [examples](https://github.com/guidepup/guidepup-playwright/tree/main/examples) to learn how you could use Guidepup with Playwright in your projects.
 
-### Playwright Config
+### Playwright config
 
 In your `playwright.config.ts` add the following for the best results with Guidepup for Screen Reader automation:
 
@@ -71,13 +76,13 @@ export default config;
 
 Check out the configuration this adds [in the `config.ts` file](./src/config.ts).
 
-### Web Content Navigation
+### 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()`.
+In addition to the Guidepup APIs the `screenReader`, `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:
+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:
 
 ```ts
 // Navigate to the desired page
@@ -89,7 +94,7 @@ await page.goto("https://github.com/guidepup/guidepup", {
 await page.locator('header[role="banner"]').waitFor();
 
 // Navigate to the web content
-await nvda.navigateToWebContent();
+await screenReader.navigateToWebContent();
 
 // ... some commands
 ```
@@ -100,15 +105,18 @@ await nvda.navigateToWebContent();
 // ... some commands
 
 // Store spoken phrases
-const spokenPhrases = await nvda.spokenPhraseLog();
+const spokenPhrases = await screenReader.spokenPhraseLog();
 
 // Navigate to the web content
-await nvda.navigateToWebContent();
+await screenReader.navigateToWebContent();
 
 // ... some commands
 
 // Collect all spoken phrases
-const allSpokenPhrases = [...spokenPhrases, ...(await nvda.spokenPhraseLog())];
+const allSpokenPhrases = [
+  ...spokenPhrases,
+  ...(await screenReader.spokenPhraseLog()),
+];
 
 // ... do something with spoken phrases
 ```
@@ -119,14 +127,22 @@ or pass a flag to prevent log clearing:
 // ... some commands
 
 // Navigate to the web content
-await nvda.navigateToWebContent(false);
+await screenReader.navigateToWebContent(false);
 
 // ... some commands
 ```
 
-### Providing Screen Reader Start Options
+### 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:
+The options provided to `screenReader.start([options])`, `nvda.start([options])`, or `voiceOver.start([options])` can be configured using `test.use(config)` as follows:
+
+```ts
+// Screen Reader Example
+import { screenReaderTest as test } from "@guidepup/playwright";
+
+// Capture all spoken phrases, including usage hints
+test.use({ screenReaderStartOptions: { capture: true } });
+```
 
 ```ts
 // VoiceOver Example
@@ -146,7 +162,7 @@ test.use({ nvdaStartOptions: { capture: true } });
 
 The default for VoiceOver and NVDA is set to `"initial"`. `true` captures all spoken phrases, including usage hints. `false` disables spoken phrase capture.
 
-### VoiceOver Example
+### VoiceOver example
 
 `playwright.config.ts`:
 
@@ -206,7 +222,7 @@ test.describe("Playwright VoiceOver", () => {
 });
 ```
 
-### NVDA Example
+### NVDA example
 
 `playwright.config.ts`:
 
@@ -268,7 +284,7 @@ test.describe("Playwright NVDA", () => {
 });
 ```
 
-## Powerful Tooling
+## Powerful tooling
 
 Check out some of the other Guidepup modules:
 

package/lib/delay.d.ts

@@ -0,0 +1 @@
+export declare function delay(ms: number): Promise<unknown>;

package/lib/delay.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delay = delay;
+async function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/lib/index.d.ts

@@ -1,5 +1,7 @@
 export { nvdaTest } from "./nvdaTest";
 export type { NVDAPlaywright } from "./nvdaTest";
 export { screenReaderConfig } from "./screenReaderConfig";
+export { screenReaderTest } from "./screenReaderTest";
+export type { ScreenReaderPlaywright } from "./screenReaderTest";
 export { voiceOverTest } from "./voiceOverTest";
 export type { VoiceOverPlaywright } from "./voiceOverTest";

package/lib/index.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.voiceOverTest = exports.screenReaderConfig = exports.nvdaTest = void 0;
+exports.voiceOverTest = exports.screenReaderTest = 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 screenReaderTest_1 = require("./screenReaderTest");
+Object.defineProperty(exports, "screenReaderTest", { enumerable: true, get: function () { return screenReaderTest_1.screenReaderTest; } });
 var voiceOverTest_1 = require("./voiceOverTest");
 Object.defineProperty(exports, "voiceOverTest", { enumerable: true, get: function () { return voiceOverTest_1.voiceOverTest; } });

package/lib/nvdaTest.d.ts

@@ -31,10 +31,8 @@ export interface NVDAPlaywright extends NVDA {
      * of the browser's web content.
      *
      * This command should be used after page navigation.
-     *
-     * Note: this command clears all logs by default.
      */
-    navigateToWebContent(clearLogs?: boolean): Promise<void>;
+    navigateToWebContent(options?: Pick<CommandOptions, "capture">): Promise<void>;
 }
 /**
  * These tests extend the default Playwright environment that launches the

package/lib/nvdaTest.js

@@ -4,6 +4,7 @@ exports.nvdaTest = void 0;
 const test_1 = require("@playwright/test");
 const guidepup_1 = require("@guidepup/guidepup");
 const applicationNameMap_1 = require("./applicationNameMap");
+const delay_1 = require("./delay");
 const nvdaPlaywright = guidepup_1.nvda;
 const MAX_APPLICATION_SWITCH_RETRY_COUNT = 10;
 const SWITCH_APPLICATION = {
@@ -37,7 +38,8 @@ const focusBrowser = async ({ applicationName, pageTitle, }) => {
     let applicationSwitchRetryCount = 0;
     while (applicationSwitchRetryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
         applicationSwitchRetryCount++;
-        await nvdaPlaywright.perform(SWITCH_APPLICATION);
+        await nvdaPlaywright.perform(SWITCH_APPLICATION, { capture: false });
+        await (0, delay_1.delay)(500);
         await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
         windowTitle = await nvdaPlaywright.lastSpokenPhrase();
         if (hasFocus({ applicationName, pageTitle, windowTitle })) {
@@ -59,17 +61,17 @@ exports.nvdaTest = test_1.test.extend({
             if (!applicationName) {
                 throw new Error(`Browser ${browserName} is not installed.`);
             }
-            await page.goto("about:blank", { waitUntil: "load" });
-            await page.bringToFront();
-            nvdaPlaywright.navigateToWebContent = async (clearLogs = true) => {
+            nvdaPlaywright.navigateToWebContent = async ({ capture } = {}) => {
+                const currentSpokenPhraseLog = [
+                    ...(await nvdaPlaywright.spokenPhraseLog()),
+                ];
+                const currentItemTextLog = [...(await nvdaPlaywright.itemTextLog())];
                 // Make sure NVDA is not in focus mode.
-                await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.exitFocusMode);
-                const pageTitle = await page.title();
+                await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.exitFocusMode, { capture: false });
+                await (0, delay_1.delay)(100);
                 // Ensure application is brought to front and focused.
-                await focusBrowser({
-                    applicationName,
-                    pageTitle,
-                });
+                const pageTitle = await page.title();
+                await focusBrowser({ applicationName, pageTitle });
                 // Ensure the document is ready and focused.
                 await page.bringToFront();
                 await page.locator("body").waitFor();
@@ -86,16 +88,23 @@ exports.nvdaTest = test_1.test.extend({
                 // 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);
-                if (clearLogs) {
-                    // Clear out logs.
-                    await nvdaPlaywright.clearItemTextLog();
-                    await nvdaPlaywright.clearSpokenPhraseLog();
-                }
+                await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.readNextFocusableItem, { capture: false });
+                await (0, delay_1.delay)(100);
+                await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.toggleBetweenBrowseAndFocusMode, { capture: false });
+                await (0, delay_1.delay)(100);
+                await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.toggleBetweenBrowseAndFocusMode, { capture: false });
+                await (0, delay_1.delay)(100);
+                await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.exitFocusMode, { capture: false });
+                await (0, delay_1.delay)(100);
+                await nvdaPlaywright.clearSpokenPhraseLog();
+                await nvdaPlaywright.clearItemTextLog();
+                const spokenPhraseLog = await nvdaPlaywright.spokenPhraseLog();
+                const itemTextLog = await nvdaPlaywright.itemTextLog();
+                spokenPhraseLog.push(...currentSpokenPhraseLog);
+                itemTextLog.push(...currentItemTextLog);
+                // Navigate to the beginning of the web content, using chosen capture
+                // settings, so don't miss announcing the first item on the page.
+                await nvdaPlaywright.perform(MOVE_TO_TOP, { capture });
             };
             await nvdaPlaywright.start(nvdaStartOptions);
             await use(nvdaPlaywright);

package/lib/screenReaderTest.d.ts

@@ -0,0 +1,76 @@
+import { CommandOptions, type ScreenReader } from "@guidepup/guidepup";
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type CaptureCommandOptions = Prettify<Pick<CommandOptions, "capture">>;
+/**
+ * This object can be used to launch and control the default screen reader for
+ * the environment.
+ *
+ * Here's a typical example:
+ *
+ * ```ts
+ * import { screenReader } from "@guidepup/guidepup";
+ *
+ * (async () => {
+ *   // Start the screen reader.
+ *   await screenReader.start();
+ *
+ *   // Move to the next item.
+ *   await screenReader.next();
+ *
+ *   // ... perform some commands.
+ *
+ *   // Stop the screen reader.
+ *   await screenReader.stop();
+ * })();
+ * ```
+ */
+export interface ScreenReaderPlaywright extends ScreenReader {
+    /**
+     * Guidepup Playwright specific command that navigates the screen reader to
+     * the beginning of the browser's web content.
+     *
+     * This command should be used after page navigation.
+     */
+    navigateToWebContent(options?: Pick<CommandOptions, "capture">): Promise<void>;
+}
+/**
+ * These tests extend the default Playwright environment that launches the
+ * browser with a running instance of the default screen reader for the current
+ * OS.
+ *
+ * A fresh started screen reader instance `screenReader` is provided to each
+ * test.
+ */
+export declare const screenReaderTest: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    /**
+     * This object can be used to launch and control the default screen reader for
+     * the environment.
+     *
+     * Here's a typical example:
+     *
+     * ```ts
+     * import { screenReader } from "@guidepup/guidepup";
+     *
+     * (async () => {
+     *   // Start the screen reader.
+     *   await screenReader.start();
+     *
+     *   // Move to the next item.
+     *   await screenReader.next();
+     *
+     *   // ... perform some commands.
+     *
+     *   // Stop the screen reader.
+     *   await screenReader.stop();
+     * })();
+     * ```
+     */
+    screenReader: ScreenReaderPlaywright;
+    /**
+     * Options to start the default screen reader with.
+     */
+    screenReaderStartOptions: CaptureCommandOptions;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export {};

package/lib/screenReaderTest.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.screenReaderTest = void 0;
+const test_1 = require("@playwright/test");
+const guidepup_1 = require("@guidepup/guidepup");
+const applicationNameMap_1 = require("./applicationNameMap");
+const delay_1 = require("./delay");
+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 cleanString = (str) => str
+    .toLowerCase()
+    // REF: https://github.com/nvaccess/nvda/blob/master/source/locale/en/symbols.dic
+    .replace(/[|¦:;'"`\-‐–—·_()[\]{}\\^~]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+const hasFocus = ({ applicationName, pageTitle, windowTitle, }) => {
+    const cleanedApplicationName = cleanString(applicationName);
+    const cleanedPageTitle = cleanString(pageTitle);
+    const cleanedWindowTitle = cleanString(windowTitle);
+    return ((cleanedPageTitle.length &&
+        cleanedWindowTitle.startsWith(cleanedPageTitle)) ||
+        cleanedWindowTitle.includes(cleanedApplicationName));
+};
+const focusBrowser = async ({ applicationName, pageTitle, }) => {
+    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.reportTitle);
+    let windowTitle = await screenReaderPlaywright.lastSpokenPhrase();
+    if (hasFocus({ applicationName, pageTitle, windowTitle })) {
+        return;
+    }
+    let applicationSwitchRetryCount = 0;
+    while (applicationSwitchRetryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
+        applicationSwitchRetryCount++;
+        await screenReaderPlaywright.perform(SWITCH_APPLICATION, {
+            capture: false,
+        });
+        await (0, delay_1.delay)(500);
+        await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.reportTitle);
+        windowTitle = await screenReaderPlaywright.lastSpokenPhrase();
+        if (hasFocus({ applicationName, pageTitle, windowTitle })) {
+            break;
+        }
+    }
+};
+const screenReaderPlaywright = guidepup_1.screenReader;
+/**
+ * These tests extend the default Playwright environment that launches the
+ * browser with a running instance of the default screen reader for the current
+ * OS.
+ *
+ * A fresh started screen reader instance `screenReader` is provided to each
+ * test.
+ */
+exports.screenReaderTest = test_1.test.extend({
+    screenReaderStartOptions: { capture: "initial" },
+    screenReader: async ({ browserName, page, screenReaderStartOptions }, use) => {
+        try {
+            const applicationName = applicationNameMap_1.applicationNameMap[browserName];
+            if (!applicationName) {
+                throw new Error(`Browser ${browserName} is not installed.`);
+            }
+            if (guidepup_1.nvda.default()) {
+                screenReaderPlaywright.navigateToWebContent = async ({ capture, } = {}) => {
+                    const currentSpokenPhraseLog = [
+                        ...(await screenReaderPlaywright.spokenPhraseLog()),
+                    ];
+                    const currentItemTextLog = [
+                        ...(await screenReaderPlaywright.itemTextLog()),
+                    ];
+                    // Make sure NVDA is not in focus mode.
+                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.exitFocusMode, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Ensure application is brought to front and focused.
+                    const pageTitle = await page.title();
+                    await focusBrowser({ applicationName, pageTitle });
+                    // Ensure the document is ready and focused.
+                    await page.bringToFront();
+                    await page.locator("body").waitFor();
+                    await page.locator("body").focus();
+                    await page.locator("body").click();
+                    await page.locator("body").blur();
+                    // 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 screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.readNextFocusableItem, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.toggleBetweenBrowseAndFocusMode, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.toggleBetweenBrowseAndFocusMode, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.exitFocusMode, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    await screenReaderPlaywright.clearSpokenPhraseLog();
+                    await screenReaderPlaywright.clearItemTextLog();
+                    const spokenPhraseLog = await screenReaderPlaywright.spokenPhraseLog();
+                    const itemTextLog = await screenReaderPlaywright.itemTextLog();
+                    spokenPhraseLog.push(...currentSpokenPhraseLog);
+                    itemTextLog.push(...currentItemTextLog);
+                    // Navigate to the beginning of the web content, using chosen capture
+                    // settings, so don't miss announcing the first item on the page.
+                    await screenReaderPlaywright.perform(MOVE_TO_TOP, { capture });
+                };
+            }
+            else if (guidepup_1.voiceOver.default()) {
+                screenReaderPlaywright.navigateToWebContent = async ({ capture, } = {}) => {
+                    // Ensure application is brought to front and focused.
+                    await (0, guidepup_1.macOSActivate)(applicationName);
+                    // Cancel auto navigation.
+                    await screenReaderPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Ensure the document is ready and focused.
+                    await page.bringToFront();
+                    await page.locator("body").waitFor();
+                    // Open the web item chooser.
+                    await screenReaderPlaywright.perform(guidepup_1.voiceOverKeyCodeCommands.openItemChooser, { capture: false });
+                    await (0, delay_1.delay)(500);
+                    // Filter by "web content" - currently web content items for all browsers
+                    // are suffixed by "web content".
+                    for (const character of "web content") {
+                        await screenReaderPlaywright.type(character, { capture: false });
+                        await (0, delay_1.delay)(100);
+                    }
+                    // Select the web content window spot.
+                    await screenReaderPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Enter }, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Navigate into web content.
+                    await screenReaderPlaywright.interact({ capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Navigate to the beginning of the web content.
+                    await screenReaderPlaywright.perform(guidepup_1.voiceOverKeyCodeCommands.moveToBeginningOfText, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Cancel auto navigation
+                    await screenReaderPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Navigate to the beginning of the web content, using chosen capture
+                    // settings, so don't miss announcing the first item on the page.
+                    await screenReaderPlaywright.perform(guidepup_1.voiceOverKeyCodeCommands.moveToBeginningOfText, { capture });
+                };
+            }
+            else {
+                throw new Error("No supported screen reader");
+            }
+            await screenReaderPlaywright.start(screenReaderStartOptions);
+            await use(screenReaderPlaywright);
+        }
+        finally {
+            try {
+                await screenReaderPlaywright.stop();
+            }
+            catch {
+                // swallow stop failure
+            }
+        }
+    },
+});

package/lib/voiceOverTest.d.ts

@@ -29,10 +29,8 @@ export interface VoiceOverPlaywright extends VoiceOver {
      * of the browser's web content.
      *
      * This command should be used after a page navigation has completed.
-     *
-     * Note: this command clears all logs by default.
      */
-    navigateToWebContent(clearLogs?: boolean): Promise<void>;
+    navigateToWebContent(options?: Pick<CommandOptions, "capture">): Promise<void>;
 }
 /**
  * These tests extend the default Playwright environment that launches the

package/lib/voiceOverTest.js

@@ -4,6 +4,7 @@ exports.voiceOverTest = void 0;
 const test_1 = require("@playwright/test");
 const guidepup_1 = require("@guidepup/guidepup");
 const applicationNameMap_1 = require("./applicationNameMap");
+const delay_1 = require("./delay");
 const voiceOverPlaywright = guidepup_1.voiceOver;
 /**
  * These tests extend the default Playwright environment that launches the
@@ -19,37 +20,41 @@ exports.voiceOverTest = test_1.test.extend({
             if (!applicationName) {
                 throw new Error(`Browser ${browserName} is not installed.`);
             }
-            voiceOverPlaywright.navigateToWebContent = async (clearLogs = true) => {
+            voiceOverPlaywright.navigateToWebContent = async ({ capture } = {}) => {
                 // Ensure application is brought to front and focused.
                 await (0, guidepup_1.macOSActivate)(applicationName);
-                // Cancel auto navigation
-                await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control });
+                // Cancel auto navigation.
+                await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
+                await (0, delay_1.delay)(100);
                 // Ensure the document is ready and focused.
                 await page.bringToFront();
                 await page.locator("body").waitFor();
                 // Open the web item chooser.
-                await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.openItemChooser);
+                await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.openItemChooser, { capture: false });
+                await (0, delay_1.delay)(500);
                 // Filter by "web content" - currently web content items for all browsers
                 // are suffixed by "web content".
-                await voiceOverPlaywright.type("web content");
+                for (const character of "web content") {
+                    await voiceOverPlaywright.type(character, { capture: false });
+                    await (0, delay_1.delay)(100);
+                }
                 // Select the web content window spot.
-                await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Enter });
+                await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Enter }, { capture: false });
+                await (0, delay_1.delay)(100);
                 // Navigate into web content.
-                await voiceOverPlaywright.interact();
+                await voiceOverPlaywright.interact({ capture: false });
+                await (0, delay_1.delay)(100);
                 // Navigate to the beginning of the web content.
-                await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.moveToBeginningOfText);
+                await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.moveToBeginningOfText, { capture: false });
+                await (0, delay_1.delay)(100);
                 // Cancel auto navigation
-                await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control });
-                if (clearLogs) {
-                    // Clear out logs.
-                    await voiceOverPlaywright.clearItemTextLog();
-                    await voiceOverPlaywright.clearSpokenPhraseLog();
-                }
+                await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
+                await (0, delay_1.delay)(100);
+                // Navigate to the beginning of the web content, using chosen capture
+                // settings, so don't miss announcing the first item on the page.
+                await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.moveToBeginningOfText, { capture });
             };
             await voiceOverPlaywright.start(voiceOverStartOptions);
-            await (0, guidepup_1.macOSActivate)(applicationName);
-            // Cancel auto navigation
-            await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
             await use(voiceOverPlaywright);
         }
         finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidepup/playwright",
-  "version": "0.16.3",
+  "version": "0.18.0",
   "description": "Screen reader automation library for Playwright testing. ",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -34,15 +34,17 @@
     "prepublish": "yarn build",
     "pretest": "npx playwright install chromium firefox webkit",
     "test:nvda": "yarn test:nvda:chromium && yarn test:nvda:firefox",
+    "test:screenreader": "yarn test:screenreader:chromium",
     "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:screenreader:chromium": "playwright test --config ./examples/playwright-screenreader/chromium.config.ts ./examples/playwright-screenreader/tests/chromium/",
     "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.25.0",
+    "@guidepup/guidepup": "^0.29.1",
     "@guidepup/record": "^0.1.0",
     "@playwright/test": "^1.60.0",
     "@types/node": "^24.10.1",
@@ -56,7 +58,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@guidepup/guidepup": ">=0.25.0",
+    "@guidepup/guidepup": ">=0.27.0",
     "@playwright/test": "^1.57.0"
   },
   "resolutions": {