@guidepup/playwright 0.16.2 → 0.17.0

package/lib/index.d.ts

@@ -1,5 +1,7 @@
 export { nvdaTest } from "./nvdaTest";
 export type { NVDAPlaywright } from "./nvdaTest";
 export { screenReaderConfig } from "./screenReaderConfig";
+export { screenReaderTest } from "./screenReaderTest";
+export type { ScreenReaderPlaywright } from "./screenReaderTest";
 export { voiceOverTest } from "./voiceOverTest";
 export type { VoiceOverPlaywright } from "./voiceOverTest";

package/lib/index.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.voiceOverTest = exports.screenReaderConfig = exports.nvdaTest = void 0;
+exports.voiceOverTest = exports.screenReaderTest = exports.screenReaderConfig = exports.nvdaTest = void 0;
 var nvdaTest_1 = require("./nvdaTest");
 Object.defineProperty(exports, "nvdaTest", { enumerable: true, get: function () { return nvdaTest_1.nvdaTest; } });
 var screenReaderConfig_1 = require("./screenReaderConfig");
 Object.defineProperty(exports, "screenReaderConfig", { enumerable: true, get: function () { return screenReaderConfig_1.screenReaderConfig; } });
+var screenReaderTest_1 = require("./screenReaderTest");
+Object.defineProperty(exports, "screenReaderTest", { enumerable: true, get: function () { return screenReaderTest_1.screenReaderTest; } });
 var voiceOverTest_1 = require("./voiceOverTest");
 Object.defineProperty(exports, "voiceOverTest", { enumerable: true, get: function () { return voiceOverTest_1.voiceOverTest; } });

package/lib/nvdaTest.js

@@ -14,9 +14,19 @@ const MOVE_TO_TOP = {
     keyCode: [guidepup_1.WindowsKeyCodes.Home],
     modifiers: [guidepup_1.WindowsModifiers.Control],
 };
