@guidepup/playwright 0.15.0 → 0.16.0

package/README.md

@@ -6,12 +6,11 @@
 
 ## [Documentation](https://guidepup.dev) | [API Reference](https://www.guidepup.dev/docs/api/class-guidepup)
 
-[![MacOS Monetary Support](https://img.shields.io/badge/macos-Monetary-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-monterey/id1576738294)
-[![MacOS Ventura Support](https://img.shields.io/badge/macos-Ventura-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-ventura/id1638787999)
 [![MacOS Sonoma Support](https://img.shields.io/badge/macos-Somona-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-sonoma/id6450717509)
-[![Windows 10 Support](https://img.shields.io/badge/windows-10-blue.svg?logo=windows10)](https://www.microsoft.com/en-gb/software-download/windows10ISO)
-[![Windows Server 2019 Support](https://img.shields.io/badge/windows_server-2019-blue.svg?logo=windows)](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2019)
+[![MacOS Sequoia Support](https://img.shields.io/badge/macos-Somona-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-sequoia/id6596773750)
+[![MacOS Tahoe Support](https://img.shields.io/badge/macos-Tahoe-blue.svg?logo=apple)](https://www.apple.com/uk/os/macos/)
 [![Windows Server 2022 Support](https://img.shields.io/badge/windows_server-2022-blue.svg?logo=windows)](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2022)
+[![Windows Server 2025 Support](https://img.shields.io/badge/windows_server-2025-blue.svg?logo=windows)](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2025)
 
 This package provides [Guidepup](https://github.com/guidepup/guidepup) integration with [Playwright](https://playwright.dev/) for writing screen reader tests that automate <a href="https://www.guidepup.dev/docs/api/class-voiceover"><b>VoiceOver on MacOS</b></a> and <a href="https://www.guidepup.dev/docs/api/class-nvda"><b>NVDA on Windows</b></a>.
 
@@ -95,7 +94,7 @@ 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:
+**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
@@ -114,6 +113,17 @@ const allSpokenPhrases = [...spokenPhrases, ...(await nvda.spokenPhraseLog())];
 // ... do something with spoken phrases
 ```
 
+or pass a flag to prevent log clearing:
+
+```ts
+// ... some commands
+
+// Navigate to the web content
+await nvda.navigateToWebContent(false);
+
+// ... some commands
+```
+
 ### Providing Screen Reader Start Options
 
 The options provided to `nvda.start([options])` or `voiceOver.start([options])` can be configured using `test.use(config)` as follows:
@@ -122,16 +132,20 @@ The options provided to `nvda.start([options])` or `voiceOver.start([options])`
 // VoiceOver Example
 import { voiceOverTest as test } from "@guidepup/playwright";
 
-test.use({ voiceOverStartOptions: { capture: "initial" } });
+// Capture all spoken phrases, including usage hints
+test.use({ voiceOverStartOptions: { capture: true } });
 ```
 
 ```ts
 // NVDA Example
 import { nvdaTest as test } from "@guidepup/playwright";
 
-test.use({ nvdaStartOptions: { capture: "initial" } });
+// Capture all spoken phrases, including usage hints
+test.use({ nvdaStartOptions: { capture: true } });
 ```
 
+The default for VoiceOver and NVDA is set to `"initial"`. `true` captures all spoken phrases, including usage hints. `false` disables spoken phrase capture.
+
 ### VoiceOver Example
 
 `playwright.config.ts`:
@@ -148,6 +162,8 @@ const config: PlaywrightTestConfig = {
   projects: [
     {
       name: "webkit",
+      // Take care to ensure all usage is headed - screen readers cannot
+      // operate against headless browsers.
       use: { ...devices["Desktop Safari"], headless: false },
     },
   ],
@@ -206,6 +222,8 @@ const config: PlaywrightTestConfig = {
   projects: [
     {
       name: "firefox",
+      // Take care to ensure all usage is headed - screen readers cannot
+      // operate against headless browsers.
       use: { ...devices["Desktop Firefox"], headless: false },
     },
   ],

package/lib/nvdaTest.d.ts

@@ -32,9 +32,9 @@ export interface NVDAPlaywright extends NVDA {
      *
      * This command should be used after page navigation.
      *
-     * Note: this command clears all logs.
+     * Note: this command clears all logs by default.
      */
-    navigateToWebContent(): Promise<void>;
+    navigateToWebContent(clearLogs?: boolean): Promise<void>;
 }
 /**
  * These tests extend the default Playwright environment that launches the

package/lib/nvdaTest.js

@@ -14,10 +14,14 @@ const MOVE_TO_TOP = {
     keyCode: [guidepup_1.WindowsKeyCodes.Home],
     modifiers: [guidepup_1.WindowsModifiers.Control],
 };
-const focusBrowser = async ({ applicationName, }) => {
+const hasFocus = ({ applicationName, pageTitle, windowTitle, }) => {
+    return ((pageTitle.length && windowTitle.startsWith(pageTitle)) ||
+        windowTitle.includes(applicationName));
+};
+const focusBrowser = async ({ applicationName, pageTitle, }) => {
     await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
     let windowTitle = await nvdaPlaywright.lastSpokenPhrase();
-    if (windowTitle.includes(applicationName)) {
+    if (hasFocus({ applicationName, pageTitle, windowTitle })) {
         return;
     }
     let applicationSwitchRetryCount = 0;
@@ -26,7 +30,7 @@ const focusBrowser = async ({ applicationName, }) => {
         await nvdaPlaywright.perform(SWITCH_APPLICATION);
         await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
         windowTitle = await nvdaPlaywright.lastSpokenPhrase();
-        if (windowTitle.includes(applicationName)) {
+        if (hasFocus({ applicationName, pageTitle, windowTitle })) {
             break;
         }
     }
@@ -38,7 +42,7 @@ const focusBrowser = async ({ applicationName, }) => {
  * A fresh started NVDA instance `nvda` is provided to each test.
  */
 exports.nvdaTest = test_1.test.extend({
-    nvdaStartOptions: {},
+    nvdaStartOptions: { capture: "initial" },
     nvda: async ({ browserName, page, nvdaStartOptions }, use) => {
         try {
             const applicationName = applicationNameMap_1.applicationNameMap[browserName];
@@ -47,11 +51,18 @@ exports.nvdaTest = test_1.test.extend({
             }
             await page.goto("about:blank", { waitUntil: "load" });
             await page.bringToFront();
-            nvdaPlaywright.navigateToWebContent = async () => {
+            nvdaPlaywright.navigateToWebContent = async (clearLogs = true) => {
                 // Make sure NVDA is not in focus mode.
                 await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.exitFocusMode);
+                const pageTitle = await page.title();
                 // Ensure application is brought to front and focused.
-                await focusBrowser({ applicationName });
+                await focusBrowser({ applicationName, pageTitle });
+                // Ensure the document is ready and focused.
+                await page.bringToFront();
+                await page.locator("body").waitFor();
+                await page.locator("body").focus();
+                await page.locator("body").click();
+                await page.locator("body").blur();
                 // NVDA appears to not work well with Firefox when switching between
                 // applications resulting in the entire browser window having NVDA focus
                 // with focus mode.
@@ -67,9 +78,11 @@ exports.nvdaTest = test_1.test.extend({
                 await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.toggleBetweenBrowseAndFocusMode);
                 await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.exitFocusMode);
                 await nvdaPlaywright.perform(MOVE_TO_TOP);
-                // Clear out logs.
-                await nvdaPlaywright.clearItemTextLog();
-                await nvdaPlaywright.clearSpokenPhraseLog();
+                if (clearLogs) {
+                    // Clear out logs.
+                    await nvdaPlaywright.clearItemTextLog();
+                    await nvdaPlaywright.clearSpokenPhraseLog();
+                }
             };
             await nvdaPlaywright.start(nvdaStartOptions);
             await use(nvdaPlaywright);

package/lib/screenReaderConfig.d.ts

@@ -2,5 +2,7 @@ import { PlaywrightTestConfig } from "@playwright/test";
 export type ScreenReaderPlaywrightTestConfig = PlaywrightTestConfig;
 /**
  * Minimal required configuration for Screen Reader tests in Playwright.
+ *
+ * Depending on your configuration this may not be sufficient.
  */
 export declare const screenReaderConfig: ScreenReaderPlaywrightTestConfig;

package/lib/screenReaderConfig.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.screenReaderConfig = void 0;
 /**
  * Minimal required configuration for Screen Reader tests in Playwright.
+ *
+ * Depending on your configuration this may not be sufficient.
  */
 exports.screenReaderConfig = {
     /**

package/lib/voiceOverTest.d.ts

@@ -28,11 +28,11 @@ export interface VoiceOverPlaywright extends VoiceOver {
      * Guidepup Playwright specific command that navigates VoiceOver to the beginning
      * of the browser's web content.
      *
-     * This command should be used after page navigation.
+     * This command should be used after a page navigation has completed.
      *
-     * Note: this command clears all logs.
+     * Note: this command clears all logs by default.
      */
-    navigateToWebContent(): Promise<void>;
+    navigateToWebContent(clearLogs?: boolean): Promise<void>;
 }
 /**
  * These tests extend the default Playwright environment that launches the

package/lib/voiceOverTest.js

@@ -12,26 +12,36 @@ const voiceOverPlaywright = guidepup_1.voiceOver;
  * A fresh started VoiceOver instance `voiceOver` is provided to each test.
  */
 exports.voiceOverTest = test_1.test.extend({
-    voiceOverStartOptions: {},
+    voiceOverStartOptions: { capture: "initial" },
     voiceOver: async ({ browserName, page, voiceOverStartOptions }, use) => {
         try {
             const applicationName = applicationNameMap_1.applicationNameMap[browserName];
             if (!applicationName) {
                 throw new Error(`Browser ${browserName} is not installed.`);
             }
-            voiceOverPlaywright.navigateToWebContent = async () => {
+            voiceOverPlaywright.navigateToWebContent = async (clearLogs = true) => {
                 // Ensure application is brought to front and focused.
                 await (0, guidepup_1.macOSActivate)(applicationName);
                 // Ensure the document is ready and focused.
                 await page.bringToFront();
                 await page.locator("body").waitFor();
                 await page.locator("body").focus();
-                // Navigate to the beginning of the web content.
+                await page.locator("body").click();
+                await page.locator("body").blur();
+                // Try to navigate into web content.
                 await voiceOverPlaywright.interact();
-                await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.jumpToLeftEdge);
-                // Clear out logs.
-                await voiceOverPlaywright.clearItemTextLog();
-                await voiceOverPlaywright.clearSpokenPhraseLog();
+                // Series of find previous commands to escape accidental interaction
+                // with sub-content of web content area.
+                await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.findPreviousHeading);
+                await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.findPreviousGraphic);
+                await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.findPreviousPlainText);
+                // Navigate to the beginning of the web content.
+                await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.moveToBeginningOfText);
+                if (clearLogs) {
+                    // Clear out logs.
+                    await voiceOverPlaywright.clearItemTextLog();
+                    await voiceOverPlaywright.clearSpokenPhraseLog();
+                }
             };
             await voiceOverPlaywright.start(voiceOverStartOptions);
             await (0, guidepup_1.macOSActivate)(applicationName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidepup/playwright",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Screen reader driver for Playwright tests.",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -8,7 +8,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/guidepup/guidepup-playwright"
+    "url": "git+https://github.com/guidepup/guidepup-playwright.git"
   },
   "bugs": {
     "url": "https://github.com/guidepup/guidepup-playwright/issues"
@@ -42,9 +42,9 @@
     "test:voiceover:webkit": "playwright test --config ./examples/playwright-voiceover/webkit.config.ts ./examples/playwright-voiceover/tests/webkit/"
   },
   "devDependencies": {
-    "@guidepup/guidepup": "^0.24.0",
+    "@guidepup/guidepup": "^0.25.0",
     "@guidepup/record": "^0.1.0",
-    "@playwright/test": "^1.58.0",
+    "@playwright/test": "^1.60.0",
     "@types/node": "^24.10.1",
     "@typescript-eslint/eslint-plugin": "^8.48.1",
     "@typescript-eslint/parser": "^8.48.1",
@@ -56,7 +56,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@guidepup/guidepup": ">=0.22.1",
+    "@guidepup/guidepup": ">=0.25.0",
     "@playwright/test": "^1.57.0"
   },
   "resolutions": {