@guidepup/playwright 0.19.1 → 0.20.0

package/lib/nvdaTest.js

@@ -4,49 +4,8 @@ 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 navigateNVDAtoWebContent_1 = require("./navigateNVDAtoWebContent");
 const nvdaPlaywright = guidepup_1.nvda;
-const MAX_APPLICATION_SWITCH_RETRY_COUNT = 10;
-const SWITCH_APPLICATION = {
-    keyCode: [guidepup_1.WindowsKeyCodes.Escape],
-    modifiers: [guidepup_1.WindowsModifiers.Alt],
-};
-const MOVE_TO_TOP = {
-    keyCode: [guidepup_1.WindowsKeyCodes.Home],
-    modifiers: [guidepup_1.WindowsModifiers.Control],
-};
-const cleanString = (str) => str
-    .toLowerCase()
-    // REF: https://github.com/nvaccess/nvda/blob/master/source/locale/en/symbols.dic
-    .replace(/[|¦:;'"`\-‐–—·_()[\]{}\\^~]/g, " ")
-    .replace(/\s+/g, " ")
-    .trim();
-const hasFocus = ({ applicationName, pageTitle, windowTitle, }) => {
-    const cleanedApplicationName = cleanString(applicationName);
-    const cleanedPageTitle = cleanString(pageTitle);
-    const cleanedWindowTitle = cleanString(windowTitle);
-    return ((cleanedPageTitle.length &&
-        cleanedWindowTitle.startsWith(cleanedPageTitle)) ||
-        cleanedWindowTitle.includes(cleanedApplicationName));
-};
-const focusBrowser = async ({ applicationName, pageTitle, }) => {
-    await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
-    let windowTitle = await nvdaPlaywright.lastSpokenPhrase();
-    if (hasFocus({ applicationName, pageTitle, windowTitle })) {
-        return;
-    }
-    let applicationSwitchRetryCount = 0;
-    while (applicationSwitchRetryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
-        applicationSwitchRetryCount++;
-        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 })) {
-            break;
-        }
-    }
-};
 /**
  * These tests extend the default Playwright environment that launches the
  * browser with a running instance of the NVDA screen reader for Windows.
@@ -59,53 +18,14 @@ exports.nvdaTest = test_1.test.extend({
         try {
             const applicationName = applicationNameMap_1.applicationNameMap[browserName];
             if (!applicationName) {
-                throw new Error(`Browser ${browserName} is not installed.`);
+                throw new Error(`Browser ${browserName} is not recognised.`);
             }
-            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, { capture: false });
-                await (0, delay_1.delay)(100);
-                // Ensure application is brought to front and focused.
-                const pageTitle = await page.title();
-                await focusBrowser({ applicationName, pageTitle });
-                // Ensure the document is ready and focused.
-                await page.bringToFront();
-                await page.locator("body").waitFor();
-                await page.locator("body").focus();
-                await page.locator("body").click();
-                await page.locator("body").blur();
-                // NVDA appears to not work well with Firefox when switching between
-                // applications resulting in the entire browser window having NVDA focus
-                // with focus mode.
-                //
-                // One workaround is to tab to the next focusable item. From there we can
-                // toggle into (yes although we are already in it...) focus mode and back
-                // out. In case this ever transpires to not happen as expect, we then ensure
-                // we exit focus mode and move NVDA to the top of the page.
-                //
-                // REF: https://github.com/nvaccess/nvda/issues/5758
-                await 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 });
-            };
+            nvdaPlaywright.navigateToWebContent = ({ capture } = {}) => (0, navigateNVDAtoWebContent_1.navigateNVDAtoWebContent)({
+                nvda: nvdaPlaywright,
+                page,
+                applicationName,
+                capture,
+            });
             await nvdaPlaywright.start(nvdaStartOptions);
             await use(nvdaPlaywright);
         }

package/lib/orcaTest.d.ts

@@ -0,0 +1,73 @@
+import { type CommandOptions, type Orca, type StartOptions } from "@guidepup/guidepup";
+/**
+ * [API Reference](https://www.guidepup.dev/docs/api/class-orca)
+ *
+ * This object can be used to launch and control Orca.
+ *
+ * Here's a typical example:
+ *
+ * ```ts
+ * import { unstable_orca } from "@guidepup/guidepup";
+ *
+ * (async () => {
+ *   // Start Orca.
+ *   await unstable_orca.start();
+ *
+ *   // Move to the next item.
+ *   await unstable_orca.next();
+ *
+ *   // ... perform some commands.
+ *
+ *   // Stop Orca.
+ *   await unstable_orca.stop();
+ * })();
+ * ```
+ */
+export interface OrcaPlaywright extends Orca {
+    /**
+     * Guidepup Playwright specific command that navigates Orca to the beginning
+     * of the browser's web content.
+     *
+     * This command should be used after a page navigation has completed.
+     */
+    navigateToWebContent(options?: Pick<CommandOptions, "capture">): Promise<void>;
+}
+/**
+ * These tests extend the default Playwright environment that launches the
+ * browser with a running instance of the Orca screen reader for macOS.
+ *
+ * A fresh started Orca instance `orca` is provided to each test.
+ */
+export declare const orcaTest: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    /**
+     * [API Reference](https://www.guidepup.dev/docs/api/class-orca)
+     *
+     * This object can be used to launch and control Orca.
+     *
+     * Here's a typical example:
+     *
+     * ```ts
+     * import { unstable_orca } from "@guidepup/guidepup";
+     *
+     * (async () => {
+     *   // Start Orca.
+     *   await unstable_orca.start();
+     *
+     *   // Move to the next item.
+     *   await unstable_orca.next();
+     *
+     *   // ... perform some commands.
+     *
+     *   // Stop Orca.
+     *   await unstable_orca.stop();
+     * })();
+     * ```
+     */
+    orca: OrcaPlaywright;
+    /**
+     * [API Reference](https://www.guidepup.dev/docs/api/class-start-options)
+     *
+     * Options to start Orca with, see also [unstable_orca.start([options])](https://www.guidepup.dev/docs/api/class-orca#unstable-orca-start).
+     */
+    orcaStartOptions: StartOptions;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;

