@guidepup/playwright 0.18.0 → 0.19.1

package/README.md

@@ -99,39 +99,6 @@ 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:
-
-```ts
-// ... some commands
-
-// Store spoken phrases
-const spokenPhrases = await screenReader.spokenPhraseLog();
-
-// Navigate to the web content
-await screenReader.navigateToWebContent();
-
-// ... some commands
-
-// Collect all spoken phrases
-const allSpokenPhrases = [
-  ...spokenPhrases,
-  ...(await screenReader.spokenPhraseLog()),
-];
-
-// ... do something with spoken phrases
-```
-
-or pass a flag to prevent log clearing:
-
-```ts
-// ... some commands
-
-// Navigate to the web content
-await screenReader.navigateToWebContent(false);
-
-// ... some commands
-```
-
 ### 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:
@@ -213,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
@@ -275,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
@@ -284,6 +251,18 @@ test.describe("Playwright NVDA", () => {
 });
 ```
 
+### Capture Playwright Interactions
+
+Use the `capture()` API to wrap Playwright interactions and capture the resulting screen reader output without needing to perform the interaction through Guidepup.
+
+```ts
+const capture = await screenReader.capture(() =>
+  page.getByRole("button", { name: "Add to cart" }).click(),
+);
+
+expect(capture.spokenPhrase).toContain("Added to cart");
+```
+
 ## Powerful tooling
 
 Check out some of the other Guidepup modules:

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)
  *
@@ -32,7 +33,7 @@ export interface NVDAPlaywright extends NVDA {
      *
      * This command should be used after page navigation.
      */
-    navigateToWebContent(options?: Pick<CommandOptions, "capture">): Promise<void>;
+    navigateToWebContent(options?: CaptureCommandOptions): Promise<void>;
 }
 /**
  * These tests extend the default Playwright environment that launches the
@@ -65,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/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.
@@ -33,7 +34,7 @@ export interface ScreenReaderPlaywright extends ScreenReader {
      *
      * This command should be used after page navigation.
      */
-    navigateToWebContent(options?: Pick<CommandOptions, "capture">): Promise<void>;
+    navigateToWebContent(options?: CaptureCommandOptions): Promise<void>;
 }
 /**
  * These tests extend the default Playwright environment that launches the
@@ -71,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

@@ -48,6 +48,46 @@ const focusBrowser = async ({ applicationName, pageTitle, }) => {
         }
     }
 };
+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 screenReaderPlaywright = guidepup_1.screenReader;
 /**
  * These tests extend the default Playwright environment that launches the
@@ -116,38 +156,69 @@ exports.screenReaderTest = test_1.test.extend({
             }
             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 auto navigation.
-                    await screenReaderPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
+                    // 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();
-                    // 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 });
+                    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);
+                            }
+                        });
                     }
-                    // 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

@@ -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)
  *
@@ -65,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

@@ -5,6 +5,46 @@ 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 voiceOverPlaywright = guidepup_1.voiceOver;
 /**
  * These tests extend the default Playwright environment that launches the
@@ -21,38 +61,69 @@ exports.voiceOverTest = test_1.test.extend({
                 throw new Error(`Browser ${browserName} is not installed.`);
             }
             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 auto navigation.
-                await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
+                // 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();
-                // 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 });
+                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);
+                        }
+                    });
                 }
-                // 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 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.18.0",
+  "version": "0.19.1",
   "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.29.1",
+    "@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": {