@guidepup/playwright 0.19.0 → 0.19.1

package/README.md

@@ -251,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/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,10 +156,16 @@ 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();
@@ -147,31 +193,18 @@ exports.screenReaderTest = test_1.test.extend({
                     `;
                             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);
+                        // 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);
-                        // 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);
+                        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 });

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,10 +61,16 @@ 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();
@@ -52,31 +98,18 @@ exports.voiceOverTest = test_1.test.extend({
             `;
                         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);
+                    // 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);
-                    // 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);
+                    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 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidepup/playwright",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Screen reader automation library for Playwright testing. ",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",