package/lib/orcaTest.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.orcaTest = void 0;
+const test_1 = require("@playwright/test");
+const guidepup_1 = require("@guidepup/guidepup");
+const navigateOrcaToWebContent_1 = require("./navigateOrcaToWebContent");
+const orcaPlaywright = guidepup_1.unstable_orca;
+/**
+ * These tests extend the default Playwright environment that launches the
+ * browser with a running instance of the Orca screen reader for macOS.
+ *
+ * A fresh started Orca instance `orca` is provided to each test.
+ */
+exports.orcaTest = test_1.test.extend({
+    orcaStartOptions: { capture: "initial" },
+    orca: async ({ page, orcaStartOptions }, use) => {
+        try {
+            orcaPlaywright.navigateToWebContent = ({ capture } = {}) => (0, navigateOrcaToWebContent_1.navigateOrcaToWebContent)({
+                orca: orcaPlaywright,
+                page,
+                capture,
+            });
+            await orcaPlaywright.start(orcaStartOptions);
+            await use(orcaPlaywright);
+        }
+        finally {
+            try {
+                await orcaPlaywright.stop();
+            }
+            catch {
+                // swallow stop failure
+            }
+        }
+    },
+});

package/lib/screenReaderTest.d.ts

@@ -5,6 +5,8 @@ type Prettify<T> = {
 type CaptureCommandOptions = Prettify<Pick<CommandOptions, "capture">>;
 type CaptureStartOptions = Prettify<Pick<StartOptions, "capture" | "settings">>;
 /**
+ * [API Reference](https://www.guidepup.dev/docs/api/class-screenreader)
+ *
  * This object can be used to launch and control the default screen reader for
  * the environment.
  *
@@ -46,6 +48,8 @@ export interface ScreenReaderPlaywright extends ScreenReader {
  */
 export declare const screenReaderTest: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
     /**
+     * [API Reference](https://www.guidepup.dev/docs/api/class-screenreader)
+     *
      * This object can be used to launch and control the default screen reader for
      * the environment.
      *
@@ -70,7 +74,9 @@ export declare const screenReaderTest: import("@playwright/test").TestType<impor
      */
     screenReader: ScreenReaderPlaywright;
     /**
-     * Options to start the default screen reader with.
+     * [API Reference](https://www.guidepup.dev/docs/api/class-start-options)
+     *
+     * Options to start the default screen reader with, see also [screenReader.start([options])](https://www.guidepup.dev/docs/api/class-screenreader#screenreader-start).
      */
     screenReaderStartOptions: CaptureStartOptions;
 }, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;

