@guidepup/playwright 0.17.0 → 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/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,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

@@ -32,10 +32,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?: Pick<CommandOptions, "capture">): Promise<void>;
 }
 /**
  * These tests extend the default Playwright environment that launches the

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,40 +95,59 @@ 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();
+                    // 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 {

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,32 +20,39 @@ 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 use(voiceOverPlaywright);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidepup/playwright",
-  "version": "0.17.0",
+  "version": "0.18.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.29.1",
     "@guidepup/record": "^0.1.0",
     "@playwright/test": "^1.60.0",
     "@types/node": "^24.10.1",