test(nvda-smoke): focus browser via NVDA Alt+Esc (foreground-lock safe)

Author: jon-bell

tests/e2e/a11y-nvda-smoke.ts

@@ -1,13 +1,17 @@
 // NVDA smoke: proves the self-hosted Windows runner drives REAL NVDA via
 // guidepup in CI (the Windows analog of the VoiceOver lane). Self-contained —
 // no deploy preview / OpenBao, and no extra deps: uses @guidepup/guidepup's
-// nvda driver (a repo dependency) + Playwright's bundled chromium. Launches a
-// static page, focuses it, walks the NVDA cursor, and asserts NVDA actually
-// spoke the page's content.
+// nvda driver + Playwright's bundled chromium (both already repo deps).
+//
+// The load-bearing trick (mirrors @guidepup/playwright's navigateToWebContent):
+// under a CI job the runner console holds the OS foreground, so SetForeground-
+// Window is blocked. Instead we bring the browser to NVDA's focus with
+// NVDA-driven Alt+Esc app-switching, verified by reading the window title —
+// which the OS honors regardless of foreground lock.
 //
 // Run:  npx tsx tests/e2e/a11y-nvda-smoke.ts
 import { chromium } from "@playwright/test";
-import { nvda, windowsActivate } from "@guidepup/guidepup";
+import { nvda, WindowsKeyCodes, WindowsModifiers } from "@guidepup/guidepup";
 import { mkdirSync, writeFileSync } from "node:fs";
 
 const PAGE =
@@ -23,6 +27,26 @@ const PAGE =
   );
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+const clean = (s: string) => s.toLowerCase().replace(/[^a-z0-9 ]+/g, " ").replace(/\s+/g, " ").trim();
+
+// Cycle windows via Alt+Esc until NVDA reports the browser window as focused.
+// NVDA reports its window title as e.g. "NVDA smoke - Google Chrome for Testing".
+// Alt+Esc is OS-honored regardless of foreground lock (unlike SetForegroundWindow).
+async function focusBrowser(pageTitle: string): Promise<{ ok: boolean; seen: string[] }> {
+  const want = clean(pageTitle);
+  const SWITCH = { keyCode: [WindowsKeyCodes.Escape], modifiers: [WindowsModifiers.Alt] };
+  const seen: string[] = [];
+  for (let i = 0; i < 12; i++) {
+    await nvda.perform(nvda.keyboardCommands.reportTitle);
+    await sleep(400); // let NVDA finish speaking before reading the phrase
+    const title = clean(await nvda.lastSpokenPhrase());
+    seen.push(title);
+    if (want.length && (title.startsWith(want) || title.includes("chrom"))) return { ok: true, seen };
+    await nvda.perform(SWITCH, { capture: false });
+    await sleep(700);
+  }
+  return { ok: false, seen };
+}
 
 async function main() {
   await nvda.start();
@@ -34,18 +58,12 @@ async function main() {
     });
     const page = await browser.newPage();
     await page.goto(PAGE);
-    await page.bringToFront();
-    await sleep(800);
-    // Force the Chromium window to the OS foreground so NVDA's browse cursor
-    // lands in it. Required in CI, where the runner's job console otherwise
-    // holds foreground and NVDA reads nothing (window title = page <title>).
-    await windowsActivate("chrome.exe", "NVDA smoke").catch(() => {});
-    await sleep(1200);
-    await page.locator("h1").click().catch(() => {});
-    await sleep(800);
+    await sleep(1000);
 
+    const focused = await focusBrowser("NVDA smoke");
+    console.log("focusBrowser ok=" + focused.ok + " titles seen: " + JSON.stringify(focused.seen));
     await nvda.clearSpokenPhraseLog();
-    await nvda.press("Control+Home"); // jump to top of document, reads the H1
+    await nvda.press("Control+Home"); // top of document, reads the H1
     for (let i = 0; i < 6; i++) {
       await nvda.next(); // walk paragraph, link, button
     }
@@ -60,9 +78,8 @@ async function main() {
     if (nonEmpty.length === 0) {
       throw new Error("NVDA produced no spoken content — the AT was not driven");
     }
-    const joined = nonEmpty.join(" | ").toLowerCase();
-    if (!joined.includes("smoke")) {
-      throw new Error("NVDA spoke, but did not read the smoke page (H1) — got: " + joined);
+    if (!nonEmpty.join(" | ").toLowerCase().includes("smoke")) {
+      throw new Error("NVDA spoke, but did not read the smoke page: " + nonEmpty.join(" | "));
     }
     console.log("SMOKE PASS: NVDA read the page (H1 + " + (nonEmpty.length - 1) + " more items)");
   } finally {