package/lib/screenReaderTest.js

@@ -4,90 +4,10 @@ exports.screenReaderTest = void 0;
 const test_1 = require("@playwright/test");
 const guidepup_1 = require("@guidepup/guidepup");
 const applicationNameMap_1 = require("./applicationNameMap");
-const delay_1 = require("./delay");
-const MAX_APPLICATION_SWITCH_RETRY_COUNT = 10;
-const SWITCH_APPLICATION = {
-    keyCode: [guidepup_1.WindowsKeyCodes.Escape],
-    modifiers: [guidepup_1.WindowsModifiers.Alt],
-};
-const MOVE_TO_TOP = {
-    keyCode: [guidepup_1.WindowsKeyCodes.Home],
-    modifiers: [guidepup_1.WindowsModifiers.Control],
-};
-const cleanString = (str) => str
-    .toLowerCase()
-    // REF: https://github.com/nvaccess/nvda/blob/master/source/locale/en/symbols.dic
-    .replace(/[|¦:;'"`\-‐–—·_()[\]{}\\^~]/g, " ")
-    .replace(/\s+/g, " ")
-    .trim();
-const hasFocus = ({ applicationName, pageTitle, windowTitle, }) => {
-    const cleanedApplicationName = cleanString(applicationName);
-    const cleanedPageTitle = cleanString(pageTitle);
-    const cleanedWindowTitle = cleanString(windowTitle);
-    return ((cleanedPageTitle.length &&
-        cleanedWindowTitle.startsWith(cleanedPageTitle)) ||
-        cleanedWindowTitle.includes(cleanedApplicationName));
-};
-const focusBrowser = async ({ applicationName, pageTitle, }) => {
-    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.reportTitle);
-    let windowTitle = await screenReaderPlaywright.lastSpokenPhrase();
-    if (hasFocus({ applicationName, pageTitle, windowTitle })) {
-        return;
-    }
-    let applicationSwitchRetryCount = 0;
-    while (applicationSwitchRetryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
-        applicationSwitchRetryCount++;
-        await screenReaderPlaywright.perform(SWITCH_APPLICATION, {
-            capture: false,
-        });
-        await (0, delay_1.delay)(500);
-        await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.reportTitle);
-        windowTitle = await screenReaderPlaywright.lastSpokenPhrase();
-        if (hasFocus({ applicationName, pageTitle, windowTitle })) {
-            break;
-        }
-    }
-};
-const closeMenus = async ({ screenReaderPlaywright, }) => {
-    await screenReaderPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Escape }, { capture: false });
-};
-const cancelCurrentInteraction = async ({ screenReaderPlaywright, }) => {
-    await screenReaderPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
-};
-const openItemChooser = async ({ screenReaderPlaywright, }) => {
-    let lastSpokenPhrase = "";
-    while (!lastSpokenPhrase.toLowerCase().includes("item chooser")) {
-        await cancelCurrentInteraction({ screenReaderPlaywright });
-        await (0, delay_1.delay)(100);
-        await closeMenus({ screenReaderPlaywright });
-        await (0, delay_1.delay)(100);
-        await screenReaderPlaywright.perform(guidepup_1.voiceOverKeyCodeCommands.openItemChooser, { capture: true });
-        lastSpokenPhrase = await screenReaderPlaywright.lastSpokenPhrase();
-    }
-};
-async function selectWebContentItem({ screenReaderPlaywright, }) {
-    // eslint-disable-next-line no-constant-condition
-    while (true) {
-        let matched = false;
-        for (const character of "web content") {
-            await cancelCurrentInteraction({ screenReaderPlaywright });
-            await (0, delay_1.delay)(100);
-            await screenReaderPlaywright.type(character, { capture: "initial" });
-            const lastSpokenPhrase = await screenReaderPlaywright.lastSpokenPhrase();
-            if (lastSpokenPhrase.toLowerCase().includes("web content")) {
-                matched = true;
-                break;
-            }
-        }
-        if (matched) {
-            break;
-        }
-        // Clear the entire Item Chooser search.
-        await screenReaderPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Backspace }, { capture: false });
-        await (0, delay_1.delay)(100);
-    }
-    await screenReaderPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Enter }, { capture: false });
-}
+const navigateNVDAtoWebContent_1 = require("./navigateNVDAtoWebContent");
+const navigateOrcaToWebContent_1 = require("./navigateOrcaToWebContent");
+const navigateVoiceOverToWebContent_1 = require("./navigateVoiceOverToWebContent");
+const applicationIdMap_1 = require("./applicationIdMap");
 const screenReaderPlaywright = guidepup_1.screenReader;
 /**
  * These tests extend the default Playwright environment that launches the
@@ -102,124 +22,32 @@ exports.screenReaderTest = test_1.test.extend({
     screenReader: async ({ browserName, page, screenReaderStartOptions }, use) => {
         try {
             const applicationName = applicationNameMap_1.applicationNameMap[browserName];
-            if (!applicationName) {
-                throw new Error(`Browser ${browserName} is not installed.`);
+            const applicationId = applicationIdMap_1.applicationIdMap[browserName];
+            if (!applicationName || !applicationId) {
+                throw new Error(`Browser ${browserName} is not recognised.`);
             }
             if (guidepup_1.nvda.default()) {
-                screenReaderPlaywright.navigateToWebContent = async ({ capture, } = {}) => {
-                    const currentSpokenPhraseLog = [
-                        ...(await screenReaderPlaywright.spokenPhraseLog()),
-                    ];
-                    const currentItemTextLog = [
-                        ...(await screenReaderPlaywright.itemTextLog()),
-                    ];
-                    // Make sure NVDA is not in focus mode.
-                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.exitFocusMode, { capture: false });
-                    await (0, delay_1.delay)(100);
-                    // Ensure application is brought to front and focused.
-                    const pageTitle = await page.title();
-                    await focusBrowser({ applicationName, pageTitle });
-                    // Ensure the document is ready and focused.
-                    await page.bringToFront();
-                    await page.locator("body").waitFor();
-                    await page.locator("body").focus();
-                    await page.locator("body").click();
-                    await page.locator("body").blur();
-                    // NVDA appears to not work well with Firefox when switching between
-                    // applications resulting in the entire browser window having NVDA focus
-                    // with focus mode.
-                    //
-                    // One workaround is to tab to the next focusable item. From there we can
-                    // toggle into (yes although we are already in it...) focus mode and back
-                    // out. In case this ever transpires to not happen as expect, we then ensure
-                    // we exit focus mode and move NVDA to the top of the page.
-                    //
-                    // REF: https://github.com/nvaccess/nvda/issues/5758
-                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.readNextFocusableItem, { capture: false });
-                    await (0, delay_1.delay)(100);
-                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.toggleBetweenBrowseAndFocusMode, { capture: false });
-                    await (0, delay_1.delay)(100);
-                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.toggleBetweenBrowseAndFocusMode, { capture: false });
-                    await (0, delay_1.delay)(100);
-                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.exitFocusMode, { capture: false });
-                    await (0, delay_1.delay)(100);
-                    await screenReaderPlaywright.clearSpokenPhraseLog();
-                    await screenReaderPlaywright.clearItemTextLog();
-                    const spokenPhraseLog = await screenReaderPlaywright.spokenPhraseLog();
-                    const itemTextLog = await screenReaderPlaywright.itemTextLog();
-                    spokenPhraseLog.push(...currentSpokenPhraseLog);
-                    itemTextLog.push(...currentItemTextLog);
-                    // Navigate to the beginning of the web content, using chosen capture
-                    // settings, so don't miss announcing the first item on the page.
-                    await screenReaderPlaywright.perform(MOVE_TO_TOP, { capture });
-                };
+                screenReaderPlaywright.navigateToWebContent = ({ capture } = {}) => (0, navigateNVDAtoWebContent_1.navigateNVDAtoWebContent)({
+                    nvda: guidepup_1.nvda,
+                    page,
+                    applicationName,
+                    capture,
+                });
             }
             else if (guidepup_1.voiceOver.default()) {
-                screenReaderPlaywright.navigateToWebContent = async ({ capture, } = {}) => {
-                    const currentSpokenPhraseLog = [
-                        ...(await screenReaderPlaywright.spokenPhraseLog()),
-                    ];
-                    const currentItemTextLog = [
-                        ...(await screenReaderPlaywright.itemTextLog()),
-                    ];
-                    // Ensure application is brought to front and focused.
-                    await (0, guidepup_1.macOSActivate)(applicationName);
-                    // Cancel automatic behaviours/previous commands.
-                    await cancelCurrentInteraction({ screenReaderPlaywright });
-                    await (0, delay_1.delay)(100);
-                    // Ensure the document is ready and focused.
-                    await page.bringToFront();
-                    await page.locator("body").waitFor();
-                    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 item chooser and select web content.
-                        await openItemChooser({ screenReaderPlaywright });
-                        await selectWebContentItem({ screenReaderPlaywright });
-                        // Navigate into web content.
-                        await screenReaderPlaywright.interact({ 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 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);
-                            }
-                        });
-                    }
-                };
+                screenReaderPlaywright.navigateToWebContent = ({ capture } = {}) => (0, navigateVoiceOverToWebContent_1.navigateVoiceOverToWebContent)({
+                    voiceOver: guidepup_1.voiceOver,
+                    page,
+                    applicationId,
+                    capture,
+                });
+            }
+            else if (guidepup_1.unstable_orca.default()) {
+                screenReaderPlaywright.navigateToWebContent = ({ capture } = {}) => (0, navigateOrcaToWebContent_1.navigateOrcaToWebContent)({
+                    orca: guidepup_1.unstable_orca,
+                    page,
+                    capture,
+                });
             }
             else {
                 throw new Error("No supported screen reader");

package/lib/voiceOverTest.d.ts

@@ -1,4 +1,4 @@
-import type { StartOptions, CommandOptions, VoiceOver } from "@guidepup/guidepup";
+import { type CommandOptions, type StartOptions, type VoiceOver } from "@guidepup/guidepup";
 /**
  * [API Reference](https://www.guidepup.dev/docs/api/class-voiceover)
  *
@@ -34,7 +34,7 @@ export interface VoiceOverPlaywright extends VoiceOver {
 }
 /**
  * These tests extend the default Playwright environment that launches the
- * browser with a running instance of the VoiceOver screen reader for MacOS.
+ * browser with a running instance of the VoiceOver screen reader for macOS.
  *
  * A fresh started VoiceOver instance `voiceOver` is provided to each test.
  */

