From 989049f9207d3ed2d6107f9614f05d3fd9d2c24e Mon Sep 17 00:00:00 2001 From: SandroMaglione Date: Tue, 17 Nov 2026 06:36:21 +1300 Subject: [PATCH 1/2] ritmo-devtools keyboard: walk a game's page by keyboard in Chromium A new CLI command plays the page by keyboard on each screen of a route and fails on six generic invariants: a menu open with focus outside it, Tab leaving an open menu, a control with no accessible name, Enter or Space not pressing the focused control (its click stopped, so nothing changes), a press that drops focus to (pressed for real on a fresh load), and a visible control neither Tab nor its group's arrows reach. A check it cannot decide is printed as not checked with the reason, never as passed; a failed route step or a page error is a failure, and that screen's checks are not checked. Each failure names the check, the screen, the control (Chromium's role and name, a selector), what was seen, and the fix. Without --url it serves the working directory with the game's Vite config. Routes are validated with messages that name the bad field. The tests run fixture pages in Chromium where it is downloaded (the CI browser job) and skip elsewhere, like the engine tests. The UI playbook's check line names the command. Co-Authored-By: Claude Opus 5.5 --- .changeset/devtools-keyboard-walk.md | 5 + .changeset/ui-playbook-keyboard-check.md | 5 + .github/workflows/ci.yml | 2 +- .../skills/ritmo/playbooks/ui-and-render.md | 2 +- packages/devtools/README.md | 79 ++- packages/devtools/src/cli.ts | 127 +++- .../devtools/src/internal/keyboardPage.ts | 187 +++++ .../devtools/src/internal/keyboardWalk.ts | 639 ++++++++++++++++++ packages/devtools/test/KeyboardWalk.test.ts | 232 +++++++ .../test/fixtures/keyboard/focus-dropped.html | 15 + .../fixtures/keyboard/focus-outside-menu.html | 6 + .../test/fixtures/keyboard/index.html | 41 ++ .../fixtures/keyboard/key-not-pressed.html | 9 + .../test/fixtures/keyboard/page-error.html | 5 + .../fixtures/keyboard/tab-leaves-menu.html | 8 + .../fixtures/keyboard/unnamed-control.html | 5 + .../keyboard/unreachable-control.html | 5 + 17 files changed, 1366 insertions(+), 6 deletions(-) create mode 100644 .changeset/devtools-keyboard-walk.md create mode 100644 .changeset/ui-playbook-keyboard-check.md create mode 100644 packages/devtools/src/internal/keyboardPage.ts create mode 100644 packages/devtools/src/internal/keyboardWalk.ts create mode 100644 packages/devtools/test/KeyboardWalk.test.ts create mode 100644 packages/devtools/test/fixtures/keyboard/focus-dropped.html create mode 100644 packages/devtools/test/fixtures/keyboard/focus-outside-menu.html create mode 100644 packages/devtools/test/fixtures/keyboard/index.html create mode 100644 packages/devtools/test/fixtures/keyboard/key-not-pressed.html create mode 100644 packages/devtools/test/fixtures/keyboard/page-error.html create mode 100644 packages/devtools/test/fixtures/keyboard/tab-leaves-menu.html create mode 100644 packages/devtools/test/fixtures/keyboard/unnamed-control.html create mode 100644 packages/devtools/test/fixtures/keyboard/unreachable-control.html diff --git a/.changeset/devtools-keyboard-walk.md b/.changeset/devtools-keyboard-walk.md new file mode 100644 index 00000000..4af6fe18 --- /dev/null +++ b/.changeset/devtools-keyboard-walk.md @@ -0,0 +1,5 @@ +--- +"@typeonce/ritmo-devtools": minor +--- + +`ritmo-devtools keyboard [--url ] [--route ] [--json]` plays the game's page by keyboard in Chromium and fails on what breaks keyboard play: a menu open with focus outside it, Tab leaving an open menu, a control with no accessible name, Enter or Space not pressing the focused control, a press that drops focus to ``, and a visible control the keyboard cannot reach. Each failure names the check, the screen, the control (role, name, selector), what was seen, and the fix; a check it cannot decide is printed as not checked, never as passed. Without `--url` it serves the working directory with the game's own Vite config. A route file lists the screens to visit and how to reach them; without one, the start page is the only screen. It presses controls for real to check focus, so a route marks what must not be pressed. It uses the optional `playwright` and `vite` peers `verify` already uses, at the same versions. diff --git a/.changeset/ui-playbook-keyboard-check.md b/.changeset/ui-playbook-keyboard-check.md new file mode 100644 index 00000000..201773d6 --- /dev/null +++ b/.changeset/ui-playbook-keyboard-check.md @@ -0,0 +1,5 @@ +--- +"@typeonce/ritmo": patch +--- + +The `ritmo` skill's UI playbook (`ui-and-render.md`) checks a page with DOM controls with `ritmo-devtools keyboard`, on a route through every screen that shows them. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 29501404..1792f982 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -97,7 +97,7 @@ jobs: # The check job skips these without browsers. - name: Browser engine tests - run: pnpm vitest run packages/devtools/test/PlaywrightEngine.test.ts + run: pnpm vitest run packages/devtools/test/PlaywrightEngine.test.ts packages/devtools/test/KeyboardWalk.test.ts # Pull requests only: on main the change is already merged, so a result # there could not stop it. diff --git a/packages/core/skills/ritmo/playbooks/ui-and-render.md b/packages/core/skills/ritmo/playbooks/ui-and-render.md index cea8e6b5..6d81e4f3 100644 --- a/packages/core/skills/ritmo/playbooks/ui-and-render.md +++ b/packages/core/skills/ritmo/playbooks/ui-and-render.md @@ -13,4 +13,4 @@ 7. Build each DOM control (a button, a toggle, a slider) once and update its text and attributes in place; never rewrite a region that holds one (`innerHTML`, `replaceChildren`): the rewrite deletes the focused control and drops focus to ``. Give every control a name a test can find it by: its text, or `aria-label` on an icon. 8. A menu that stops play is a modal: `showModal()` on a ``, which moves focus in, keeps it there, and makes the page behind inert; an element with `aria-modal="true"` must do all three itself. The menu's own keys (arrows, letters) listen on that element. Handle a ``'s `cancel` and `close` events as intents and show it again from the game's state, because the browser closes a dialog on a repeated Escape even when `cancel` is prevented. A splash or wipe that must cover a menu is a `popover="manual"` shown after it, never a `z-index`; a layer the player presses (a crash panel) is its own modal dialog, since everything outside the newest modal is inert. -**Check:** the simulation's headless tests pass unchanged, and the game's check passes. +**Check:** the simulation's headless tests pass unchanged, and the game's check passes. When the page has DOM controls, `ritmo-devtools keyboard` passes with a route through every screen that shows them (the `@typeonce/ritmo-devtools` README). diff --git a/packages/devtools/README.md b/packages/devtools/README.md index 867554e1..28315ea3 100644 --- a/packages/devtools/README.md +++ b/packages/devtools/README.md @@ -11,7 +11,7 @@ pnpm add -D @typeonce/ritmo-devtools The main import (`Session`, `Fuzz`, `Invariant`, `Replay`, `Lint`, ...) and `ritmo-devtools lint` need no peer dependency. Each optional peer is for one feature: `playwright` and `vite` for runs in browser engines -(`PlaywrightEngine`, `ritmo-devtools verify`), `vite` for `ReplayVitePlugin`, +(`PlaywrightEngine`, `ritmo-devtools verify`, `ritmo-devtools keyboard`), `vite` for `ReplayVitePlugin`, and `rolldown` and `oxlint` for `ritmo-devtools scan`. The package reads the core `Debug` handle, which exists only on runtimes made @@ -528,6 +528,83 @@ ritmo-devtools scan src/simulation/index.ts missing tool). `--json` prints `{ entry, files, packages: [{ name, files, findings: [{ file, line, column, rule, snippet }] }] }`. +## Keyboard walk + +`ritmo-devtools keyboard` plays the game's page by keyboard in Chromium and +fails on what breaks keyboard play, whatever the game. Run it after a change +to the page's DOM controls or menus: + +```sh +ritmo-devtools keyboard --route keyboard.json +# FAIL focus-outside-menu [title] dialog "Paused" at #menu: this menu is open and focus is on . Fix: move focus into the menu when it opens: ... +# FAIL key-not-pressed [play] button "Menu" at #pause: Space with it focused did not press it: a key listener called preventDefault() on its keydown. Fix: ... +# +# [title] +# FAIL focus-outside-menu (1 decided) +# pass tab-leaves-menu (1 decided) +# ... +# not checked focus-dropped +# not checked link "Discord" at #links > a: a link to another site is not pressed for real +# +# keyboard walk of http://127.0.0.1:52011/: 2 failures; checks 2 failed, 9 passed, 1 not checked on 2 screens +``` + +Each screen gets six checks: + +| check | fails when | +| --- | --- | +| `focus-outside-menu` | a menu is open and focus is outside it | +| `tab-leaves-menu` | Tab moves focus out of the open menu | +| `unnamed-control` | a control Tab reaches has no accessible name | +| `key-not-pressed` | Enter or Space on the focused control does not press it | +| `focus-dropped` | pressing a control drops focus to `` | +| `unreachable-control` | a visible control is reached neither by Tab nor by the arrow keys of its group (a roving group with one Tab stop passes) | + +A menu is a `` opened with `showModal()`, a shown +`aria-modal="true"` element, or a shown dialog (``, +`role="dialog"`). Names and roles are Chromium's own, from its accessibility +tree. A check that cannot be decided on a screen (no menu open, nothing Tab +reaches) is printed as not checked with the reason, never as passed. Each +failure line names the check, the screen, the control (role, name, and a +CSS selector that finds it), what was seen, and the fix. + +`key-not-pressed` stops the click it caused, so it changes nothing a click +would; a custom control (a `role="switch"`) counts as pressed when its +`aria-checked`, `aria-pressed`, `aria-expanded`, or `aria-selected` changes. +`focus-dropped` presses each control for real, on a fresh load of its +screen, so it does what a player's press does: mark what must not be pressed +in the route. A link to another site is never pressed for real. + +Without `--route` the start page is one screen. A route is a JSON file: + +```json +{ + "screens": [ + { "name": "title" }, + { "name": "play", "path": "?seed=7", "steps": [{ "click": { "role": "button", "name": "Play" } }, { "press": "s" }, { "wait": 800 }] }, + { "name": "end", "path": "?moment=end", "steps": [{ "wait": 5000 }], "noPress": [{ "name": "Start over", "role": "button" }] } + ] +} +``` + +- `path` is appended to the URL. `steps` run in order after the page + settles: `press` takes a key as Playwright names it, `click` a role and + the accessible name the report prints, `wait` milliseconds. +- `noPress` is `true` (press nothing on that screen) or a list of controls + by name and optional role. +- A step that cannot run, or an error the page throws, is a failure, and + that screen's checks are not checked. + +- Without `--url` it serves the working directory with the game's own Vite + config; `--url` walks a page already served. It needs `playwright` and its + Chromium (`npm install --save-dev playwright vite` and + `npx playwright install chromium`); a missing one is printed with its + install command. +- Exit codes: 0 nothing failed, 1 a check failed, a route step failed, or the + page threw, 2 usage error (arguments, a route that is not valid, a missing + tool, a dev server that did not start). `--json` prints + `{ ok, url, screens, failures: [{ check, screen, control?, saw, fix }], outcomes: [{ check, screen, status, decided, undecided }] }`. + ## Fuzzing `Fuzz.run` finds a bug before anyone plays into it: seeded random input, diff --git a/packages/devtools/src/cli.ts b/packages/devtools/src/cli.ts index 6a620182..b0cfee78 100755 --- a/packages/devtools/src/cli.ts +++ b/packages/devtools/src/cli.ts @@ -5,6 +5,7 @@ * ritmo-devtools lint * ritmo-devtools verify [--engines node,chromium,webkit,firefox] [--json] * ritmo-devtools scan [--json] + * ritmo-devtools keyboard [--url ] [--route ] [--json] * * `lint` imports `` (a module exporting `lintTarget`, see the `Lint` module), * prints every lint of its schedules with its fix, and exits with 1 when one @@ -54,9 +55,22 @@ * and the game's `oxlint` with `@typeonce/oxlint-plugin-ritmo`; a missing one * is printed with its install command and exits with 2. * + * `keyboard` plays the game's page by keyboard in Chromium and checks, on + * each screen of a route, what a keyboard player relies on: focus moves into + * an open menu and Tab stays there, every control has a name, Enter and + * Space press the focused control, a press keeps focus off ``, and + * every visible control is reached by Tab or by its group's arrow keys. + * Without `--url` it serves the working directory with the game's own Vite + * config. `--route ` names the screens to visit (JSON, see the README); + * without it the start page is one screen. It needs `playwright` and its + * Chromium, and `vite` when there is no `--url`; a missing one is printed + * with its install command. + * * Exit codes: 0 ok (and every `scan` that ran), 1 lint warning, uncovered - * module, mismatched versions, or an engine that differs or did not run, 2 usage error (for `scan` - * also an unreadable entry, an import that does not resolve, or a missing tool). + * module, mismatched versions, an engine that differs or did not run, or a + * keyboard failure, 2 usage error (for `scan` also an unreadable entry, an + * import that does not resolve, or a missing tool; for `keyboard` an invalid + * route, a missing tool, or a dev server that did not start). * Requires Node 22.15 or later for `module.registerHooks`; on older Node it * prints that coverage was not checked. * @@ -68,6 +82,7 @@ import { resolve } from "node:path" import { pathToFileURL } from "node:url" import * as DependencyScan from "./internal/dependencyScan.ts" +import * as KeyboardWalk from "./internal/keyboardWalk.ts" import * as PackageVersions from "./internal/packageVersions.ts" import * as SimulationCoverage from "./internal/simulationCoverage.ts" import * as SkillLink from "./internal/skillLink.ts" @@ -79,9 +94,11 @@ const usage = [ "usage: ritmo-devtools lint ", " ritmo-devtools verify [--engines node,chromium,webkit,firefox] [--json]", " ritmo-devtools scan [--json]", + " ritmo-devtools keyboard [--url ] [--route ] [--json]", " lint: exports lintTarget: () => { runtime, schedules, describe?, hostEvents? } (see the Lint module)", " verify: exports replayTarget: (playback) => { runtime, schedules, hostClock } (see the Verify module)", - " scan: is the simulation's entry module; every file it imports, node_modules included, is checked for Math, clock, and randomness calls" + " scan: is the simulation's entry module; every file it imports, node_modules included, is checked for Math, clock, and randomness calls", + " keyboard: plays the page at --url (or the working directory served with its Vite config) by keyboard in Chromium; --route is a JSON file of screens" ].join("\n") const isRecord = (value: unknown): value is Record => typeof value === "object" && value !== null @@ -101,6 +118,7 @@ const main = async (args: ReadonlyArray): Promise => { if (command === "lint" && rest.length === 1) return lint(rest[0]!) if (command === "verify") return verify(rest) if (command === "scan") return scan(rest) + if (command === "keyboard") return keyboard(rest) console.error(usage) return 2 } @@ -223,6 +241,109 @@ const scan = async (args: ReadonlyArray): Promise => { return 0 } +/** The value of `--name value` or `--name=value` at `index`, and how many arguments it took; undefined when `args[index]` is not that flag. */ +const flag = (args: ReadonlyArray, index: number, name: string): { readonly value: string | undefined; readonly taken: number } | undefined => { + const arg = args[index]! + if (arg === name) return { value: args[index + 1], taken: 2 } + if (arg.startsWith(`${name}=`)) return { value: arg.slice(name.length + 1), taken: 1 } + return undefined +} + +const keyboard = async (args: ReadonlyArray): Promise => { + let url: string | undefined + let routeFile: string | undefined + let json = false + for (let index = 0; index < args.length;) { + if (args[index] === "--json") { + json = true + index++ + continue + } + const given = flag(args, index, "--url") ?? flag(args, index, "--route") + if (given === undefined || given.value === undefined || given.value === "") { + console.error(usage) + return 2 + } + if (args[index]!.startsWith("--url")) url = given.value + else routeFile = given.value + index += given.taken + } + if (url !== undefined && !/^https?:\/\//.test(url)) { + console.error(`--url must be an http(s) URL of the game's page, such as http://localhost:5173/; got ${url}`) + return 2 + } + let route = KeyboardWalk.startRoute + if (routeFile !== undefined) { + let data: unknown + try { + data = JSON.parse(readFileSync(resolve(routeFile), "utf8")) + } catch (error) { + console.error(`${routeFile} could not be read as JSON: ${error instanceof Error ? error.message : String(error)}`) + return 2 + } + const parsed = KeyboardWalk.parseRoute(data) + if (!parsed.ok) { + console.error(`${routeFile} is not a keyboard route: ${parsed.error}`) + return 2 + } + route = parsed.value + } + let playwright: typeof import("playwright") + try { + playwright = await import("playwright") + } catch { + console.error("keyboard needs playwright, which is not installed: npm install --save-dev playwright && npx playwright install chromium") + return 2 + } + let browser: Awaited> + try { + browser = await playwright.chromium.launch() + } catch (error) { + const message = error instanceof Error ? error.message : String(error) + console.error(/Executable doesn't exist|playwright install/i.test(message) + ? "keyboard needs Chromium, which is not downloaded: npx playwright install chromium" + : `Chromium did not launch: ${message.split("\n")[0]}`) + return 2 + } + let server: { readonly close: () => Promise } | undefined + try { + if (url === undefined) { + let vite: typeof import("vite") + try { + vite = await import("vite") + } catch { + console.error("keyboard serves the game with its own Vite config and needs vite, which is not installed: npm install --save-dev vite (or pass --url of a running dev server)") + return 2 + } + try { + const dev = await vite.createServer({ + root: process.cwd(), + logLevel: "silent", + clearScreen: false, + server: { host: "127.0.0.1", port: 0, strictPort: false, hmr: false, watch: null } + }) + server = dev + await dev.listen() + const address = dev.httpServer?.address() + if (address === null || address === undefined || typeof address === "string") { + console.error("the Vite dev server did not report its port") + return 2 + } + url = `http://127.0.0.1:${address.port}/` + } catch (error) { + console.error(`the game's Vite dev server did not start: ${error instanceof Error ? error.message : String(error)}`) + return 2 + } + } + const report = await KeyboardWalk.walk(browser, { url, route }) + console.log(json ? JSON.stringify(report, null, 2) : KeyboardWalk.format(report)) + return report.ok ? 0 : 1 + } finally { + await browser.close().catch(() => undefined) + await server?.close().catch(() => undefined) + } +} + const withoutText = ({ text: _text, ...error }: Verify.VerifyError) => error process.exitCode = await main(process.argv.slice(2)) diff --git a/packages/devtools/src/internal/keyboardPage.ts b/packages/devtools/src/internal/keyboardPage.ts new file mode 100644 index 00000000..e2c6f874 --- /dev/null +++ b/packages/devtools/src/internal/keyboardPage.ts @@ -0,0 +1,187 @@ +/** + * The page side of `ritmo-devtools keyboard`: a script installed before the + * game's own scripts on every page the walk opens. It runs in the browser, + * so it is plain JavaScript in a string: Node never runs it, and the package + * config has no DOM types. + * + * It installs `__ritmoKeyboardWalk` with: + * + * - `state()`: the focused element and the open menu, each described; + * - `controls(scope)`: the visible, enabled controls inside the menu (or the + * page), described; + * - `groupStops(control, stops)`: the Tab stops in the smallest element that + * holds the control and at least one stop, for the arrow-key probe; + * - `arm(stop)` and `result()`: around one key press, whether the focused + * control was pressed (a `click` reached it, or its `aria-checked`, + * `aria-pressed`, `aria-expanded`, or `aria-selected` changed) and whether + * a listener prevented the key; with `stop`, the click is stopped at + * `window` before any game listener runs, so a press through `click` + * changes nothing (a control that acts on keydown still acts); + * - `element(id)`, `focus(id)`: an element by the id the walk gave it. + * + * Elements are identified through a `WeakMap`, so the game's DOM is never + * changed. + */ +export const pageScript = String.raw`(() => { + if (globalThis.__ritmoKeyboardWalk) return + const ids = new WeakMap() + const byId = new Map() + let next = 1 + const idOf = (element) => { + let id = ids.get(element) + if (id === undefined) { + id = next++ + ids.set(element, id) + byId.set(id, new WeakRef(element)) + } + return id + } + const element = (id) => byId.get(id)?.deref() ?? null + const shown = (element) => typeof element.checkVisibility === "function" && element.checkVisibility({ visibilityProperty: true, opacityProperty: true }) === true + const visible = (element) => { + if (!shown(element)) return false + const box = element.getBoundingClientRect() + return box.width > 0 && box.height > 0 + } + const last = (list) => list.length === 0 ? null : list[list.length - 1] + const openMenu = () => + last([...document.querySelectorAll("dialog:modal")]) + ?? last([...document.querySelectorAll('[aria-modal="true"]')].filter(shown)) + ?? last([...document.querySelectorAll('dialog[open], [role="dialog"], [role="alertdialog"]')].filter(shown)) + const selector = (element) => { + const parts = [] + let at = element + while (at !== null && at.nodeType === 1 && at !== document.documentElement) { + if (at.id !== "" && document.querySelectorAll("#" + CSS.escape(at.id)).length === 1) { + parts.unshift("#" + CSS.escape(at.id)) + break + } + let part = at.localName + const parent = at.parentElement + if (parent !== null) { + const same = [...parent.children].filter((child) => child.localName === at.localName) + if (same.length > 1) part += ":nth-of-type(" + (same.indexOf(at) + 1) + ")" + } + parts.unshift(part) + at = parent + } + return parts.join(" > ") + } + const nativeKeys = (element) => { + const tag = element.localName + const type = (element.getAttribute("type") ?? "").toLowerCase() + if (tag === "button") return ["Enter", " "] + if (tag === "input" && ["button", "submit", "reset", "image"].includes(type)) return ["Enter", " "] + if (tag === "input" && ["checkbox", "radio"].includes(type)) return [" "] + if (tag === "a" && element.hasAttribute("href")) return ["Enter"] + if (tag === "summary") return ["Enter", " "] + return [] + } + const customRoles = ["button", "link", "checkbox", "switch", "radio", "tab", "menuitem", "menuitemcheckbox", "menuitemradio", "option"] + const describe = (element) => { + const tag = element.localName + const native = nativeKeys(element) + const role = element.getAttribute("role") ?? "" + const custom = native.length === 0 && customRoles.includes(role) + return { + id: idOf(element), + tag: element.localName, + selector: selector(element), + keys: native.length > 0 ? native : custom ? (role === "link" ? ["Enter"] : ["Enter", " "]) : [], + native: native.length > 0, + external: tag === "a" && element.hasAttribute("href") && (() => { + try { + return new URL(element.href, location.href).origin !== location.origin + } catch { + return false + } + })(), + canvas: element.localName === "canvas" + } + } + const focused = () => { + const active = document.activeElement + return active === null || active === document.body || active === document.documentElement ? null : active + } + const controlSelector = [ + "button", "a[href]", "input:not([type=hidden])", "select", "textarea", "summary", + ...customRoles.map((role) => '[role="' + role + '"]'), + '[role="slider"]', '[role="spinbutton"]', '[role="combobox"]', '[role="textbox"]' + ].join(", ") + // A custom control (a switch, a toggle) may act on keydown with no click: a change of its state attributes is a press too. + const stateOf = (element) => element === null ? "" : ["aria-checked", "aria-pressed", "aria-expanded", "aria-selected"].map((name) => element.getAttribute(name) ?? "").join("|") + let armed = null + window.addEventListener("click", (event) => { + if (armed === null) return + armed.clicks.push(event.target) + if (armed.stop) { + event.stopImmediatePropagation() + event.preventDefault() + } + }, true) + globalThis.__ritmoKeyboardWalk = { + element: (id) => element(id), + focus: (id) => { + const found = element(id) + if (found !== null) found.focus() + return found !== null && document.activeElement === found + }, + state: () => { + const menu = openMenu() + const active = focused() + return { + active: active === null ? null : describe(active), + menu: menu === null ? null : describe(menu), + inMenu: menu !== null && active !== null && menu.contains(active), + url: location.href + } + }, + controls: (scope) => { + const root = scope === null ? document.body : element(scope) + if (root === null) return [] + return [...root.querySelectorAll(controlSelector)] + .filter((control) => !control.disabled && control.closest("[inert]") === null && visible(control)) + .map(describe) + }, + groupStops: (control, stops) => { + const target = element(control) + if (target === null) return [] + const inside = (group) => stops.filter((stop) => { + const found = element(stop) + return found !== null && group.contains(found) + }) + for (let group = target.parentElement; group !== null && group !== document.body && group !== document.documentElement; group = group.parentElement) { + const found = inside(group) + if (found.length > 0) return found + } + return [] + }, + arm: (stop) => { + const target = document.activeElement + const press = { stop, clicks: [], target, before: stateOf(target), keydown: null, keyup: null } + armed = press + const down = (event) => { + press.keydown = event.defaultPrevented + window.removeEventListener("keydown", down) + } + const up = (event) => { + press.keyup = event.defaultPrevented + window.removeEventListener("keyup", up) + } + window.addEventListener("keydown", down) + window.addEventListener("keyup", up) + }, + result: () => { + const press = armed + armed = null + if (press === null) return { pressed: false, keydownPrevented: null, keyupPrevented: null } + const target = press.target + const clicked = target !== null && press.clicks.some((clicked) => clicked === target || (clicked instanceof Node && target.contains(clicked))) + return { + pressed: clicked || (target !== null && stateOf(target) !== press.before), + keydownPrevented: press.keydown, + keyupPrevented: press.keyup + } + } + } +})()` diff --git a/packages/devtools/src/internal/keyboardWalk.ts b/packages/devtools/src/internal/keyboardWalk.ts new file mode 100644 index 00000000..a30ad035 --- /dev/null +++ b/packages/devtools/src/internal/keyboardWalk.ts @@ -0,0 +1,639 @@ +/** + * `ritmo-devtools keyboard`: plays a game's page by keyboard in Chromium and + * checks what a keyboard player relies on, on each screen of a route. + * + * Six checks, each decided per screen as passed, failed, or not checked + * (with the reason), never passed by default: + * + * - `focus-outside-menu`: a menu is open and focus is outside it; + * - `tab-leaves-menu`: Tab moves focus out of the open menu; + * - `unnamed-control`: a control Tab reaches has no accessible name; + * - `key-not-pressed`: Enter or Space on the focused control did not press + * it (the click is stopped, so this changes nothing); + * - `focus-dropped`: pressing a control dropped focus to `` (the + * control is pressed for real, after a reload of the screen); + * - `unreachable-control`: a visible control neither Tab nor the arrows of + * its group reach. + * + * A menu is a `dialog:modal`, a shown `aria-modal="true"` element (the + * `checkVisibility` test `Keyboard.actions` uses), or a shown dialog + * (``, `role="dialog"`, `role="alertdialog"`). Accessible names + * come from Chromium's own accessibility tree. + * + * @internal + */ +import type * as PlaywrightTypes from "playwright" + +import * as Result from "@typeonce/ritmo/Result" + +import { pageScript } from "./keyboardPage.ts" + +/** A control a route names: by accessible name, and by role when given. */ +export interface ControlName { + readonly name: string + readonly role?: string +} + +/** One thing a route does to reach a screen. */ +export type Step = + | { readonly press: string } + | { readonly click: { readonly role: string; readonly name: string } } + | { readonly wait: number } + +/** One screen of the walk: where it starts, how to reach it, and what not to press. */ +export interface Screen { + readonly name: string + /** Appended to the URL: `/`, `?map=8`, `#settings`. */ + readonly path: string + readonly steps: ReadonlyArray + /** `true` presses nothing on this screen (no `focus-dropped`); a list skips those controls. */ + readonly noPress: true | ReadonlyArray +} + +export interface Route { + readonly screens: ReadonlyArray +} + +/** The route of a game that writes none: the start page, as one screen. */ +export const startRoute: Route = { screens: [{ name: "start", path: "", steps: [], noPress: [] }] } + +const isRecord = (value: unknown): value is Record => typeof value === "object" && value !== null && !Array.isArray(value) + +const onlyKeys = (value: Record, keys: ReadonlyArray, at: string): string | undefined => { + const extra = Object.keys(value).find((key) => !keys.includes(key)) + return extra === undefined ? undefined : `${at}.${extra} is not a field (expected ${keys.join(", ")})` +} + +const nonEmpty = (value: unknown): value is string => typeof value === "string" && value.trim() !== "" + +const parseControlName = (value: unknown, at: string): Result.Result => { + if (!isRecord(value)) return Result.failure(`${at} must be an object { "name": string, "role"?: string }`) + const extra = onlyKeys(value, ["name", "role"], at) + if (extra !== undefined) return Result.failure(extra) + if (!nonEmpty(value["name"])) return Result.failure(`${at}.name must be a non-empty string: the control's accessible name`) + if (value["role"] !== undefined && !nonEmpty(value["role"])) return Result.failure(`${at}.role must be a non-empty string when given: an ARIA role such as "button"`) + return Result.success(value["role"] === undefined ? { name: value["name"] } : { name: value["name"], role: value["role"] }) +} + +const parseStep = (value: unknown, at: string): Result.Result => { + if (!isRecord(value) || Object.keys(value).length !== 1) { + return Result.failure(`${at} must be one of { "press": "Escape" }, { "click": { "role": "button", "name": "Play" } }, { "wait": 500 }`) + } + if ("press" in value) { + return nonEmpty(value["press"]) ? Result.success({ press: value["press"] }) : Result.failure(`${at}.press must be a key name, as Playwright's keyboard.press takes it ("Enter", "Escape", "a")`) + } + if ("wait" in value) { + const wait = value["wait"] + return typeof wait === "number" && Number.isInteger(wait) && wait >= 0 && wait <= 60_000 + ? Result.success({ wait }) + : Result.failure(`${at}.wait must be a whole number of milliseconds from 0 to 60000`) + } + if ("click" in value) { + const click = value["click"] + if (!isRecord(click)) return Result.failure(`${at}.click must be an object { "role": string, "name": string }`) + const extra = onlyKeys(click, ["role", "name"], `${at}.click`) + if (extra !== undefined) return Result.failure(extra) + if (!nonEmpty(click["role"])) return Result.failure(`${at}.click.role must be a non-empty string: an ARIA role such as "button"`) + if (!nonEmpty(click["name"])) return Result.failure(`${at}.click.name must be a non-empty string: the control's accessible name`) + return Result.success({ click: { role: click["role"], name: click["name"] } }) + } + return Result.failure(`${at} must be one of { "press": ... }, { "click": ... }, { "wait": ... }; ${Object.keys(value)[0]} is not a step`) +} + +const parseScreen = (value: unknown, at: string): Result.Result => { + if (!isRecord(value)) return Result.failure(`${at} must be an object { "name", "path"?, "steps"?, "noPress"? }`) + const extra = onlyKeys(value, ["name", "path", "steps", "noPress"], at) + if (extra !== undefined) return Result.failure(extra) + if (!nonEmpty(value["name"])) return Result.failure(`${at}.name must be a non-empty string`) + const path = value["path"] ?? "" + if (typeof path !== "string") return Result.failure(`${at}.path must be a string appended to the URL ("/", "?map=8")`) + const rawSteps = value["steps"] ?? [] + if (!Array.isArray(rawSteps)) return Result.failure(`${at}.steps must be an array`) + const steps: Array = [] + for (const [index, raw] of rawSteps.entries()) { + const step = parseStep(raw, `${at}.steps[${index}]`) + if (!step.ok) return step + steps.push(step.value) + } + const rawNoPress = value["noPress"] ?? [] + if (rawNoPress === true) return Result.success({ name: value["name"], path, steps, noPress: true }) + if (!Array.isArray(rawNoPress)) return Result.failure(`${at}.noPress must be true (press nothing on this screen) or an array of { "name", "role"? }`) + const noPress: Array = [] + for (const [index, raw] of rawNoPress.entries()) { + const control = parseControlName(raw, `${at}.noPress[${index}]`) + if (!control.ok) return control + noPress.push(control.value) + } + return Result.success({ name: value["name"], path, steps, noPress }) +} + +/** Validates a route file's JSON; the error names the field that is wrong. */ +export const parseRoute = (value: unknown): Result.Result => { + if (!isRecord(value)) return Result.failure(`the route must be an object { "screens": [...] }`) + const extra = onlyKeys(value, ["screens"], "route") + if (extra !== undefined) return Result.failure(extra) + const raw = value["screens"] + if (!Array.isArray(raw) || raw.length === 0) return Result.failure(`route.screens must be a non-empty array`) + const screens: Array = [] + for (const [index, entry] of raw.entries()) { + const screen = parseScreen(entry, `route.screens[${index}]`) + if (!screen.ok) return screen + if (screens.some((other) => other.name === screen.value.name)) return Result.failure(`route.screens[${index}].name "${screen.value.name}" is already the name of another screen`) + screens.push(screen.value) + } + return Result.success({ screens }) +} + +/** The six checks. */ +export type CheckId = "focus-outside-menu" | "tab-leaves-menu" | "unnamed-control" | "key-not-pressed" | "focus-dropped" | "unreachable-control" + +export const checks: ReadonlyArray = ["focus-outside-menu", "tab-leaves-menu", "unnamed-control", "key-not-pressed", "focus-dropped", "unreachable-control"] + +/** A control as the report names it: its role and name from the accessibility tree, and a CSS selector that finds it. */ +export interface Control { + readonly role: string + readonly name: string + readonly selector: string +} + +/** One failure: which check, on which screen, which control, what the walk saw, and what to change. */ +export interface Failure { + readonly check: CheckId | "route-step" | "page-error" + readonly screen: string + readonly control?: Control + readonly saw: string + readonly fix: string +} + +/** A control a check could not decide, and why. */ +export interface Undecided { + readonly control?: Control + readonly reason: string +} + +/** One check on one screen. `passed` counts only what was decided; `undecided` lists the rest. */ +export interface Outcome { + readonly check: CheckId + readonly screen: string + readonly status: "passed" | "failed" | "not-checked" + /** How many controls (or menus) the check decided. */ + readonly decided: number + readonly undecided: ReadonlyArray +} + +export interface Report { + readonly ok: boolean + readonly url: string + readonly screens: ReadonlyArray + readonly failures: ReadonlyArray + readonly outcomes: ReadonlyArray +} + +export const fixes: Record = { + "focus-outside-menu": "move focus into the menu when it opens: showModal() on a does it, an aria-modal element must focus its first control itself (ui-and-render.md step 8)", + "tab-leaves-menu": "keep Tab inside the open menu: open it with showModal() on a , or make the page behind an aria-modal element inert (ui-and-render.md step 8)", + "unnamed-control": "give it a name: visible text, or aria-label on an icon (ui-and-render.md step 7)", + "key-not-pressed": "leave Enter and Space on a focused control to the page: take game keys with Keyboard.actions, not a page key listener that calls preventDefault() (lint ritmo/use-keyboard-for-game-keys)", + "focus-dropped": "update the control in place instead of rewriting its region (ui-and-render.md step 7); when the press closes a menu into play, focus the canvas (ui-and-render.md step 8, Keyboard.actions)", + "unreachable-control": "let the keyboard reach it: remove tabIndex = -1 (Keyboard.actions leaves Enter and Space on a focused control to it and keeps every other key with the game), or make it part of a group whose one Tab stop reaches it with the arrows", + "route-step": "fix the route so this step can run, or the page so it shows what the step names; the screen's checks did not run", + "page-error": "fix the error the page threw; the checks it interrupted did not run" +} + +/** What the walk needs from outside: the page's URL, the route, and how long to let a screen settle. */ +export interface Options { + readonly url: string + readonly route: Route + /** Milliseconds after a page load before the route's steps run (default 1500). */ + readonly settle?: number +} + +interface Described { + readonly id: number + readonly tag: string + readonly selector: string + readonly keys: ReadonlyArray + readonly native: boolean + /** A link to another site: pressing it for real would leave the game, so it is not pressed. */ + readonly external: boolean + readonly canvas: boolean +} + +interface PageState { + readonly active: Described | null + readonly menu: Described | null + readonly inMenu: boolean + readonly url: string +} + +interface PressResult { + readonly pressed: boolean + readonly keydownPrevented: boolean | null + readonly keyupPrevented: boolean | null +} + +const keyName = (key: string): string => key === " " ? "Space" : key + +/** Joins a screen's path to the base URL, keeping the base's own path. */ +const screenUrl = (base: string, path: string): string => { + if (path === "") return base + if (path.startsWith("?") || path.startsWith("#")) return base.replace(/[?#].*$/, "") + path + return new URL(path, base).href +} + +const describeControl = (control: Control): string => + `${control.role === "" ? "element" : control.role} ${control.name === "" ? "(no name)" : JSON.stringify(control.name)} at ${control.selector}` + +/** Runs the walk in an open Chromium; the caller launches and closes it. */ +export const walk = async (browser: PlaywrightTypes.Browser, options: Options): Promise => { + const settle = options.settle ?? 1500 + const failures: Array = [] + const outcomes: Array = [] + for (const screen of options.route.screens) { + const result = await walkScreen(browser, options.url, screen, settle) + failures.push(...result.failures) + outcomes.push(...result.outcomes) + } + return { ok: failures.length === 0, url: options.url, screens: options.route.screens.map((screen) => screen.name), failures, outcomes } +} + +interface Opened { + readonly page: PlaywrightTypes.Page + readonly errors: Array + readonly state: () => Promise + readonly control: (described: Described) => Promise + readonly close: () => Promise +} + +const open = async (browser: PlaywrightTypes.Browser): Promise => { + const page = await browser.newPage({ viewport: { width: 1280, height: 800 } }) + await page.addInitScript(pageScript) + const errors: Array = [] + page.on("pageerror", (error) => errors.push(error.message)) + const cdp = await page.context().newCDPSession(page) + const state = () => page.evaluate(() => (Reflect.get(globalThis, "__ritmoKeyboardWalk") as { state: () => PageState }).state()) + const control = async (described: Described): Promise => { + try { + const evaluated = await cdp.send("Runtime.evaluate", { expression: `__ritmoKeyboardWalk.element(${described.id})`, objectGroup: "ritmo-keyboard" }) + const objectId = evaluated.result.objectId + if (objectId === undefined) return { role: "", name: "", selector: described.selector } + const tree = await cdp.send("Accessibility.getPartialAXTree", { objectId, fetchRelatives: false }) + const node = tree.nodes[0] + const role = node?.role?.value + const name = node?.name?.value + return { role: typeof role === "string" ? role : "", name: typeof name === "string" ? name.trim() : "", selector: described.selector } + } catch { + return { role: "", name: "", selector: described.selector } + } + } + return { page, errors, state, control, close: () => page.close() } +} + +/** Opens the screen: loads its URL, lets it settle, and runs its steps. A failed step is returned as its message. */ +const reach = async (opened: Opened, url: string, screen: Screen, settle: number): Promise => { + const { page } = opened + try { + await page.goto(screenUrl(url, screen.path), { waitUntil: "load" }) + } catch (error) { + return `the page did not load: ${error instanceof Error ? error.message : String(error)}` + } + await page.waitForTimeout(settle) + for (const [index, step] of screen.steps.entries()) { + const at = `steps[${index}]` + try { + if ("press" in step) await page.keyboard.press(step.press) + else if ("wait" in step) await page.waitForTimeout(step.wait) + else { + const target = await find(opened, step.click) + if (target === undefined) return `${at}: no visible ${step.click.role} named ${JSON.stringify(step.click.name)} to click (names are the ones this report prints)` + await page.locator(target.selector).first().click({ timeout: 5000 }) + } + } catch (error) { + return `${at} failed: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}` + } + await page.waitForTimeout(300) + } + return undefined +} + +/** + * The first visible element with this role and accessible name, by the names + * this report prints (Chromium's accessibility tree), so a name copied from a + * report finds its control. Waits up to five seconds for it to show. + */ +const find = async (opened: Opened, wanted: { readonly role: string; readonly name: string }): Promise => { + for (let tries = 0; tries < 10; tries++) { + const candidates = await call(opened.page, "controls", null) as ReadonlyArray + for (const candidate of candidates) { + const control = await opened.control(candidate) + if (control.role === wanted.role && control.name === wanted.name) return candidate + } + await opened.page.waitForTimeout(500) + } + return undefined +} + +const call = (page: PlaywrightTypes.Page, name: string, argument: A): Promise => + page.evaluate( + ({ name, argument }) => (Reflect.get(globalThis, "__ritmoKeyboardWalk") as Record unknown>)[name]!(argument), + { name, argument } + ) + +const press = async (opened: Opened, key: string, stop: boolean, wait: number): Promise => { + await call(opened.page, "arm", stop) + await opened.page.keyboard.press(key) + await opened.page.waitForTimeout(wait) + return await call(opened.page, "result", undefined) as PressResult +} + +const notChecked = (check: CheckId, screen: string, reason: string): Outcome => ({ check, screen, status: "not-checked", decided: 0, undecided: [{ reason }] }) + +const matches = (control: Control, names: ReadonlyArray): boolean => + names.some((entry) => entry.name === control.name && (entry.role === undefined || entry.role === control.role)) + +interface ScreenResult { + readonly failures: ReadonlyArray + readonly outcomes: ReadonlyArray +} + +const walkScreen = async (browser: PlaywrightTypes.Browser, url: string, screen: Screen, settle: number): Promise => { + const failures: Array = [] + const outcomes: Array = [] + const fail = (check: Failure["check"], saw: string, control?: Control): void => { + failures.push(control === undefined ? { check, screen: screen.name, saw, fix: fixes[check] } : { check, screen: screen.name, control, saw, fix: fixes[check] }) + } + const skipAll = (reason: string): ScreenResult => ({ failures, outcomes: checks.map((check) => notChecked(check, screen.name, reason)) }) + + const opened = await open(browser) + try { + const reached = await reach(opened, url, screen, settle) + if (reached !== undefined) { + fail("route-step", reached) + return skipAll(`the route did not reach this screen (${reached})`) + } + if (opened.errors.length > 0) { + fail("page-error", `the page threw while the screen opened: ${opened.errors[0]}`) + return skipAll("the page threw while the screen opened") + } + + // Pass 1: the Tab walk, with Enter and Space on each stop (the click stopped). + const start = await opened.state() + const menu = start.menu + const stops: Array = [] + const escapes: Array = [] + const presses: Array<{ readonly stop: Described; readonly key: string; readonly result: PressResult }> = [] + const visit = async (at: PageState): Promise => { + const active = at.active! + stops.push(active) + if (menu !== null && at.menu?.id === menu.id && !at.inMenu) escapes.push(active) + for (const key of active.keys) { + const result = await press(opened, key, true, 80) + presses.push({ stop: active, key, result }) + // The game may move focus on a key it took: walk on from where focus is now. + const after = await opened.state() + if (after.active?.id !== active.id) break + } + } + if (start.active !== null) await visit(start) + let atBody = 0 + for (let tabs = 0; tabs < 120; tabs++) { + await opened.page.keyboard.press("Tab") + await opened.page.waitForTimeout(40) + const at = await opened.state() + if (at.active === null) { + if (++atBody >= 2) break + continue + } + atBody = 0 + if (stops.some((stop) => stop.id === at.active!.id)) break + await visit(at) + } + const pageErrors = opened.errors.length + if (pageErrors > 0) { + fail("page-error", `the page threw during the Tab walk: ${opened.errors[0]}`) + return skipAll("the page threw during the Tab walk") + } + + // focus-outside-menu and tab-leaves-menu. + if (menu === null) { + outcomes.push(notChecked("focus-outside-menu", screen.name, "no menu is open on this screen")) + outcomes.push(notChecked("tab-leaves-menu", screen.name, "no menu is open on this screen")) + } else { + const menuControl = await opened.control(menu) + const where = start.active === null ? "" : describeControl(await opened.control(start.active)) + if (!start.inMenu) fail("focus-outside-menu", `this menu is open and focus is on ${where}`, menuControl) + outcomes.push({ check: "focus-outside-menu", screen: screen.name, status: start.inMenu ? "passed" : "failed", decided: 1, undecided: [] }) + const inside = stops.length - escapes.length + if (escapes.length > 0) { + fail("tab-leaves-menu", `this menu is open and Tab reached ${describeControl(await opened.control(escapes[0]!))} outside it${escapes.length > 1 ? ` (and ${escapes.length - 1} more)` : ""}`, menuControl) + outcomes.push({ check: "tab-leaves-menu", screen: screen.name, status: "failed", decided: 1, undecided: [] }) + } else if (inside === 0) { + outcomes.push(notChecked("tab-leaves-menu", screen.name, "Tab reached nothing inside the open menu")) + } else { + outcomes.push({ check: "tab-leaves-menu", screen: screen.name, status: "passed", decided: 1, undecided: [] }) + } + } + + // unnamed-control. + const named = stops.filter((stop) => !stop.canvas) + const controls = new Map() + for (const stop of stops) controls.set(stop.id, await opened.control(stop)) + if (named.length === 0) outcomes.push(notChecked("unnamed-control", screen.name, "Tab reached no control")) + else { + const unnamed = named.filter((stop) => controls.get(stop.id)!.name === "") + for (const stop of unnamed) fail("unnamed-control", "Tab reaches it and it has no accessible name", controls.get(stop.id)) + outcomes.push({ check: "unnamed-control", screen: screen.name, status: unnamed.length > 0 ? "failed" : "passed", decided: named.length, undecided: [] }) + } + + // key-not-pressed. + { + const undecided: Array = [] + const failedIds = new Set() + let decided = 0 + const byStop = new Map>() + for (const entry of presses) byStop.set(entry.stop.id, [...byStop.get(entry.stop.id) ?? [], entry]) + for (const [id, entries] of byStop) { + const stop = entries[0]!.stop + const control = controls.get(id)! + if (!stop.native) { + if (entries.some((entry) => entry.result.pressed)) decided++ + else undecided.push({ control, reason: "a custom control (not a native button, link, checkbox, or summary) showed no click and no change of aria-checked, aria-pressed, aria-expanded, or aria-selected, which may be right for it" }) + continue + } + decided++ + for (const entry of entries) { + if (entry.result.pressed) continue + const prevented = entry.result.keydownPrevented === true ? "a key listener called preventDefault() on its keydown" : entry.result.keyupPrevented === true ? "a key listener called preventDefault() on its keyup" : "no click followed" + fail("key-not-pressed", `${keyName(entry.key)} with it focused did not press it: ${prevented}`, control) + failedIds.add(id) + } + } + const pressable = stops.filter((stop) => stop.keys.length > 0) + outcomes.push(decided === 0 + ? { check: "key-not-pressed", screen: screen.name, status: "not-checked", decided: 0, undecided: undecided.length > 0 ? undecided : [{ reason: pressable.length === 0 ? "Tab reached no control that Enter or Space presses" : "no press could be judged" }] } + : { check: "key-not-pressed", screen: screen.name, status: failedIds.size > 0 ? "failed" : "passed", decided, undecided }) + + // unreachable-control: what Tab missed, unless the arrows of its group reach it. + const visible = await call(opened.page, "controls", menu?.id ?? null) as ReadonlyArray + const reachedIds = new Set(stops.map((stop) => stop.id)) + const missed = visible.filter((control) => !reachedIds.has(control.id)) + const probed = new Map>() + const unreachable: Array = [] + for (const control of missed) { + const from = await opened.page.evaluate( + ({ control, stops }) => (Reflect.get(globalThis, "__ritmoKeyboardWalk") as { groupStops: (control: number, stops: ReadonlyArray) => ReadonlyArray }).groupStops(control, stops), + { control: control.id, stops: [...reachedIds] } + ) + let found = false + for (const stop of from.slice(0, 2)) { + let reachedFrom = probed.get(stop) + if (reachedFrom === undefined) { + reachedFrom = await probe(opened, stop, missed.length + 1) + probed.set(stop, reachedFrom) + } + if (reachedFrom.has(control.id)) { + found = true + break + } + } + if (!found) unreachable.push(control) + } + for (const control of unreachable) { + const named = await opened.control(control) + fail("unreachable-control", `it is visible${menu === null ? "" : " in the open menu"}, and neither Tab nor the arrow keys of its group reach it`, named) + } + outcomes.push(visible.length === 0 + ? notChecked("unreachable-control", screen.name, menu === null ? "no visible control on this screen" : "no visible control in the open menu") + : { check: "unreachable-control", screen: screen.name, status: unreachable.length > 0 ? "failed" : "passed", decided: visible.length, undecided: [] }) + if (opened.errors.length > pageErrors) fail("page-error", `the page threw during the arrow-key probe: ${opened.errors[pageErrors]}`) + + // Pass 2, focus-dropped: press each control for real, on a fresh copy of the screen. + if (screen.noPress === true) { + outcomes.push(notChecked("focus-dropped", screen.name, "the route marks this screen not to be pressed (noPress: true)")) + } else { + const skip = screen.noPress + const results = { decided: 0, undecided: [] as Array, failed: 0 } + const candidates = stops.filter((stop) => stop.native && stop.keys.length > 0) + for (const stop of candidates) { + const control = controls.get(stop.id)! + if (matches(control, skip)) { + results.undecided.push({ control, reason: "the route marks it not to be pressed" }) + continue + } + if (stop.external) { + results.undecided.push({ control, reason: "a link to another site is not pressed for real" }) + continue + } + if (failedIds.has(stop.id)) { + results.undecided.push({ control, reason: "Enter or Space does not press it (key-not-pressed)" }) + continue + } + const outcome = await pressForReal(browser, url, screen, settle, stop) + if (outcome._tag === "Undecided") results.undecided.push({ control, reason: outcome.reason }) + else if (outcome._tag === "PageError") { + fail("page-error", `the page threw when ${keyName(outcome.key)} pressed it: ${outcome.message}`, control) + results.undecided.push({ control, reason: "the page threw when it was pressed" }) + } else { + results.decided++ + if (outcome._tag === "Dropped") { + results.failed++ + fail("focus-dropped", `${keyName(outcome.key)} pressed it and focus fell to `, control) + } + } + } + outcomes.push(results.decided === 0 + ? { check: "focus-dropped", screen: screen.name, status: "not-checked", decided: 0, undecided: results.undecided.length > 0 ? results.undecided : [{ reason: "Tab reached no control that Enter or Space presses" }] } + : { check: "focus-dropped", screen: screen.name, status: results.failed > 0 ? "failed" : "passed", decided: results.decided, undecided: results.undecided }) + } + } + return { failures, outcomes: checks.map((check) => outcomes.find((outcome) => outcome.check === check)!) } + } finally { + await opened.close() + } +} + +/** Every element the arrow keys reach from `stop`, focused by script after the walk's last key. */ +const probe = async (opened: Opened, stop: number, most: number): Promise> => { + const reached = new Set() + for (const keys of [["ArrowRight", "ArrowLeft"], ["ArrowDown", "ArrowUp"]] as const) { + for (const key of keys) { + const focused = await call(opened.page, "focus", stop) + if (focused !== true) return reached + for (let step = 0; step < most; step++) { + await opened.page.keyboard.press(key) + await opened.page.waitForTimeout(30) + const at = await opened.state() + if (at.active === null || reached.has(at.active.id)) break + reached.add(at.active.id) + } + } + } + return reached +} + +type Pressed = + | { readonly _tag: "Kept"; readonly key: string } + | { readonly _tag: "Dropped"; readonly key: string } + | { readonly _tag: "PageError"; readonly key: string; readonly message: string } + | { readonly _tag: "Undecided"; readonly reason: string } + +/** Reloads the screen, tabs to the control again (by its selector), and presses it with the click let through. */ +const pressForReal = async (browser: PlaywrightTypes.Browser, url: string, screen: Screen, settle: number, stop: Described): Promise => { + const opened = await open(browser) + try { + const reached = await reach(opened, url, screen, settle) + if (reached !== undefined) return { _tag: "Undecided", reason: `the route did not reach the screen again (${reached})` } + let at = await opened.state() + for (let tabs = 0; at.active?.selector !== stop.selector && tabs < 120; tabs++) { + await opened.page.keyboard.press("Tab") + await opened.page.waitForTimeout(40) + at = await opened.state() + } + if (at.active?.selector !== stop.selector) return { _tag: "Undecided", reason: "Tab did not reach it again after a reload" } + const key = stop.keys[0]! + const before = opened.errors.length + const popups: Array = [] + const onPopup = (popup: PlaywrightTypes.Page): void => { + popups.push(popup) + } + opened.page.on("popup", onPopup) + const result = await press(opened, key, false, 700) + opened.page.off("popup", onPopup) + await Promise.all(popups.map((popup) => popup.close().catch(() => undefined))) + if (popups.length > 0) return { _tag: "Undecided", reason: "the press opened another page" } + if (opened.errors.length > before) return { _tag: "PageError", key, message: opened.errors[before]! } + const after = await opened.state() + if (after.url.replace(/#.*$/, "") !== at.url.replace(/#.*$/, "")) return { _tag: "Undecided", reason: "the press left the page" } + if (!result.pressed) return { _tag: "Undecided", reason: `${keyName(key)} did not press it after a reload` } + return after.active === null ? { _tag: "Dropped", key } : { _tag: "Kept", key } + } catch (error) { + return { _tag: "Undecided", reason: `the press failed: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}` } + } finally { + await opened.close() + } +} + +/** The report as text: one line per failure, then what passed and what was not checked, per screen. */ +export const format = (report: Report): string => { + const lines: Array = [] + for (const failure of report.failures) { + lines.push(`FAIL ${failure.check} [${failure.screen}]${failure.control === undefined ? "" : ` ${describeControl(failure.control)}`}: ${failure.saw}. Fix: ${failure.fix}.`) + } + if (lines.length > 0) lines.push("") + for (const screen of report.screens) { + const outcomes = report.outcomes.filter((outcome) => outcome.screen === screen) + lines.push(`[${screen}]`) + for (const outcome of outcomes) { + const count = outcome.decided > 0 ? ` (${outcome.decided} decided)` : "" + lines.push(` ${outcome.status === "passed" ? "pass" : outcome.status === "failed" ? "FAIL" : "not checked"} ${outcome.check}${count}`) + for (const entry of outcome.undecided) lines.push(` not checked${entry.control === undefined ? "" : ` ${describeControl(entry.control)}`}: ${entry.reason}`) + } + } + const failed = report.outcomes.filter((outcome) => outcome.status === "failed").length + const passed = report.outcomes.filter((outcome) => outcome.status === "passed").length + const skipped = report.outcomes.filter((outcome) => outcome.status === "not-checked").length + const other = report.failures.filter((failure) => failure.check === "route-step" || failure.check === "page-error").length + lines.push("") + lines.push(`keyboard walk of ${report.url}: ${report.failures.length} failure${report.failures.length === 1 ? "" : "s"}${other > 0 ? ` (${other} route or page error${other === 1 ? "" : "s"})` : ""}; checks ${failed} failed, ${passed} passed, ${skipped} not checked on ${report.screens.length} screen${report.screens.length === 1 ? "" : "s"}`) + return lines.join("\n") +} diff --git a/packages/devtools/test/KeyboardWalk.test.ts b/packages/devtools/test/KeyboardWalk.test.ts new file mode 100644 index 00000000..dcaa4492 --- /dev/null +++ b/packages/devtools/test/KeyboardWalk.test.ts @@ -0,0 +1,232 @@ +import { execFile } from "node:child_process" +import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs" +import { createServer, type Server } from "node:http" +import { tmpdir } from "node:os" +import { join } from "node:path" +import { fileURLToPath } from "node:url" +import { afterAll, beforeAll, describe, expect, it } from "vitest" + +import type * as KeyboardWalkModule from "../src/internal/keyboardWalk.ts" + +// The walk is internal to the CLI (the package exports no `internal/*`): load its source to call it with a short settle time. +const KeyboardWalk = await import(new URL("../src/internal/keyboardWalk.ts", import.meta.url).href) as typeof KeyboardWalkModule + +const cli = fileURLToPath(new URL("../src/cli.ts", import.meta.url)) +const fixtures = fileURLToPath(new URL("./fixtures/keyboard/", import.meta.url)) + +const run = (args: ReadonlyArray, cwd: string) => + new Promise<{ readonly status: number | null; readonly stdout: string; readonly stderr: string }>((done) => { + execFile(process.execPath, [cli, "keyboard", ...args], { cwd }, (error, stdout, stderr) => { + done({ status: error === null ? 0 : typeof error.code === "number" ? error.code : null, stdout, stderr }) + }) + }) + +describe("keyboard route", () => { + it("fills in a screen's defaults", () => { + expect(KeyboardWalk.parseRoute({ screens: [{ name: "title" }] })).toEqual({ + ok: true, + value: { screens: [{ name: "title", path: "", steps: [], noPress: [] }] } + }) + }) + + it("keeps every kind of step and both kinds of noPress", () => { + const parsed = KeyboardWalk.parseRoute({ + screens: [ + { name: "play", path: "?map=8", steps: [{ press: "Escape" }, { click: { role: "button", name: "Play" } }, { wait: 500 }], noPress: [{ name: "Start over", role: "button" }] }, + { name: "end", noPress: true } + ] + }) + expect(parsed.ok && parsed.value.screens).toEqual([ + { name: "play", path: "?map=8", steps: [{ press: "Escape" }, { click: { role: "button", name: "Play" } }, { wait: 500 }], noPress: [{ name: "Start over", role: "button" }] }, + { name: "end", path: "", steps: [], noPress: true } + ]) + }) + + it("names the field that is wrong", () => { + const error = (value: unknown) => { + const parsed = KeyboardWalk.parseRoute(value) + return parsed.ok ? undefined : parsed.error + } + expect(error([])).toBe("the route must be an object { \"screens\": [...] }") + expect(error({ screens: [] })).toBe("route.screens must be a non-empty array") + expect(error({ screens: [{ name: "a" }], extra: 1 })).toBe("route.extra is not a field (expected screens)") + expect(error({ screens: [{ name: "" }] })).toBe("route.screens[0].name must be a non-empty string") + expect(error({ screens: [{ name: "a" }, { name: "a" }] })).toBe("route.screens[1].name \"a\" is already the name of another screen") + expect(error({ screens: [{ name: "a", url: "/" }] })).toBe("route.screens[0].url is not a field (expected name, path, steps, noPress)") + expect(error({ screens: [{ name: "a", steps: [{ click: { role: "button" } }] }] })).toBe("route.screens[0].steps[0].click.name must be a non-empty string: the control's accessible name") + expect(error({ screens: [{ name: "a", steps: [{ wait: 1.5 }] }] })).toBe("route.screens[0].steps[0].wait must be a whole number of milliseconds from 0 to 60000") + expect(error({ screens: [{ name: "a", steps: [{ press: "a", wait: 1 }] }] })).toMatch(/^route\.screens\[0\]\.steps\[0\] must be one of/) + expect(error({ screens: [{ name: "a", steps: [{ type: "abc" }] }] })).toMatch(/type is not a step$/) + expect(error({ screens: [{ name: "a", noPress: [{ role: "button" }] }] })).toBe("route.screens[0].noPress[0].name must be a non-empty string: the control's accessible name") + expect(error({ screens: [{ name: "a", noPress: false }] })).toBe("route.screens[0].noPress must be true (press nothing on this screen) or an array of { \"name\", \"role\"? }") + }) +}) + +describe("ritmo-devtools keyboard arguments", () => { + it("refuses a bad route or URL with exit code 2", async () => { + const dir = mkdtempSync(join(tmpdir(), "ritmo-keyboard-")) + const route = join(dir, "route.json") + writeFileSync(route, JSON.stringify({ screens: [{ name: "a", steps: [{ wait: -1 }] }] })) + expect(await run(["--route", route], fixtures)).toMatchObject({ status: 2, stdout: "", stderr: `${route} is not a keyboard route: route.screens[0].steps[0].wait must be a whole number of milliseconds from 0 to 60000\n` }) + expect(await run(["--url", "localhost:5173"], fixtures)).toMatchObject({ status: 2, stderr: "--url must be an http(s) URL of the game's page, such as http://localhost:5173/; got localhost:5173\n" }) + expect((await run(["--route"], fixtures)).status).toBe(2) + }, 60_000) +}) + +// The browsers are downloaded only where browser runs are checked (the CI job "Determinism across engines"). +const skipped = await (async () => { + try { + const playwright = await import("playwright") + return existsSync(playwright.chromium.executablePath()) ? undefined : "chromium is not downloaded (npx playwright install chromium)" + } catch { + return "playwright is not installed" + } +})() +if (skipped !== undefined) console.warn(`keyboard walk tests skipped: ${skipped}`) + +const types: Record = { ".html": "text/html" } + +describe.skipIf(skipped !== undefined)("ritmo-devtools keyboard", () => { + let server: Server + let base = "" + let browser: Awaited> + + beforeAll(async () => { + server = createServer((request, response) => { + const path = new URL(request.url ?? "/", "http://localhost").pathname + const file = join(fixtures, path === "/" ? "index.html" : path) + if (!file.startsWith(fixtures) || !existsSync(file)) { + response.statusCode = 404 + response.end() + return + } + response.setHeader("content-type", types[file.slice(file.lastIndexOf("."))] ?? "text/plain") + response.end(readFileSync(file)) + }) + await new Promise((done) => server.listen(0, "127.0.0.1", done)) + const address = server.address() + base = `http://127.0.0.1:${typeof address === "object" && address !== null ? address.port : 0}/` + browser = await (await import("playwright")).chromium.launch() + }, 60_000) + + afterAll(async () => { + await browser?.close() + await new Promise((done) => server?.close(done)) + }) + + const walk = (screens: ReadonlyArray & { readonly name: string }>) => + KeyboardWalk.walk(browser, { url: base, route: { screens: screens.map((screen) => ({ path: "", steps: [], noPress: [], ...screen })) }, settle: 100 }) + const statuses = (report: KeyboardWalkModule.Report, screen: string) => + Object.fromEntries(report.outcomes.filter((outcome) => outcome.screen === screen).map((outcome) => [outcome.check, outcome.status])) + + it("passes every check on a page built for the keyboard, and decides each one it can", async () => { + const report = await walk([{ name: "play" }, { name: "paused", path: "#paused" }]) + expect(report.failures).toEqual([]) + expect(report.ok).toBe(true) + expect(statuses(report, "play")).toEqual({ + "focus-outside-menu": "not-checked", + "tab-leaves-menu": "not-checked", + "unnamed-control": "passed", + "key-not-pressed": "passed", + "focus-dropped": "passed", + "unreachable-control": "passed" + }) + expect(statuses(report, "paused")).toEqual({ + "focus-outside-menu": "passed", + "tab-leaves-menu": "passed", + "unnamed-control": "passed", + "key-not-pressed": "passed", + "focus-dropped": "passed", + "unreachable-control": "passed" + }) + // The roving toolbar's other buttons are reached by its arrows, not by Tab. + expect(report.outcomes.find((outcome) => outcome.screen === "play" && outcome.check === "unreachable-control")?.decided).toBe(5) + }, 120_000) + + it("fails each check on the page that breaks it, naming the control and the fix", async () => { + const report = await walk(["focus-outside-menu", "tab-leaves-menu", "unnamed-control", "key-not-pressed", "focus-dropped", "unreachable-control"] + .map((name) => ({ name, path: `${name}.html` }))) + expect(report.ok).toBe(false) + const failed = report.failures.map((failure) => [failure.screen, failure.check, failure.control?.role, failure.control?.name, failure.control?.selector]) + expect(failed).toEqual([ + ["focus-outside-menu", "focus-outside-menu", "dialog", "Title", "body > div"], + ["tab-leaves-menu", "tab-leaves-menu", "dialog", "Paused", "body > div"], + ["unnamed-control", "unnamed-control", "button", "", "body > button:nth-of-type(1)"], + ["key-not-pressed", "key-not-pressed", "button", "Restart", "#restart"], + ["key-not-pressed", "key-not-pressed", "button", "Restart", "#restart"], + ["focus-dropped", "focus-dropped", "button", "Add (0)", "#add"], + ["unreachable-control", "unreachable-control", "button", "Brake", "#hud > button"] + ]) + // Each page fails only its own check. + for (const check of KeyboardWalk.checks) { + const others = report.outcomes.filter((outcome) => outcome.screen === check && outcome.check !== check) + expect(others.filter((outcome) => outcome.status === "failed")).toEqual([]) + expect(statuses(report, check)[check]).toBe("failed") + } + expect(report.failures.find((failure) => failure.check === "key-not-pressed")).toMatchObject({ + saw: "Enter with it focused did not press it: a key listener called preventDefault() on its keydown", + fix: KeyboardWalk.fixes["key-not-pressed"] + }) + expect(report.failures.find((failure) => failure.check === "tab-leaves-menu")?.saw).toBe("this menu is open and Tab reached button \"Menu\" at body > button outside it") + expect(report.failures.find((failure) => failure.check === "focus-dropped")?.saw).toBe("Enter pressed it and focus fell to ") + // A control Enter does not press is not pressed for real. + expect(report.outcomes.find((outcome) => outcome.screen === "key-not-pressed" && outcome.check === "focus-dropped")).toMatchObject({ + status: "not-checked", + undecided: [{ control: { role: "button", name: "Restart", selector: "#restart" }, reason: "Enter or Space does not press it (key-not-pressed)" }] + }) + }, 180_000) + + it("reports a page error and a failed route step as failures, and the screen's checks as not checked", async () => { + const report = await walk([ + { name: "broken", path: "page-error.html" }, + { name: "lost", steps: [{ click: { role: "button", name: "Settings" } }] } + ]) + expect(report.failures.map((failure) => [failure.screen, failure.check, failure.saw])).toEqual([ + ["broken", "page-error", "the page threw while the screen opened: boot failed"], + ["lost", "route-step", "steps[0]: no visible button named \"Settings\" to click (names are the ones this report prints)"] + ]) + expect(report.outcomes.every((outcome) => outcome.status === "not-checked")).toBe(true) + expect(report.outcomes).toHaveLength(12) + }, 120_000) + + it("does not press what the route marks", async () => { + const report = await walk([{ name: "some", noPress: [{ name: "Menu", role: "button" }] }, { name: "none", noPress: true }]) + expect(report.outcomes.find((outcome) => outcome.screen === "some" && outcome.check === "focus-dropped")).toMatchObject({ + status: "passed", + decided: 2, + undecided: [{ control: { role: "button", name: "Menu" }, reason: "the route marks it not to be pressed" }] + }) + expect(report.outcomes.find((outcome) => outcome.screen === "none" && outcome.check === "focus-dropped")).toMatchObject({ + status: "not-checked", + undecided: [{ reason: "the route marks this screen not to be pressed (noPress: true)" }] + }) + }, 120_000) + + it("serves the working directory with Vite, prints the report, and exits with 0 when nothing fails", async () => { + const result = await run([], fixtures) + expect(result.stderr).toBe("") + expect(result.status).toBe(0) + expect(result.stdout).toMatch(/^\[start\]\n {2}not checked focus-outside-menu\n {4}not checked: no menu is open on this screen\n/) + expect(result.stdout).toMatch(/\n {2}pass unreachable-control \(5 decided\)\n\nkeyboard walk of http:\/\/127\.0\.0\.1:\d+\/: 0 failures; checks 0 failed, 4 passed, 2 not checked on 1 screen\n$/) + }, 120_000) + + it("prints one line per failure and JSON with --json, and exits with 1", async () => { + const dir = mkdtempSync(join(tmpdir(), "ritmo-keyboard-")) + const route = join(dir, "route.json") + writeFileSync(route, JSON.stringify({ screens: [{ name: "hud", path: "unreachable-control.html", noPress: true }] })) + const text = await run(["--route", route], fixtures) + expect(text.status).toBe(1) + expect(text.stdout.split("\n")[0]).toBe(`FAIL unreachable-control [hud] button "Brake" at #hud > button: it is visible, and neither Tab nor the arrow keys of its group reach it. Fix: ${KeyboardWalk.fixes["unreachable-control"]}.`) + const json = await run(["--json", `--route=${route}`], fixtures) + expect(json.status).toBe(1) + const report = JSON.parse(json.stdout) as KeyboardWalkModule.Report + expect(report.ok).toBe(false) + expect(report.failures).toEqual([{ + check: "unreachable-control", + screen: "hud", + control: { role: "button", name: "Brake", selector: "#hud > button" }, + saw: "it is visible, and neither Tab nor the arrow keys of its group reach it", + fix: KeyboardWalk.fixes["unreachable-control"] + }]) + }, 120_000) +}) diff --git a/packages/devtools/test/fixtures/keyboard/focus-dropped.html b/packages/devtools/test/fixtures/keyboard/focus-dropped.html new file mode 100644 index 00000000..6375e4f9 --- /dev/null +++ b/packages/devtools/test/fixtures/keyboard/focus-dropped.html @@ -0,0 +1,15 @@ + + +a press rewrites the region that holds the control +
+ diff --git a/packages/devtools/test/fixtures/keyboard/focus-outside-menu.html b/packages/devtools/test/fixtures/keyboard/focus-outside-menu.html new file mode 100644 index 00000000..23be8a56 --- /dev/null +++ b/packages/devtools/test/fixtures/keyboard/focus-outside-menu.html @@ -0,0 +1,6 @@ + + +a menu opens and focus stays outside +
+ +
diff --git a/packages/devtools/test/fixtures/keyboard/index.html b/packages/devtools/test/fixtures/keyboard/index.html new file mode 100644 index 00000000..4b68b593 --- /dev/null +++ b/packages/devtools/test/fixtures/keyboard/index.html @@ -0,0 +1,41 @@ + + +passes every check + + + + + + + +
Rules +
+ diff --git a/packages/devtools/test/fixtures/keyboard/key-not-pressed.html b/packages/devtools/test/fixtures/keyboard/key-not-pressed.html new file mode 100644 index 00000000..5b64b065 --- /dev/null +++ b/packages/devtools/test/fixtures/keyboard/key-not-pressed.html @@ -0,0 +1,9 @@ + + +a page key listener takes Enter and Space + + diff --git a/packages/devtools/test/fixtures/keyboard/page-error.html b/packages/devtools/test/fixtures/keyboard/page-error.html new file mode 100644 index 00000000..5fbeb945 --- /dev/null +++ b/packages/devtools/test/fixtures/keyboard/page-error.html @@ -0,0 +1,5 @@ + + +the page throws + + diff --git a/packages/devtools/test/fixtures/keyboard/tab-leaves-menu.html b/packages/devtools/test/fixtures/keyboard/tab-leaves-menu.html new file mode 100644 index 00000000..f6a938dd --- /dev/null +++ b/packages/devtools/test/fixtures/keyboard/tab-leaves-menu.html @@ -0,0 +1,8 @@ + + +Tab leaves an aria-modal menu + +
+ +
+ diff --git a/packages/devtools/test/fixtures/keyboard/unnamed-control.html b/packages/devtools/test/fixtures/keyboard/unnamed-control.html new file mode 100644 index 00000000..4cb90026 --- /dev/null +++ b/packages/devtools/test/fixtures/keyboard/unnamed-control.html @@ -0,0 +1,5 @@ + + +an icon button with no name + + diff --git a/packages/devtools/test/fixtures/keyboard/unreachable-control.html b/packages/devtools/test/fixtures/keyboard/unreachable-control.html new file mode 100644 index 00000000..08be66e6 --- /dev/null +++ b/packages/devtools/test/fixtures/keyboard/unreachable-control.html @@ -0,0 +1,5 @@ + + +a button the keyboard cannot reach + +
From 4b3a3489cb7a07f59f6106c140930b4ea1b1ce52 Mon Sep 17 00:00:00 2001 From: SandroMaglione Date: Tue, 17 Nov 2026 06:48:13 +1300 Subject: [PATCH 2/2] Keyboard walk: a screen with nothing checked fails; names checked on arrow-reached controls - A screen on which no check could be decided is a failure (nothing-checked), so a route that misses the game's controls never exits with 0. - unnamed-control covers every control the keyboard reaches, by Tab or by the arrows of its group; names are read before the arrow keys are pressed. - The focus-dropped fix covers a control that hides itself, and no longer cites a playbook step that does not say it. Co-Authored-By: Claude Fable 5.2 --- .changeset/devtools-keyboard-walk.md | 2 +- packages/devtools/README.md | 10 +++-- .../devtools/src/internal/keyboardWalk.ts | 43 ++++++++++++------- packages/devtools/test/KeyboardWalk.test.ts | 15 +++++++ .../test/fixtures/keyboard/no-controls.html | 5 +++ .../fixtures/keyboard/unnamed-control.html | 17 ++++++++ 6 files changed, 71 insertions(+), 21 deletions(-) create mode 100644 packages/devtools/test/fixtures/keyboard/no-controls.html diff --git a/.changeset/devtools-keyboard-walk.md b/.changeset/devtools-keyboard-walk.md index 4af6fe18..4bf8df6a 100644 --- a/.changeset/devtools-keyboard-walk.md +++ b/.changeset/devtools-keyboard-walk.md @@ -2,4 +2,4 @@ "@typeonce/ritmo-devtools": minor --- -`ritmo-devtools keyboard [--url ] [--route ] [--json]` plays the game's page by keyboard in Chromium and fails on what breaks keyboard play: a menu open with focus outside it, Tab leaving an open menu, a control with no accessible name, Enter or Space not pressing the focused control, a press that drops focus to ``, and a visible control the keyboard cannot reach. Each failure names the check, the screen, the control (role, name, selector), what was seen, and the fix; a check it cannot decide is printed as not checked, never as passed. Without `--url` it serves the working directory with the game's own Vite config. A route file lists the screens to visit and how to reach them; without one, the start page is the only screen. It presses controls for real to check focus, so a route marks what must not be pressed. It uses the optional `playwright` and `vite` peers `verify` already uses, at the same versions. +`ritmo-devtools keyboard [--url ] [--route ] [--json]` plays the game's page by keyboard in Chromium and fails on what breaks keyboard play: a menu open with focus outside it, Tab leaving an open menu, a control with no accessible name, Enter or Space not pressing the focused control, a press that drops focus to ``, and a visible control the keyboard cannot reach. Each failure names the check, the screen, the control (role, name, selector), what was seen, and the fix; a check it cannot decide is printed as not checked, never as passed, and a screen on which nothing could be checked fails. Without `--url` it serves the working directory with the game's own Vite config. A route file lists the screens to visit and how to reach them; without one, the start page is the only screen. It presses controls for real to check focus, so a route marks what must not be pressed. It uses the optional `playwright` and `vite` peers `verify` already uses, at the same versions. diff --git a/packages/devtools/README.md b/packages/devtools/README.md index 28315ea3..c155029e 100644 --- a/packages/devtools/README.md +++ b/packages/devtools/README.md @@ -555,7 +555,7 @@ Each screen gets six checks: | --- | --- | | `focus-outside-menu` | a menu is open and focus is outside it | | `tab-leaves-menu` | Tab moves focus out of the open menu | -| `unnamed-control` | a control Tab reaches has no accessible name | +| `unnamed-control` | a control the keyboard reaches (by Tab, or by the arrow keys of its group) has no accessible name | | `key-not-pressed` | Enter or Space on the focused control does not press it | | `focus-dropped` | pressing a control drops focus to `` | | `unreachable-control` | a visible control is reached neither by Tab nor by the arrow keys of its group (a roving group with one Tab stop passes) | @@ -593,15 +593,17 @@ Without `--route` the start page is one screen. A route is a JSON file: - `noPress` is `true` (press nothing on that screen) or a list of controls by name and optional role. - A step that cannot run, or an error the page throws, is a failure, and - that screen's checks are not checked. + that screen's checks are not checked. A screen on which no check could be + decided is a failure too (`nothing-checked`): the route did not reach the + game's controls, or the page has none the walk can see. - Without `--url` it serves the working directory with the game's own Vite config; `--url` walks a page already served. It needs `playwright` and its Chromium (`npm install --save-dev playwright vite` and `npx playwright install chromium`); a missing one is printed with its install command. -- Exit codes: 0 nothing failed, 1 a check failed, a route step failed, or the - page threw, 2 usage error (arguments, a route that is not valid, a missing +- Exit codes: 0 nothing failed, 1 a check failed, a route step failed, the + page threw, or a screen had nothing to check, 2 usage error (arguments, a route that is not valid, a missing tool, a dev server that did not start). `--json` prints `{ ok, url, screens, failures: [{ check, screen, control?, saw, fix }], outcomes: [{ check, screen, status, decided, undecided }] }`. diff --git a/packages/devtools/src/internal/keyboardWalk.ts b/packages/devtools/src/internal/keyboardWalk.ts index a30ad035..2776130f 100644 --- a/packages/devtools/src/internal/keyboardWalk.ts +++ b/packages/devtools/src/internal/keyboardWalk.ts @@ -7,7 +7,8 @@ * * - `focus-outside-menu`: a menu is open and focus is outside it; * - `tab-leaves-menu`: Tab moves focus out of the open menu; - * - `unnamed-control`: a control Tab reaches has no accessible name; + * - `unnamed-control`: a control the keyboard reaches (by Tab, or by the + * arrows of its group) has no accessible name; * - `key-not-pressed`: Enter or Space on the focused control did not press * it (the click is stopped, so this changes nothing); * - `focus-dropped`: pressing a control dropped focus to `` (the @@ -15,6 +16,9 @@ * - `unreachable-control`: a visible control neither Tab nor the arrows of * its group reach. * + * A screen on which no check could be decided is a failure too + * (`nothing-checked`): nothing checked is never an exit code of 0. + * * A menu is a `dialog:modal`, a shown `aria-modal="true"` element (the * `checkVisibility` test `Keyboard.actions` uses), or a shown dialog * (``, `role="dialog"`, `role="alertdialog"`). Accessible names @@ -158,7 +162,7 @@ export interface Control { /** One failure: which check, on which screen, which control, what the walk saw, and what to change. */ export interface Failure { - readonly check: CheckId | "route-step" | "page-error" + readonly check: CheckId | "route-step" | "page-error" | "nothing-checked" readonly screen: string readonly control?: Control readonly saw: string @@ -194,10 +198,11 @@ export const fixes: Record = { "tab-leaves-menu": "keep Tab inside the open menu: open it with showModal() on a , or make the page behind an aria-modal element inert (ui-and-render.md step 8)", "unnamed-control": "give it a name: visible text, or aria-label on an icon (ui-and-render.md step 7)", "key-not-pressed": "leave Enter and Space on a focused control to the page: take game keys with Keyboard.actions, not a page key listener that calls preventDefault() (lint ritmo/use-keyboard-for-game-keys)", - "focus-dropped": "update the control in place instead of rewriting its region (ui-and-render.md step 7); when the press closes a menu into play, focus the canvas (ui-and-render.md step 8, Keyboard.actions)", + "focus-dropped": "update the control in place instead of rewriting its region (ui-and-render.md step 7); when the press hides or removes the control (it closes a menu, dismisses a hint), move focus on, to the canvas when play resumes (Keyboard.actions)", "unreachable-control": "let the keyboard reach it: remove tabIndex = -1 (Keyboard.actions leaves Enter and Space on a focused control to it and keeps every other key with the game), or make it part of a group whose one Tab stop reaches it with the arrows", "route-step": "fix the route so this step can run, or the page so it shows what the step names; the screen's checks did not run", - "page-error": "fix the error the page threw; the checks it interrupted did not run" + "page-error": "fix the error the page threw; the checks it interrupted did not run", + "nothing-checked": "give this screen steps that reach the game's DOM controls, or take it out of the route; controls drawn on the canvas, and elements that are not a + +