+const cleanString = (str) => str
+    .toLowerCase()
+    // REF: https://github.com/nvaccess/nvda/blob/master/source/locale/en/symbols.dic
+    .replace(/[|¦:;'"`\-‐–—·_()[\]{}\\^~]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
 const hasFocus = ({ applicationName, pageTitle, windowTitle, }) => {
-    return ((pageTitle.length && windowTitle.startsWith(pageTitle)) ||
-        windowTitle.includes(applicationName));
+    const cleanedApplicationName = cleanString(applicationName);
+    const cleanedPageTitle = cleanString(pageTitle);
+    const cleanedWindowTitle = cleanString(windowTitle);
+    return ((cleanedPageTitle.length &&
+        cleanedWindowTitle.startsWith(cleanedPageTitle)) ||
+        cleanedWindowTitle.includes(cleanedApplicationName));
 };
 const focusBrowser = async ({ applicationName, pageTitle, }) => {
     await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
@@ -49,14 +59,15 @@ exports.nvdaTest = test_1.test.extend({
             if (!applicationName) {
                 throw new Error(`Browser ${browserName} is not installed.`);
             }
-            await page.goto("about:blank", { waitUntil: "load" });
-            await page.bringToFront();
             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, pageTitle });
+                await focusBrowser({
+                    applicationName,
+                    pageTitle,
+                });
                 // Ensure the document is ready and focused.
                 await page.bringToFront();
                 await page.locator("body").waitFor();

package/lib/screenReaderTest.d.ts

@@ -0,0 +1,78 @@
+import { CommandOptions, type ScreenReader } from "@guidepup/guidepup";
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type CaptureCommandOptions = Prettify<Pick<CommandOptions, "capture">>;
+/**
+ * This object can be used to launch and control the default screen reader for
+ * the environment.
+ *
+ * Here's a typical example:
+ *
+ * ```ts
+ * import { screenReader } from "@guidepup/guidepup";
+ *
+ * (async () => {
+ *   // Start the screen reader.
+ *   await screenReader.start();
+ *
+ *   // Move to the next item.
+ *   await screenReader.next();
+ *
+ *   // ... perform some commands.
+ *
+ *   // Stop the screen reader.
+ *   await screenReader.stop();
+ * })();
+ * ```
+ */
+export interface ScreenReaderPlaywright extends ScreenReader {
+    /**
+     * Guidepup Playwright specific command that navigates the screen reader to
+     * the beginning of the browser's web content.
+     *
+     * This command should be used after page navigation.
+     *
+     * Note: this command clears all logs by default.
+     */
+    navigateToWebContent(clearLogs?: boolean): Promise<void>;
+}
+/**
+ * These tests extend the default Playwright environment that launches the
+ * browser with a running instance of the default screen reader for the current
+ * OS.
+ *
+ * A fresh started screen reader instance `screenReader` is provided to each
+ * test.
+ */
+export declare const screenReaderTest: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    /**
+     * This object can be used to launch and control the default screen reader for
+     * the environment.
+     *
+     * Here's a typical example:
+     *
+     * ```ts
+     * import { screenReader } from "@guidepup/guidepup";
+     *
+     * (async () => {
+     *   // Start the screen reader.
+     *   await screenReader.start();
+     *
+     *   // Move to the next item.
+     *   await screenReader.next();
+     *
+     *   // ... perform some commands.
+     *
+     *   // Stop the screen reader.
+     *   await screenReader.stop();
+     * })();
+     * ```
+     */
+    screenReader: ScreenReaderPlaywright;
+    /**
+     * Options to start the default screen reader with.
+     */
+    screenReaderStartOptions: CaptureCommandOptions;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export {};

package/lib/screenReaderTest.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.screenReaderTest = void 0;
+const test_1 = require("@playwright/test");
+const guidepup_1 = require("@guidepup/guidepup");
+const applicationNameMap_1 = require("./applicationNameMap");
+const MAX_APPLICATION_SWITCH_RETRY_COUNT = 10;
+const SWITCH_APPLICATION = {
+    keyCode: [guidepup_1.WindowsKeyCodes.Escape],
+    modifiers: [guidepup_1.WindowsModifiers.Alt],
+};
+const MOVE_TO_TOP = {
+    keyCode: [guidepup_1.WindowsKeyCodes.Home],
+    modifiers: [guidepup_1.WindowsModifiers.Control],
+};
+const cleanString = (str) => str
+    .toLowerCase()
+    // REF: https://github.com/nvaccess/nvda/blob/master/source/locale/en/symbols.dic
+    .replace(/[|¦:;'"`\-‐–—·_()[\]{}\\^~]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+const hasFocus = ({ applicationName, pageTitle, windowTitle, }) => {
+    const cleanedApplicationName = cleanString(applicationName);
+    const cleanedPageTitle = cleanString(pageTitle);
+    const cleanedWindowTitle = cleanString(windowTitle);
+    return ((cleanedPageTitle.length &&
+        cleanedWindowTitle.startsWith(cleanedPageTitle)) ||
+        cleanedWindowTitle.includes(cleanedApplicationName));
+};
+const focusBrowser = async ({ applicationName, pageTitle, }) => {
+    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.reportTitle);
+    let windowTitle = await screenReaderPlaywright.lastSpokenPhrase();
+    if (hasFocus({ applicationName, pageTitle, windowTitle })) {
+        return;
+    }
+    let applicationSwitchRetryCount = 0;
+    while (applicationSwitchRetryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
+        applicationSwitchRetryCount++;
+        await screenReaderPlaywright.perform(SWITCH_APPLICATION);
+        await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.reportTitle);
+        windowTitle = await screenReaderPlaywright.lastSpokenPhrase();
+        if (hasFocus({ applicationName, pageTitle, windowTitle })) {
+            break;
+        }
+    }
+};
+const screenReaderPlaywright = guidepup_1.screenReader;
+/**
+ * These tests extend the default Playwright environment that launches the
+ * browser with a running instance of the default screen reader for the current
+ * OS.
+ *
+ * A fresh started screen reader instance `screenReader` is provided to each
+ * test.
+ */
+exports.screenReaderTest = test_1.test.extend({
+    screenReaderStartOptions: { capture: "initial" },
+    screenReader: async ({ browserName, page, screenReaderStartOptions }, use) => {
+        try {
+            const applicationName = applicationNameMap_1.applicationNameMap[browserName];
+            if (!applicationName) {
+                throw new Error(`Browser ${browserName} is not installed.`);
+            }
+            if (guidepup_1.nvda.default()) {
+                screenReaderPlaywright.navigateToWebContent = async (clearLogs = true) => {
+                    // Make sure NVDA is not in focus mode.
+                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.exitFocusMode);
+                    const pageTitle = await page.title();
+                    // Ensure application is brought to front and focused.
+                    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.
+                    //
+                    // 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 screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.readNextFocusableItem);
+                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.toggleBetweenBrowseAndFocusMode);
+                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.toggleBetweenBrowseAndFocusMode);
+                    await screenReaderPlaywright.perform(guidepup_1.NVDAKeyCodeCommands.exitFocusMode);
+                    await screenReaderPlaywright.perform(MOVE_TO_TOP);
+                    if (clearLogs) {
+                        // Clear out logs.
+                        await screenReaderPlaywright.clearItemTextLog();
+                        await screenReaderPlaywright.clearSpokenPhraseLog();
+                    }
+                };
+            }
+            else if (guidepup_1.voiceOver.default()) {
+                screenReaderPlaywright.navigateToWebContent = async (clearLogs = true) => {
+                    await (0, guidepup_1.macOSActivate)(applicationName);
+                    await screenReaderPlaywright.perform({
+                        keyCode: guidepup_1.MacOSKeyCodes.Control,
+                    });
+                    await page.bringToFront();
+                    await page.locator("body").waitFor();
+                    await screenReaderPlaywright.perform(guidepup_1.voiceOverKeyCodeCommands.openItemChooser);
+                    await screenReaderPlaywright.type("web content");
+                    await screenReaderPlaywright.perform({
+                        keyCode: guidepup_1.MacOSKeyCodes.Enter,
+                    });
+                    await screenReaderPlaywright.interact();
+                    await screenReaderPlaywright.perform(guidepup_1.voiceOverKeyCodeCommands.moveToBeginningOfText);
+                    await screenReaderPlaywright.perform({
+                        keyCode: guidepup_1.MacOSKeyCodes.Control,
+                    });
+                    if (clearLogs) {
+                        await screenReaderPlaywright.clearItemTextLog();
+                        await screenReaderPlaywright.clearSpokenPhraseLog();
+                    }
+                };
+            }
+            else {
+                throw new Error("No supported screen reader");
+            }
+            await screenReaderPlaywright.start(screenReaderStartOptions);
+            await use(screenReaderPlaywright);
+        }
+        finally {
+            try {
+                await screenReaderPlaywright.stop();
+            }
+            catch {
+                // swallow stop failure
+            }
+        }
+    },
+});

