diff --git a/.changeset/devtools-keyboard-walk.md b/.changeset/devtools-keyboard-walk.md new file mode 100644 index 00000000..4bf8df6a --- /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, 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/.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..c155029e 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,85 @@ 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 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) | + +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. 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, 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 }] }`. + ## 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..2776130f --- /dev/null +++ b/packages/devtools/src/internal/keyboardWalk.ts @@ -0,0 +1,650 @@ +/** + * `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 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 + * 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 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 + * 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" | "nothing-checked" + 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 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", + "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 + 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/no-controls.html b/packages/devtools/test/fixtures/keyboard/no-controls.html new file mode 100644 index 00000000..70a141a2 --- /dev/null +++ b/packages/devtools/test/fixtures/keyboard/no-controls.html @@ -0,0 +1,5 @@ + + +a page whose controls are drawn on the canvas + +
Play
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..abf5001a --- /dev/null +++ b/packages/devtools/test/fixtures/keyboard/unnamed-control.html @@ -0,0 +1,22 @@ + + +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 + +