@guidepup/playwright 0.17.0 → 0.19.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,45 +94,23 @@ 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
 ```
 
-**Note:** This command clears all logs by default meaning `.spokenPhraseLog()` and `.itemTextLog()` are emptied. If logs from prior to the command are required, either store the logs in a variable for later use:
+### Providing screen reader start options
 
-```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
-```
-
-or pass a flag to prevent log clearing:
+The options provided to `screenReader.start([options])`, `nvda.start([options])`, or `voiceOver.start([options])` can be configured using `test.use(config)` as follows:
 
 ```ts
-// ... some commands
+// Screen Reader Example
+import { screenReaderTest as test } from "@guidepup/playwright";
 
-// Navigate to the web content
-await nvda.navigateToWebContent(false);
-
-// ... some commands
+// Capture all spoken phrases, including usage hints
+test.use({ screenReaderStartOptions: { capture: true } });
 ```
 
-### 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:
-
 ```ts
 // VoiceOver Example
 import { voiceOverTest as test } from "@guidepup/playwright";
@@ -146,7 +129,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`:
 
@@ -197,7 +180,7 @@ test.describe("Playwright VoiceOver", () => {
 
     // 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);
+      await voiceOver.nextHeading();
     }
 
     // Assert that the spoken phrases are as expected
@@ -206,7 +189,7 @@ test.describe("Playwright VoiceOver", () => {
 });
 ```
 
-### NVDA Example
+### NVDA example
 
 `playwright.config.ts`:
 