package/lib/voiceOverTest.js

@@ -47,9 +47,6 @@ exports.voiceOverTest = test_1.test.extend({
                 }
             };
             await voiceOverPlaywright.start(voiceOverStartOptions);
-            await (0, guidepup_1.macOSActivate)(applicationName);
-            // Cancel auto navigation
-            await voiceOverPlaywright.perform({ keyCode: guidepup_1.MacOSKeyCodes.Control }, { capture: false });
             await use(voiceOverPlaywright);
         }
         finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidepup/playwright",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "Screen reader automation library for Playwright testing. ",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -34,15 +34,17 @@
     "prepublish": "yarn build",
     "pretest": "npx playwright install chromium firefox webkit",
     "test:nvda": "yarn test:nvda:chromium && yarn test:nvda:firefox",
+    "test:screenreader": "yarn test:screenreader:chromium",
     "test:voiceover": "yarn test:voiceover:chromium && yarn test:voiceover:firefox && yarn test:voiceover:webkit",
     "test:nvda:chromium": "playwright test --config ./examples/playwright-nvda/chromium.config.ts ./examples/playwright-nvda/tests/chromium/",
     "test:nvda:firefox": "playwright test --config ./examples/playwright-nvda/firefox.config.ts ./examples/playwright-nvda/tests/firefox/",
+    "test:screenreader:chromium": "playwright test --config ./examples/playwright-screenreader/chromium.config.ts ./examples/playwright-screenreader/tests/chromium/",
     "test:voiceover:chromium": "playwright test --config ./examples/playwright-voiceover/chromium.config.ts ./examples/playwright-voiceover/tests/chromium/",
     "test:voiceover:firefox": "playwright test --config ./examples/playwright-voiceover/firefox.config.ts ./examples/playwright-voiceover/tests/firefox/",
     "test:voiceover:webkit": "playwright test --config ./examples/playwright-voiceover/webkit.config.ts ./examples/playwright-voiceover/tests/webkit/"
   },
   "devDependencies": {
-    "@guidepup/guidepup": "^0.25.0",
+    "@guidepup/guidepup": "^0.27.0",
     "@guidepup/record": "^0.1.0",
     "@playwright/test": "^1.60.0",
     "@types/node": "^24.10.1",
@@ -56,7 +58,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@guidepup/guidepup": ">=0.25.0",
+    "@guidepup/guidepup": ">=0.27.0",
     "@playwright/test": "^1.57.0"
   },
   "resolutions": {