@guidepup/playwright 0.13.0 → 0.13.1

package/README.md

@@ -71,9 +71,51 @@ const config: PlaywrightTestConfig = {
 export default config;
 ```
 
-Check out the configuration this adds [in the `config.ts`` file](./src/config.ts).
+Check out the configuration this adds [in the `config.ts` file](./src/config.ts).
 
-### VoiceOver
+### Web Content Navigation
+
+In addition to the Guidepup APIs the `voiceOver` and `nvda` 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.
+
+Use this method after you navigate to a page and have made any necessary checks that the page has loaded as expected. For example, this is how you might use the method with NVDA:
+
+```ts
+// Navigate to the desired page
+await page.goto("https://github.com/guidepup/guidepup", {
+  waitUntil: "load",
+});
+
+// Wait for page to be ready
+await page.locator('header[role="banner"]').waitFor();
+
+// Navigate to the web content
+await nvda.navigateToWebContent();
+
+// ... some commands
+```
+
+**Note:** This command clears all logs meaning `.spokenPhraseLog()` and `.itemTextLog()` are emptied. If logs from prior to the command are required, first store the logs in a variable for later use:
+
+```ts
+// ... some commands
+
+// Store spoken phrases
+const spokenPhrases = await nvda.spokenPhraseLog();
+
+// Navigate to the web content
+await nvda.navigateToWebContent();
+
+// ... some commands
+
+// Collect all spoken phrasees
+const allSpokenPhrases = [...spokenPhrases, ...(await nvda.spokenPhraseLog())];
+
+// ... do something with spoken phrases
+```
+
+### VoiceOver Example
 
 `playwright.config.ts`:
 
@@ -131,7 +173,7 @@ test.describe("Playwright VoiceOver", () => {
 });
 ```
 
-### NVDA
+### NVDA Example
 
 `playwright.config.ts`:
 

package/lib/nvdaTest.js

@@ -10,41 +10,23 @@ const SWITCH_APPLICATION = {
     keyCode: [guidepup_1.WindowsKeyCodes.Escape],
     modifiers: [guidepup_1.WindowsModifiers.Alt],
 };
-const focusBrowser = async ({ applicationName, page, }) => {
+const MOVE_TO_TOP = {
+    keyCode: [guidepup_1.WindowsKeyCodes.Home],
+    modifiers: [guidepup_1.WindowsModifiers.Control],
+};
+const focusBrowser = async ({ applicationName, }) => {
     await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
     let windowTitle = await nvdaPlaywright.lastSpokenPhrase();
     if (windowTitle.includes(applicationName)) {
         return;
     }
-    // Firefox has a bug with NVDA where NVDA gets stuck in focus mode if
-    // Firefox is the currently focused application.
-    // REF: https://github.com/nvaccess/nvda/issues/5758
-    // We swap to a different application, restart NVDA, and then switch back.
     let applicationSwitchRetryCount = 0;
     while (applicationSwitchRetryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
         applicationSwitchRetryCount++;
         await nvdaPlaywright.perform(SWITCH_APPLICATION);
         await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
         windowTitle = await nvdaPlaywright.lastSpokenPhrase();
-        if (!windowTitle.includes(applicationName)) {
-            break;
-        }
-    }
-    await nvdaPlaywright.stop();
-    await nvdaPlaywright.start();
-    await page.bringToFront();
-    await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
-    windowTitle = await nvdaPlaywright.lastSpokenPhrase();
-    if (windowTitle.includes(applicationName)) {
-        return;
-    }
-    applicationSwitchRetryCount = 0;
-    while (applicationSwitchRetryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
-        applicationSwitchRetryCount++;
-        await nvdaPlaywright.perform(SWITCH_APPLICATION);
-        await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
-        windowTitle = await nvdaPlaywright.lastSpokenPhrase();
-        if (!windowTitle.includes(applicationName)) {
+        if (windowTitle.includes(applicationName)) {
             break;
         }
     }
@@ -67,16 +49,23 @@ exports.nvdaTest = test_1.test.extend({
             nvdaPlaywright.navigateToWebContent = async () => {
                 // Make sure NVDA is not in focus mode.
                 await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.exitFocusMode);
-                await nvdaPlaywright.lastSpokenPhrase();
                 // Ensure application is brought to front and focused.
-                await focusBrowser({ applicationName, page });
-                // Make sure NVDA is not in focus mode.
+                await focusBrowser({ applicationName });
+                // 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);
+                await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.toggleBetweenBrowseAndFocusMode);
+                await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.toggleBetweenBrowseAndFocusMode);
                 await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.exitFocusMode);
-                await nvdaPlaywright.lastSpokenPhrase();
-                // Ensure the document is ready and focused.
-                await page.bringToFront();
-                await page.locator("body").waitFor();
-                await page.locator("body").focus();
+                await nvdaPlaywright.perform(MOVE_TO_TOP);
                 // Clear out logs.
                 await nvdaPlaywright.clearItemTextLog();
                 await nvdaPlaywright.clearSpokenPhraseLog();

package/lib/voiceOverTest.js

@@ -27,9 +27,7 @@ exports.voiceOverTest = test_1.test.extend({
                 await page.locator("body").focus();
                 // Navigate to the beginning of the web content.
                 await voiceOverPlaywright.interact();
-                await voiceOverPlaywright.lastSpokenPhrase();
                 await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.jumpToLeftEdge);
-                await voiceOverPlaywright.lastSpokenPhrase();
                 // Clear out logs.
                 await voiceOverPlaywright.clearItemTextLog();
                 await voiceOverPlaywright.clearSpokenPhraseLog();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidepup/playwright",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Screen reader driver for Playwright tests.",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",