@guidepup/playwright 0.18.0 → 0.19.0

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

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

@@ -124,30 +124,68 @@ exports.screenReaderTest = test_1.test.extend({
                     // 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 the web item chooser.
+                        await screenReaderPlaywright.perform(guidepup_1.voiceOverKeyCodeCommands.openItemChooser, { capture: false });
+                        await (0, delay_1.delay)(500);
+                        // Filter by "web content" - currently web content items for all browsers
+                        // are suffixed by "web content".
+                        for (const character of "web content") {
+                            await screenReaderPlaywright.type(character, { capture: false });
+                            await (0, delay_1.delay)(100);
+                        }
+                        // Select the web content window spot.
+                        await screenReaderPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Enter }, { capture: false });
                         await (0, delay_1.delay)(100);
+                        // Navigate into web content.
+                        await screenReaderPlaywright.interact({ capture: false });
+                        await (0, delay_1.delay)(100);
+                        // Navigate to the beginning of the web content.
+                        await screenReaderPlaywright.perform(guidepup_1.voiceOverKeyCodeCommands.moveToBeginningOfText, { capture: false });
+                        await (0, delay_1.delay)(100);
+                        // Cancel auto navigation
+                        await screenReaderPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
+                        await (0, delay_1.delay)(100);
+                        // Navigate to the Guidepup marker element at beginning of the web
+                        // content.
+                        await screenReaderPlaywright.perform(guidepup_1.voiceOverKeyCodeCommands.moveToBeginningOfText, { capture: false });
+                        await (0, delay_1.delay)(100);
+                        // Navigate to the first element of the page using the provided
+                        // capture settings.
+                        await screenReaderPlaywright.next({ capture });
+                    }
+                    finally {
+                        // Remove the temporary Guidepup marker element to restore original
+                        // page structure.
+                        await page.evaluate(() => {
+                            const marker = document.querySelector("#__guidepup_marker__");
+                            if (marker) {
+                                document.body.removeChild(marker);
+                            }
+                        });
                     }
-                    // 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

@@ -29,30 +29,68 @@ exports.voiceOverTest = test_1.test.extend({
                 // 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 the web item chooser.
+                    await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.openItemChooser, { capture: false });
+                    await (0, delay_1.delay)(500);
+                    // Filter by "web content" - currently web content items for all browsers
+                    // are suffixed by "web content".
+                    for (const character of "web content") {
+                        await voiceOverPlaywright.type(character, { capture: false });
+                        await (0, delay_1.delay)(100);
+                    }
+                    // Select the web content window spot.
+                    await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Enter }, { capture: false });
                     await (0, delay_1.delay)(100);
+                    // Navigate into web content.
+                    await voiceOverPlaywright.interact({ capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Navigate to the beginning of the web content.
+                    await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.moveToBeginningOfText, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Cancel auto navigation
+                    await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Navigate to the Guidepup marker element at beginning of the web
+                    // content.
+                    await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.moveToBeginningOfText, { capture: false });
+                    await (0, delay_1.delay)(100);
+                    // Navigate to the first element of the page using the provided
+                    // capture settings.
+                    await voiceOverPlaywright.next({ capture });
+                }
+                finally {
+                    // Remove the temporary Guidepup marker element to restore original
+                    // page structure.
+                    await page.evaluate(() => {
+                        const marker = document.querySelector("#__guidepup_marker__");
+                        if (marker) {
+                            document.body.removeChild(marker);
+                        }
+                    });
                 }
-                // 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.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.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": {