package/lib/voiceOverTest.js

@@ -1,54 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.voiceOverTest = void 0;
-const test_1 = require("@playwright/test");
 const guidepup_1 = require("@guidepup/guidepup");
-const applicationNameMap_1 = require("./applicationNameMap");
-const delay_1 = require("./delay");
-const closeMenus = async ({ voiceOverPlaywright, }) => {
-    await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Escape }, { capture: false });
-};
-const cancelCurrentInteraction = async ({ voiceOverPlaywright, }) => {
-    await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
-};
-const openItemChooser = async ({ voiceOverPlaywright, }) => {
-    let lastSpokenPhrase = "";
-    while (!lastSpokenPhrase.toLowerCase().includes("item chooser")) {
-        await cancelCurrentInteraction({ voiceOverPlaywright });
-        await (0, delay_1.delay)(100);
-        await closeMenus({ voiceOverPlaywright });
-        await (0, delay_1.delay)(100);
-        await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.openItemChooser, { capture: true });
-        lastSpokenPhrase = await voiceOverPlaywright.lastSpokenPhrase();
-    }
-};
-async function selectWebContentItem({ voiceOverPlaywright, }) {
-    // eslint-disable-next-line no-constant-condition
-    while (true) {
-        let matched = false;
-        for (const character of "web content") {
-            await cancelCurrentInteraction({ voiceOverPlaywright });
-            await (0, delay_1.delay)(100);
-            await voiceOverPlaywright.type(character, { capture: "initial" });
-            const lastSpokenPhrase = await voiceOverPlaywright.lastSpokenPhrase();
-            if (lastSpokenPhrase.toLowerCase().includes("web content")) {
-                matched = true;
-                break;
-            }
-        }
-        if (matched) {
-            break;
-        }
-        // Clear the entire Item Chooser search.
-        await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Backspace }, { capture: false });
-        await (0, delay_1.delay)(100);
-    }
-    await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Enter }, { capture: false });
-}
+const applicationIdMap_1 = require("./applicationIdMap");
+const navigateVoiceOverToWebContent_1 = require("./navigateVoiceOverToWebContent");
+const test_1 = require("@playwright/test");
 const voiceOverPlaywright = guidepup_1.voiceOver;
 /**
  * These tests extend the default Playwright environment that launches the
- * browser with a running instance of the VoiceOver screen reader for MacOS.
+ * browser with a running instance of the VoiceOver screen reader for macOS.
  *
  * A fresh started VoiceOver instance `voiceOver` is provided to each test.
  */
