fix: handle windows browser focus loss better

Author: cmorten

.vscode/settings.json

@@ -5,5 +5,8 @@
   },
   "[yaml]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
   }
 }

README.md

@@ -73,7 +73,49 @@ export default config;
 
 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.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",

src/nvdaTest.ts

@@ -1,4 +1,4 @@
-import { Page, test } from "@playwright/test";
+import { test } from "@playwright/test";
 import { nvda, WindowsKeyCodes, WindowsModifiers } from "@guidepup/guidepup";
 import type { NVDA } from "@guidepup/guidepup";
 import { applicationNameMap } from "./applicationNameMap";
@@ -46,12 +46,15 @@ const SWITCH_APPLICATION = {
   modifiers: [WindowsModifiers.Alt],
 };
 
+const MOVE_TO_TOP = {
+  keyCode: [WindowsKeyCodes.Home],
+  modifiers: [WindowsModifiers.Control],
+};
+
 const focusBrowser = async ({
   applicationName,
-  page,
 }: {
   applicationName: string;
-  page: Page;
 }) => {
   await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
   let windowTitle = await nvdaPlaywright.lastSpokenPhrase();
@@ -60,11 +63,6 @@ const focusBrowser = async ({
     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) {
@@ -74,32 +72,7 @@ const focusBrowser = async ({
     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;
     }
   }
@@ -152,21 +125,33 @@ export const nvdaTest = test.extend<{
         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();

src/voiceOverTest.ts

@@ -94,12 +94,9 @@ export const voiceOverTest = test.extend<{
 
         // 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();