@guidepup/playwright 0.19.1 → 0.20.0

package/README.md

@@ -11,15 +11,18 @@
 
 ## [Documentation](https://guidepup.dev) | [API Reference](https://www.guidepup.dev/docs/api/class-guidepup)
 
-[![MacOS Sonoma Support](https://img.shields.io/badge/macos-Somona-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-sonoma/id6450717509)
-[![MacOS Sequoia Support](https://img.shields.io/badge/macos-Sequoia-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-sequoia/id6596773750)
-[![MacOS Tahoe Support](https://img.shields.io/badge/macos-Tahoe-blue.svg?logo=apple)](https://www.apple.com/uk/os/macos/)
+[![macOS Sonoma Support](https://img.shields.io/badge/macos-Sonoma-blue.svg?logo=apple)](https://support.apple.com/en-gb/102662)
+[![macOS Sequoia Support](https://img.shields.io/badge/macos-Sequoia-blue.svg?logo=apple)](https://support.apple.com/en-gb/102662)
+[![macOS Tahoe Support](https://img.shields.io/badge/macos-Tahoe-blue.svg?logo=apple)](https://support.apple.com/en-gb/102662)
+[![macOS Golden Gate Support](https://img.shields.io/badge/macos-Golden%20Gate-blue.svg?logo=apple)](https://support.apple.com/en-gb/127455)
 [![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)
+[![Ubuntu Resolute Support](https://img.shields.io/badge/ubuntu-26.04%2B-blue.svg?logo=ubuntu)](https://releases.ubuntu.com/resolute/)
+[![Debian Trixie Support](https://img.shields.io/badge/debian-13%2B-blue.svg?logo=debian)](https://www.debian.org/releases/trixie/)
 
 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>.
+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-nvda"><b>NVDA on Windows</b></a>, <a href="https://www.guidepup.dev/docs/api/class-orca"><b>Orca on Linux</b></a>, and <a href="https://www.guidepup.dev/docs/api/class-voiceover"><b>VoiceOver on macOS</b></a>.
 
 ## Capabilities
 
@@ -62,23 +65,21 @@ You can also check out these [examples](https://github.com/guidepup/guidepup-pla
 In your `playwright.config.ts` add the following for the best results with Guidepup for Screen Reader automation:
 
 ```ts
-import { devices, PlaywrightTestConfig } from "@playwright/test";
-import { screenReaderConfig } from "@guidepup/playwright";
-
-const config: PlaywrightTestConfig = {
-  ...screenReaderConfig,
+import { withGuidepup } from "@guidepup/playwright";
 
+export default withGuidepup({
   // ... your custom config
-};
-
-export default config;
+});
 ```
 
-Check out the configuration this adds [in the `config.ts` file](./src/config.ts).
+`withGuidepup` configures Playwright to run tests serially and forces headed
+browsers, including when browser options are specified in individual projects.
+The existing `screenReaderConfig` export remains available if you prefer to
+spread the configuration manually.
 
 ### Web content navigation
 
-In addition to the Guidepup APIs the `screenReader`, `voiceOver`, and `nvda` instances provided by the Guidepup Playwright setup have an additional utility method `.navigateToWebContent()`.
+In addition to the Guidepup APIs the `screenReader`, `nvda`, `orca`, and `voiceOver` 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.
 
@@ -101,7 +102,7 @@ await screenReader.navigateToWebContent();
 
 ### Providing screen reader start options
 
-The options provided to `screenReader.start([options])`, `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])`, `orca.start([options])`, or `voiceOver.start([options])` can be configured using `test.use(config)` as follows:
 
 ```ts
 // Screen Reader Example
@@ -112,119 +113,121 @@ test.use({ screenReaderStartOptions: { capture: true } });
 ```
 
 ```ts
-// VoiceOver Example
-import { voiceOverTest as test } from "@guidepup/playwright";
+// NVDA Example
+import { nvdaTest as test } from "@guidepup/playwright";
 
 // Capture all spoken phrases, including usage hints
-test.use({ voiceOverStartOptions: { capture: true } });
+test.use({ nvdaStartOptions: { capture: true } });
 ```
 
 ```ts
-// NVDA Example
-import { nvdaTest as test } from "@guidepup/playwright";
+// Orca Example
+import { orcaTest as test } from "@guidepup/playwright";
 
 // Capture all spoken phrases, including usage hints
-test.use({ nvdaStartOptions: { capture: true } });
+test.use({ orcaStartOptions: { 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.
+```ts
+// VoiceOver Example
+import { voiceOverTest as test } from "@guidepup/playwright";
 
-### VoiceOver example
+// Capture all spoken phrases, including usage hints
+test.use({ voiceOverStartOptions: { capture: true } });
+```
+
+The default for NVDA, Orca, and VoiceOver is set to `"initial"`. `true` captures all spoken phrases, including usage hints. `false` disables spoken phrase capture.
+
+### NVDA example
 
 `playwright.config.ts`:
 
 ```ts
-import { devices, PlaywrightTestConfig } from "@playwright/test";
-import { screenReaderConfig } from "@guidepup/playwright";
+import { devices } from "@playwright/test";
+import { withGuidepup } from "@guidepup/playwright";
 
-const config: PlaywrightTestConfig = {
-  ...screenReaderConfig,
+const config = withGuidepup({
   reportSlowTests: null,
   timeout: 5 * 60 * 1000,
   retries: 2,
   projects: [
     {
-      name: "webkit",
-      // Take care to ensure all usage is headed - screen readers cannot
-      // operate against headless browsers.
-      use: { ...devices["Desktop Safari"], headless: false },
+      name: "chrome",
+      use: { ...devices["Desktop Chrome"] },
     },
   ],
-};
+});
 
 export default config;
 ```
 
-`voiceOver.spec.ts`:
+`nvda.spec.ts`:
 
 ```ts
-import { voiceOverTest as test } from "@guidepup/playwright";
+import { nvdaTest as test } from "@guidepup/playwright";
 import { expect } from "@playwright/test";
 
-test.describe("Playwright VoiceOver", () => {
-  test("I can navigate the Guidepup Github page with VoiceOver", async ({
+test.describe("Playwright NVDA", () => {
+  test("I can navigate the Guidepup Github page with NVDA", async ({
     page,
-    voiceOver,
+    nvda,
   }) => {
     // Navigate to Guidepup GitHub page
     await page.goto("https://github.com/guidepup/guidepup", {
       waitUntil: "load",
     });
 
-    // Wait for page to be ready
+    // Wait for page to be ready and setup
     const header = page.locator('header[role="banner"]');
     await header.waitFor();
 
     // Interact with the page
-    await voiceOver.navigateToWebContent();
+    await nvda.navigateToWebContent();
 
-    // Move across the page menu to the Guidepup heading using VoiceOver
-    while ((await voiceOver.itemText()) !== "Guidepup heading level 1") {
-      await voiceOver.nextHeading();
+    // Move across the page menu to the Guidepup heading using NVDA
+    while ((await nvda.lastSpokenPhrase()) !== "Guidepup, heading, level 1") {
+      await nvda.nextHeading();
     }
 
     // Assert that the spoken phrases are as expected
-    expect(JSON.stringify(await voiceOver.spokenPhraseLog())).toMatchSnapshot();
+    expect(JSON.stringify(await nvda.spokenPhraseLog())).toMatchSnapshot();
   });
 });
 ```
 
-### NVDA example
+### Orca example
 
 `playwright.config.ts`:
 
 ```ts
-import { devices, PlaywrightTestConfig } from "@playwright/test";
-import { screenReaderConfig } from "@guidepup/playwright";
+import { devices } from "@playwright/test";
+import { withGuidepup } from "@guidepup/playwright";
 
-const config: PlaywrightTestConfig = {
-  ...screenReaderConfig,
+const config = withGuidepup({
   reportSlowTests: null,
   timeout: 5 * 60 * 1000,
   retries: 2,
   projects: [
     {
       name: "firefox",
-      // Take care to ensure all usage is headed - screen readers cannot
-      // operate against headless browsers.
-      use: { ...devices["Desktop Firefox"], headless: false },
+      use: { ...devices["Desktop Firefox"] },
     },
   ],
-};
+});
 
 export default config;
 ```
 
-`nvda.spec.ts`:
+`orca.spec.ts`:
 
 ```ts
-import { nvdaTest as test } from "@guidepup/playwright";
+import { orcaTest as test } from "@guidepup/playwright";
 import { expect } from "@playwright/test";
 
-test.describe("Playwright NVDA", () => {
-  test("I can navigate the Guidepup Github page with NVDA", async ({
+test.describe("Playwright Orca", () => {
+  test("I can navigate the Guidepup Github page with Orca", async ({
     page,
-    nvda,
+    orca,
   }) => {
     // Navigate to Guidepup GitHub page
     await page.goto("https://github.com/guidepup/guidepup", {
@@ -236,17 +239,74 @@ test.describe("Playwright NVDA", () => {
     await header.waitFor();
 
     // Interact with the page
-    await nvda.navigateToWebContent();
+    await orca.navigateToWebContent();
 
-    // Move across the page menu to the Guidepup heading using NVDA
+    // Move across the page menu to the Guidepup heading using Orca
+    while ((await orca.lastSpokenPhrase()) !== "Guidepup. heading 1") {
+      await orca.nextHeading();
+    }
+
+    // Assert that the spoken phrases are as expected
+    expect(JSON.stringify(await orca.spokenPhraseLog())).toMatchSnapshot();
+  });
+});
+```
+
+### VoiceOver example
+
+`playwright.config.ts`:
+
+```ts
+import { devices } from "@playwright/test";
+import { withGuidepup } from "@guidepup/playwright";
+
+const config = withGuidepup({
+  reportSlowTests: null,
+  timeout: 5 * 60 * 1000,
+  retries: 2,
+  projects: [
+    {
+      name: "webkit",
+      use: { ...devices["Desktop Safari"] },
+    },
+  ],
+});
+
+export default config;
+```
+
+`voiceOver.spec.ts`:
+
+```ts
+import { voiceOverTest as test } from "@guidepup/playwright";
+import { expect } from "@playwright/test";
+
+test.describe("Playwright VoiceOver", () => {
+  test("I can navigate the Guidepup Github page with VoiceOver", async ({
+    page,
+    voiceOver,
+  }) => {
+    // Navigate to Guidepup GitHub page
+    await page.goto("https://github.com/guidepup/guidepup", {
+      waitUntil: "load",
+    });
+
+    // Wait for page to be ready
+    const header = page.locator('header[role="banner"]');
+    await header.waitFor();
+
+    // Interact with the page
+    await voiceOver.navigateToWebContent();
+
+    // Move across the page menu to the Guidepup heading using VoiceOver
     while (
-      !(await nvda.lastSpokenPhrase()).includes("Guidepup, heading, level 1")
+      (await voiceOver.lastSpokenPhrase()) !== "heading level 1 Guidepup"
     ) {
-      await nvda.nextHeading();
+      await voiceOver.nextHeading();
     }
 
     // Assert that the spoken phrases are as expected
-    expect(JSON.stringify(await nvda.spokenPhraseLog())).toMatchSnapshot();
+    expect(JSON.stringify(await voiceOver.spokenPhraseLog())).toMatchSnapshot();
   });
 });
 ```
@@ -267,14 +327,14 @@ expect(capture.spokenPhrase).toContain("Added to cart");
 
 Check out some of the other Guidepup modules:
 
-- [`@guidepup/guidepup`](https://github.com/guidepup/guidepup/) - Reliable automation for your screen reader a11y workflows through JavaScript supporting VoiceOver and NVDA.
 - [`@guidepup/setup`](https://github.com/guidepup/setup/) - Set up your local or CI environment for screen reader test automation.
+- [`@guidepup/guidepup`](https://github.com/guidepup/guidepup/) - Reliable automation for your screen reader a11y workflows through JavaScript supporting VoiceOver, NVDA, and Orca.
 - [`@guidepup/virtual-screen-reader`](https://github.com/guidepup/virtual-screen-reader/) - Reliable unit testing for your screen reader a11y workflows.
 - [`@guidepup/jest`](https://github.com/guidepup/jest/) - Jest matchers for reliable unit testing of your screen reader a11y workflows.
 
 ## Resources
 
-- [Documentation](https://www.guidepup.dev/docs/example)
+- [Documentation](https://www.guidepup.dev/docs/getting-started/real-world-example)
 - [API Reference](https://www.guidepup.dev/docs/api/class-guidepup)
 - [Contributing](.github/CONTRIBUTING.md)
 - [Changelog](https://github.com/guidepup/guidepup-playwright/releases)

package/lib/applicationIdMap.d.ts

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

package/lib/applicationIdMap.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applicationIdMap = void 0;
+exports.applicationIdMap = {
+    chromium: "com.google.chrome.for.testing",
+    chrome: "com.google.Chrome",
+    "chrome-beta": "com.google.Chrome.beta",
+    msedge: "com.microsoft.edgemac",
+    "msedge-beta": "com.microsoft.edgemac.Beta",
+    "msedge-dev": "com.microsoft.edgemac.Dev",
+    firefox: "org.mozilla.nightlyunofficial",
+    webkit: "org.webkit.Playwright",
+};

package/lib/cleanString.d.ts

@@ -0,0 +1 @@
+export declare const cleanString: (str: string) => string;

package/lib/cleanString.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanString = void 0;
+const cleanString = (str) => str
+    .toLowerCase()
+    .replace(/[|¦:;'"`\-‐–—·_()[\]{}\\^~]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+exports.cleanString = cleanString;

package/lib/index.d.ts

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

package/lib/index.js

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

package/lib/navigateNVDAtoWebContent.d.ts

@@ -0,0 +1,8 @@
+import { type CommandOptions, type NVDA } from "@guidepup/guidepup";
+import type { Page } from "@playwright/test";
+export declare const navigateNVDAtoWebContent: ({ nvda, page, applicationName, capture, }: {
+    nvda: NVDA;
+    page: Page;
+    applicationName: string;
+    capture?: CommandOptions["capture"];
+}) => Promise<void>;

package/lib/navigateNVDAtoWebContent.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.navigateNVDAtoWebContent = void 0;
+const guidepup_1 = require("@guidepup/guidepup");
+const cleanString_1 = require("./cleanString");
+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 hasBrowserFocus = ({ applicationName, pageTitle, windowTitle, }) => {
+    const cleanedApplicationName = (0, cleanString_1.cleanString)(applicationName);
+    const cleanedPageTitle = (0, cleanString_1.cleanString)(pageTitle);
+    const cleanedWindowTitle = (0, cleanString_1.cleanString)(windowTitle);
+    return ((cleanedPageTitle.length > 0 &&
+        cleanedWindowTitle.startsWith(cleanedPageTitle)) ||
+        cleanedWindowTitle.includes(cleanedApplicationName));
+};
+const focusBrowser = async ({ nvda, applicationName, pageTitle, }) => {
+    await nvda.perform(guidepup_1.NVDAKeyCodeCommands.reportTitle);
+    let windowTitle = await nvda.lastSpokenPhrase();
+    if (hasBrowserFocus({ applicationName, pageTitle, windowTitle })) {
+        return;
+    }
+    let applicationSwitchRetryCount = 0;
+    while (applicationSwitchRetryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
+        applicationSwitchRetryCount++;
+        await nvda.perform(SWITCH_APPLICATION, { capture: false });
+        await (0, delay_1.delay)(500);
+        await nvda.perform(guidepup_1.NVDAKeyCodeCommands.reportTitle);
+        windowTitle = await nvda.lastSpokenPhrase();
+        if (hasBrowserFocus({ applicationName, pageTitle, windowTitle })) {
+            break;
+        }
+    }
+    if (applicationSwitchRetryCount === MAX_APPLICATION_SWITCH_RETRY_COUNT) {
+        throw new Error(`Unable to focus the application window with name "${applicationName}" or title "${pageTitle}" after ${MAX_APPLICATION_SWITCH_RETRY_COUNT} attempts.`);
+    }
+};
+const navigateNVDAtoWebContent = async ({ nvda, page, applicationName, capture, }) => {
+    const currentSpokenPhraseLog = [...(await nvda.spokenPhraseLog())];
+    const currentItemTextLog = [...(await nvda.itemTextLog())];
+    await nvda.perform(guidepup_1.NVDAKeyCodeCommands.exitFocusMode, { capture: false });
+    await (0, delay_1.delay)(100);
+    const pageTitle = await page.title();
+    await focusBrowser({ nvda, applicationName, pageTitle });
+    await page.bringToFront();
+    await page.locator("body").waitFor();
+    await page.locator("body").focus();
+    await page.locator("body").click();
+    await page.locator("body").blur();
+    // Firefox can leave NVDA focused on the whole browser after an application
+    // switch. Toggling browse/focus mode after moving to a focusable item restores
+    // browse mode. REF: https://github.com/nvaccess/nvda/issues/5758
+    await nvda.perform(guidepup_1.NVDAKeyCodeCommands.readNextFocusableItem, {
+        capture: false,
+    });
+    await (0, delay_1.delay)(100);
+    await nvda.perform(guidepup_1.NVDAKeyCodeCommands.toggleBetweenBrowseAndFocusMode, {
+        capture: false,
+    });
+    await (0, delay_1.delay)(100);
+    await nvda.perform(guidepup_1.NVDAKeyCodeCommands.toggleBetweenBrowseAndFocusMode, {
+        capture: false,
+    });
+    await (0, delay_1.delay)(100);
+    await nvda.perform(guidepup_1.NVDAKeyCodeCommands.exitFocusMode, { capture: false });
+    await (0, delay_1.delay)(100);
+    await nvda.clearSpokenPhraseLog();
+    await nvda.clearItemTextLog();
+    const spokenPhraseLog = await nvda.spokenPhraseLog();
+    const itemTextLog = await nvda.itemTextLog();
+    spokenPhraseLog.push(...currentSpokenPhraseLog);
+    itemTextLog.push(...currentItemTextLog);
+    await nvda.perform(MOVE_TO_TOP, { capture });
+};
+exports.navigateNVDAtoWebContent = navigateNVDAtoWebContent;

package/lib/navigateOrcaToWebContent.d.ts

@@ -0,0 +1,7 @@
+import { type CommandOptions, type Orca } from "@guidepup/guidepup";
+import type { Page } from "@playwright/test";
+export declare const navigateOrcaToWebContent: ({ orca, page, capture, }: {
+    orca: Orca;
+    page: Page;
+    capture?: CommandOptions["capture"];
+}) => Promise<void>;

package/lib/navigateOrcaToWebContent.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.navigateOrcaToWebContent = void 0;
+const node_child_process_1 = require("node:child_process");
+const guidepup_1 = require("@guidepup/guidepup");
+const cleanString_1 = require("./cleanString");
+const delay_1 = require("./delay");
+const MAX_APPLICATION_SWITCH_RETRY_COUNT = 10;
+const focusOrcaBrowser = async ({ orca, pageTitle, }) => {
+    const cleanedPageTitle = (0, cleanString_1.cleanString)(pageTitle);
+    if (!cleanedPageTitle) {
+        throw new Error("Cannot focus an application window with an empty page title.");
+    }
+    const currentSpokenPhraseLog = [...(await orca.spokenPhraseLog())];
+    try {
+        for (let retryCount = 0; retryCount <= MAX_APPLICATION_SWITCH_RETRY_COUNT; retryCount++) {
+            await orca.clearSpokenPhraseLog();
+            await orca.perform(guidepup_1.orcaKeyCodeCommands.PresentTitle, {
+                capture: "initial",
+            });
+            const windowTitle = (0, cleanString_1.cleanString)(await orca.lastSpokenPhrase());
+            if (windowTitle.includes(cleanedPageTitle)) {
+                return;
+            }
+            if (retryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
+                (0, node_child_process_1.execFileSync)("xdotool", ["key", "--clearmodifiers", "alt+Tab"]);
+                await (0, delay_1.delay)(100);
+            }
+        }
+        throw new Error(`Unable to focus the application window with title "${pageTitle}" after ${MAX_APPLICATION_SWITCH_RETRY_COUNT} attempts.`);
+    }
+    finally {
+        await orca.clearSpokenPhraseLog();
+        const spokenPhraseLog = await orca.spokenPhraseLog();
+        spokenPhraseLog.push(...currentSpokenPhraseLog);
+    }
+};
+const navigateOrcaToWebContent = async ({ orca, page, capture, }) => {
+    const pageTitle = await page.title();
+    await focusOrcaBrowser({ orca, pageTitle });
+    await page.bringToFront();
+    await page.locator("body").waitFor();
+    await page.locator("body").focus();
+    await page.locator("body").click();
+    await page.locator("body").blur();
+    await orca.perform(guidepup_1.orcaKeyCodeCommands.StartOfFile, { capture });
+};
+exports.navigateOrcaToWebContent = navigateOrcaToWebContent;

package/lib/navigateVoiceOverToWebContent.d.ts

@@ -0,0 +1,8 @@
+import { type CommandOptions, type VoiceOver } from "@guidepup/guidepup";
+import type { Page } from "@playwright/test";
+export declare const navigateVoiceOverToWebContent: ({ voiceOver, page, applicationId, capture, }: {
+    voiceOver: VoiceOver;
+    page: Page;
+    applicationId: string;
+    capture?: CommandOptions["capture"];
+}) => Promise<void>;

package/lib/navigateVoiceOverToWebContent.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.navigateVoiceOverToWebContent = void 0;
+const guidepup_1 = require("@guidepup/guidepup");
+const delay_1 = require("./delay");
+const MAX_WEB_CONTENT_SEARCH_ATTEMPTS = 10;
+const cancelCurrentInteraction = async (voiceOver) => {
+    await voiceOver.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
+};
+const closeMenus = async (voiceOver) => {
+    await voiceOver.perform({ keyCode: guidepup_1.MacOSKeyCodes.Escape }, { capture: false });
+};
+const openItemChooser = async (voiceOver) => {
+    let lastSpokenPhrase = "";
+    while (!lastSpokenPhrase.toLowerCase().includes("item chooser")) {
+        await cancelCurrentInteraction(voiceOver);
+        await (0, delay_1.delay)(100);
+        await closeMenus(voiceOver);
+        await (0, delay_1.delay)(100);
+        await voiceOver.perform(guidepup_1.voiceOverKeyCodeCommands.openItemChooser, {
+            capture: true,
+        });
+        lastSpokenPhrase = await voiceOver.lastSpokenPhrase();
+    }
+};
+const selectWebContentItem = async (voiceOver) => {
+    let matched = false;
+    for (let attempt = 0; attempt < MAX_WEB_CONTENT_SEARCH_ATTEMPTS && !matched; attempt++) {
+        for (const character of "web content") {
+            await cancelCurrentInteraction(voiceOver);
+            await (0, delay_1.delay)(100);
+            await voiceOver.type(character, { capture: "initial" });
+            const lastSpokenPhrase = await voiceOver.lastSpokenPhrase();
+            if (lastSpokenPhrase.toLowerCase().includes("web content")) {
+                matched = true;
+                break;
+            }
+        }
+        if (matched) {
+            break;
+        }
+        if (attempt + 1 < MAX_WEB_CONTENT_SEARCH_ATTEMPTS) {
+            await voiceOver.perform({ keyCode: guidepup_1.MacOSKeyCodes.Backspace }, { capture: false });
+            await (0, delay_1.delay)(100);
+        }
+    }
+    if (!matched) {
+        throw new Error(`Unable to find "web content" in the VoiceOver Item Chooser after ${MAX_WEB_CONTENT_SEARCH_ATTEMPTS} attempts.`);
+    }
+    await voiceOver.perform({ keyCode: guidepup_1.MacOSKeyCodes.Enter }, { capture: false });
+};
+const navigateVoiceOverToWebContent = async ({ voiceOver, page, applicationId, capture, }) => {
+    const currentSpokenPhraseLog = [...(await voiceOver.spokenPhraseLog())];
+    const currentItemTextLog = [...(await voiceOver.itemTextLog())];
+    await (0, guidepup_1.macOSActivateId)(applicationId);
+    await cancelCurrentInteraction(voiceOver);
+    await (0, delay_1.delay)(100);
+    await page.bringToFront();
+    await page.locator("body").waitFor();
+    try {
+        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);
+        });
+        await openItemChooser(voiceOver);
+        await selectWebContentItem(voiceOver);
+        await voiceOver.interact({ capture: false });
+        await (0, delay_1.delay)(100);
+        await voiceOver.clearSpokenPhraseLog();
+        await voiceOver.clearItemTextLog();
+        const spokenPhraseLog = await voiceOver.spokenPhraseLog();
+        const itemTextLog = await voiceOver.itemTextLog();
+        spokenPhraseLog.push(...currentSpokenPhraseLog);
+        itemTextLog.push(...currentItemTextLog);
+        await voiceOver.next({ capture });
+    }
+    finally {
+        await page.evaluate(() => {
+            const marker = document.querySelector("#__guidepup_marker__");
+            if (marker) {
+                document.body.removeChild(marker);
+            }
+        });
+    }
+};
+exports.navigateVoiceOverToWebContent = navigateVoiceOverToWebContent;