@@ -56,75 +16,16 @@ exports.voiceOverTest = test_1.test.extend({
     voiceOverStartOptions: { capture: "initial" },
     voiceOver: async ({ browserName, page, voiceOverStartOptions }, use) => {
         try {
-            const applicationName = applicationNameMap_1.applicationNameMap[browserName];
-            if (!applicationName) {
-                throw new Error(`Browser ${browserName} is not installed.`);
+            const applicationId = applicationIdMap_1.applicationIdMap[browserName];
+            if (!applicationId) {
+                throw new Error(`Browser ${browserName} is not recognised.`);
             }
-            voiceOverPlaywright.navigateToWebContent = async ({ capture } = {}) => {
-                const currentSpokenPhraseLog = [
-                    ...(await voiceOverPlaywright.spokenPhraseLog()),
-                ];
-                const currentItemTextLog = [
-                    ...(await voiceOverPlaywright.itemTextLog()),
-                ];
-                // Ensure application is brought to front and focused.
-                await (0, guidepup_1.macOSActivate)(applicationName);
-                // Cancel automatic behaviours/previous commands.
-                await cancelCurrentInteraction({ voiceOverPlaywright });
-                await (0, delay_1.delay)(100);
-                // Ensure the document is ready and focused.
-                await page.bringToFront();
-                await page.locator("body").waitFor();
-                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 item chooser and select web content.
-                    await openItemChooser({ voiceOverPlaywright });
-                    await selectWebContentItem({ voiceOverPlaywright });
-                    // Navigate into web content.
-                    await voiceOverPlaywright.interact({ capture: false });
-                    await (0, delay_1.delay)(100);
-                    await voiceOverPlaywright.clearSpokenPhraseLog();
-                    await voiceOverPlaywright.clearItemTextLog();
-                    const spokenPhraseLog = await voiceOverPlaywright.spokenPhraseLog();
-                    const itemTextLog = await voiceOverPlaywright.itemTextLog();
-                    spokenPhraseLog.push(...currentSpokenPhraseLog);
-                    itemTextLog.push(...currentItemTextLog);
-                    // 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);
-                        }
-                    });
-                }
-            };
+            voiceOverPlaywright.navigateToWebContent = ({ capture } = {}) => (0, navigateVoiceOverToWebContent_1.navigateVoiceOverToWebContent)({
+                voiceOver: voiceOverPlaywright,
+                page,
+                applicationId,
+                capture,
+            });
             await voiceOverPlaywright.start(voiceOverStartOptions);
             await use(voiceOverPlaywright);
         }

package/lib/withGuidepup.d.ts

@@ -0,0 +1,2 @@
+import type { PlaywrightTestConfig } from "@playwright/test";
+export declare const withGuidepup: (config: PlaywrightTestConfig) => PlaywrightTestConfig;