@@ -259,7 +242,7 @@ test.describe("Playwright NVDA", () => {
     while (
       !(await nvda.lastSpokenPhrase()).includes("Guidepup, heading, level 1")
     ) {
-      await nvda.perform(nvda.keyboardCommands.moveToNextHeading);
+      await nvda.nextHeading();
     }
 
     // Assert that the spoken phrases are as expected
@@ -268,7 +251,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/nvdaTest.d.ts

@@ -1,8 +1,9 @@
-import type { CommandOptions, NVDA } from "@guidepup/guidepup";
+import { type CommandOptions, type NVDA, type StartOptions } from "@guidepup/guidepup";
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
 type CaptureCommandOptions = Prettify<Pick<CommandOptions, "capture">>;
+type CaptureStartOptions = Prettify<Pick<StartOptions, "capture" | "settings">>;
 /**
  * [API Reference](https://www.guidepup.dev/docs/api/class-nvda)
  *
@@ -31,10 +32,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?: CaptureCommandOptions): Promise<void>;
 }
 /**
  * These tests extend the default Playwright environment that launches the
@@ -67,10 +66,10 @@ export declare const nvdaTest: import("@playwright/test").TestType<import("@play
      */
     nvda: NVDAPlaywright;
     /**
-     * [API Reference](https://www.guidepup.dev/docs/api/class-command-options)
+     * [API Reference](https://www.guidepup.dev/docs/api/class-start-options)
      *
      * Options to start NVDA with, see also [nvda.start([options])](https://www.guidepup.dev/docs/api/class-nvda#nvda-start).
      */
-    nvdaStartOptions: CaptureCommandOptions;
+    nvdaStartOptions: CaptureStartOptions;
 }, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
 export {};

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,15 +61,17 @@ exports.nvdaTest = test_1.test.extend({
             if (!applicationName) {
                 throw new Error(`Browser ${browserName} is not installed.`);
             }
-            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();
@@ -84,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

@@ -1,8 +1,9 @@
-import { CommandOptions, type ScreenReader } from "@guidepup/guidepup";
+import { type CommandOptions, type ScreenReader, type StartOptions } from "@guidepup/guidepup";
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
 type CaptureCommandOptions = Prettify<Pick<CommandOptions, "capture">>;
+type CaptureStartOptions = Prettify<Pick<StartOptions, "capture" | "settings">>;
 /**
  * This object can be used to launch and control the default screen reader for
  * the environment.
@@ -32,10 +33,8 @@ export interface ScreenReaderPlaywright extends ScreenReader {
      * the beginning 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?: CaptureCommandOptions): Promise<void>;
 }
 /**
  * These tests extend the default Playwright environment that launches the
@@ -73,6 +72,6 @@ export declare const screenReaderTest: import("@playwright/test").TestType<impor
     /**
      * Options to start the default screen reader with.
      */
-    screenReaderStartOptions: CaptureCommandOptions;
+    screenReaderStartOptions: CaptureStartOptions;
 }, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
 export {};

package/lib/screenReaderTest.js

@@ -4,6 +4,7 @@ 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],
@@ -36,7 +37,10 @@ const focusBrowser = async ({ applicationName, pageTitle, }) => {
     let applicationSwitchRetryCount = 0;
     while (applicationSwitchRetryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
         applicationSwitchRetryCount++;
-        await screenReaderPlaywright.perform(SWITCH_APPLICATION);
+        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 })) {
@@ -62,11 +66,18 @@ exports.screenReaderTest = test_1.test.extend({
                 throw new Error(`Browser ${browserName} is not installed.`);
             }
             if (guidepup_1.nvda.default()) {
-                screenReaderPlaywright.navigateToWebContent = async (clearLogs = true) => {
+                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);
-                    const pageTitle = await page.title();
+                    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();
@@ -84,39 +95,96 @@ exports.screenReaderTest = 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 screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.readNextFocusableItem);
-                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.toggleBetweenBrowseAndFocusMode);
-                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.toggleBetweenBrowseAndFocusMode);
-                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.exitFocusMode);
-                    await screenReaderPlaywright.perform(MOVE_TO_TOP);
-                    if (clearLogs) {
-                        // Clear out logs.
-                        await screenReaderPlaywright.clearItemTextLog();
-                        await screenReaderPlaywright.clearSpokenPhraseLog();
-                    }
+                    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 (clearLogs = true) => {
+                screenReaderPlaywright.navigateToWebContent = async ({ capture, } = {}) => {
+                    // Ensure application is brought to front and focused.
                     await (0, guidepup_1.macOSActivate)(applicationName);
-                    await screenReaderPlaywright.perform({
-                        keyCode: guidepup_1.MacOSKeyCodes.Control,
-                    });
+                    // 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();
-                    await screenReaderPlaywright.perform(guidepup_1.voiceOverKeyCodeCommands.openItemChooser);
-                    await screenReaderPlaywright.type("web content");
-                    await screenReaderPlaywright.perform({
-                        keyCode: guidepup_1.MacOSKeyCodes.Enter,
-                    });
-                    await screenReaderPlaywright.interact();
-                    await screenReaderPlaywright.perform(guidepup_1.voiceOverKeyCodeCommands.moveToBeginningOfText);
-                    await screenReaderPlaywright.perform({
-                        keyCode: guidepup_1.MacOSKeyCodes.Control,
-                    });
-                    if (clearLogs) {
-                        await screenReaderPlaywright.clearItemTextLog();
-                        await screenReaderPlaywright.clearSpokenPhraseLog();
+                    try {
+                        // Add an interactive marker to the page that will force VoiceOver
+                        // to listen to events emitted by Playwright interactions when
+                        // navigated to.
+                        await page.evaluate(() => {
+                            const marker = document.createElement("input");
+                            marker.id = "__guidepup_marker__";
+                            marker.type = "text";
+                            marker.value = "Guidepup Marker";
+                            marker.readOnly = true;
+                            marker.tabIndex = -1;
+                            marker.autocomplete = "off";
+                            marker.setAttribute("aria-label", "Guidepup Marker");
+                            marker.style.cssText = `
+                      position: absolute;
+                      width: 1px;
+                      height: 1px;
+                      overflow: hidden;
+                      clip: rect(0 0 0 0);
+                      white-space: nowrap;
+                    `;
+                            document.body.prepend(marker);
+                        });
+                        // 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 Guidepup marker element at beginning of the web
+                        // content.
+                        await screenReaderPlaywright.perform(guidepup_1.voiceOverKeyCodeCommands.moveToBeginningOfText, { capture: false });
+                        await (0, delay_1.delay)(100);
+                        // Navigate to the first element of the page using the provided
+                        // capture settings.
+                        await screenReaderPlaywright.next({ capture });
+                    }
+                    finally {
+                        // Remove the temporary Guidepup marker element to restore original
+                        // page structure.
+                        await page.evaluate(() => {
+                            const marker = document.querySelector("#__guidepup_marker__");
+                            if (marker) {
+                                document.body.removeChild(marker);
+                            }
+                        });
                     }
                 };
             }

package/lib/voiceOverTest.d.ts

@@ -1,4 +1,4 @@
-import type { CommandOptions, VoiceOver } from "@guidepup/guidepup";
+import type { StartOptions, CommandOptions, VoiceOver } from "@guidepup/guidepup";
 /**
  * [API Reference](https://www.guidepup.dev/docs/api/class-voiceover)
  *
@@ -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
@@ -67,9 +65,9 @@ export declare const voiceOverTest: import("@playwright/test").TestType<import("
      */
     voiceOver: VoiceOverPlaywright;
     /**
-     * [API Reference](https://www.guidepup.dev/docs/api/class-command-options)
+     * [API Reference](https://www.guidepup.dev/docs/api/class-start-options)
      *
      * Options to start VoiceOver with, see also [voiceOver.start([options])](https://www.guidepup.dev/docs/api/class-voiceover#voiceover-start).
      */
-    voiceOverStartOptions: CommandOptions;
+    voiceOverStartOptions: StartOptions;
 }, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;

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,31 +20,76 @@ 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);
-                // Filter by "web content" - currently web content items for all browsers
-                // are suffixed by "web content".
-                await voiceOverPlaywright.type("web content");
-                // Select the web content window spot.
-                await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Enter });
-                // Navigate into web content.
-                await voiceOverPlaywright.interact();
-                // Navigate to the beginning of the web content.
-                await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.moveToBeginningOfText);
-                // Cancel auto navigation
-                await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control });
-                if (clearLogs) {
-                    // Clear out logs.
-                    await voiceOverPlaywright.clearItemTextLog();
-                    await voiceOverPlaywright.clearSpokenPhraseLog();
+                try {
+                    // Add an interactive marker to the page that will force VoiceOver
+                    // to listen to events emitted by Playwright interactions when
+                    // navigated to.
+                    await page.evaluate(() => {
+                        const marker = document.createElement("input");
+                        marker.id = "__guidepup_marker__";
+                        marker.type = "text";
+                        marker.value = "Guidepup Marker";
+                        marker.readOnly = true;
+                        marker.tabIndex = -1;
+                        marker.autocomplete = "off";
+                        marker.setAttribute("aria-label", "Guidepup Marker");
+                        marker.style.cssText = `
+              position: absolute;
+              width: 1px;
+              height: 1px;
+              overflow: hidden;
+              clip: rect(0 0 0 0);
+              white-space: nowrap;
+            `;
+                        document.body.prepend(marker);
+                    });
+                    // Open the web item chooser.
+                    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".
+                    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 }, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Navigate into web content.
+                    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, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Cancel auto navigation
+                    await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Navigate to the Guidepup marker element at beginning of the web
+                    // content.
+                    await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.moveToBeginningOfText, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Navigate to the first element of the page using the provided
+                    // capture settings.
+                    await voiceOverPlaywright.next({ capture });
+                }
+                finally {
+                    // Remove the temporary Guidepup marker element to restore original
+                    // page structure.
+                    await page.evaluate(() => {
+                        const marker = document.querySelector("#__guidepup_marker__");
+                        if (marker) {
+                            document.body.removeChild(marker);
+                        }
+                    });
                 }
             };
             await voiceOverPlaywright.start(voiceOverStartOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidepup/playwright",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Screen reader automation library for Playwright testing. ",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -44,7 +44,7 @@
     "test:voiceover:webkit": "playwright test --config ./examples/playwright-voiceover/webkit.config.ts ./examples/playwright-voiceover/tests/webkit/"
   },
   "devDependencies": {
-    "@guidepup/guidepup": "^0.27.0",
+    "@guidepup/guidepup": "^0.33.0",
     "@guidepup/record": "^0.1.0",
     "@playwright/test": "^1.60.0",
     "@types/node": "^24.10.1",
@@ -58,7 +58,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@guidepup/guidepup": ">=0.27.0",
+    "@guidepup/guidepup": ">=0.33.0",
     "@playwright/test": "^1.57.0"
   },
   "resolutions": {