Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .changeset/devtools-keyboard-walk.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@
"@typeonce/ritmo-devtools": minor
---

`ritmo-devtools keyboard [--url <url>] [--route <file>] [--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 `<body>`, 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.
`ritmo-devtools keyboard [--url <url>] [--route <file>] [--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 `<body>`, 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 (key presses, clicks, `waitFor` a named control, fixed waits); without one, the start page is the only screen. A loaded screen is walked as soon as it stops changing, and the real presses run on up to four pages at once, with any press that did not keep focus run again alone before it is reported. 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.
19 changes: 14 additions & 5 deletions packages/devtools/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -573,7 +573,9 @@ 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.
in the route. A link to another site is never pressed for real. The presses
run on up to four pages at once; one that did not keep focus is run again
with no other page open, and that second result is the one reported.

Without `--route` the start page is one screen. A route is a JSON file:

Expand All @@ -582,18 +584,25 @@ Without `--route` the start page is one screen. A route is a JSON file:
"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" }] }
{ "name": "end", "path": "?moment=end", "steps": [{ "waitFor": { "role": "button", "name": "Start over" } }], "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.
the accessible name the report prints, `waitFor` the same and waits up to
15 seconds for that control to show, `wait` milliseconds.
- A loaded page has settled when no request is in flight and its menu,
focus, and visible controls have not changed for 400 ms, or after 1.5
seconds at the latest. A screen that shows its controls later than that,
or after a quiet moment (a splash, a fade), needs a `waitFor` step;
prefer it to `wait`, which is paid again for every control pressed.
- `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
- A step that cannot run, an error the page throws, or a page that stops
answering for 20 seconds 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.

Expand Down
5 changes: 4 additions & 1 deletion packages/devtools/src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,7 @@
* @docGroup devtools
*/
import { readFileSync } from "node:fs"
import { availableParallelism } from "node:os"
import { resolve } from "node:path"
import { pathToFileURL } from "node:url"

Expand Down Expand Up @@ -335,7 +336,9 @@ const keyboard = async (args: ReadonlyArray<string>): Promise<number> => {
return 2
}
}
const report = await KeyboardWalk.walk(browser, { url, route })
// Half the cores, four pages at most: each page runs the whole game.
const pages = Math.max(1, Math.min(4, Math.floor(availableParallelism() / 2)))
const report = await KeyboardWalk.walk(browser, { url, route, pages })
console.log(json ? JSON.stringify(report, null, 2) : KeyboardWalk.format(report))
return report.ok ? 0 : 1
} finally {
Expand Down
17 changes: 14 additions & 3 deletions packages/devtools/src/internal/keyboardPage.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@
* It installs `__ritmoKeyboardWalk` with:
*
* - `state()`: the focused element and the open menu, each described;
* - `signature()`: the page's clock and one string naming the open menu, the
* focused element, and every visible control, to tell when a screen has
* stopped changing;
* - `controls(scope)`: the visible, enabled controls inside the menu (or the
* page), described;
* - `groupStops(control, stops)`: the Tab stops in the smallest element that
Expand Down Expand Up @@ -108,6 +111,8 @@ export const pageScript = String.raw`(() => {
...customRoles.map((role) => '[role="' + role + '"]'),
'[role="slider"]', '[role="spinbutton"]', '[role="combobox"]', '[role="textbox"]'
].join(", ")
const visibleControls = (root) => [...root.querySelectorAll(controlSelector)]
.filter((control) => !control.disabled && control.closest("[inert]") === null && visible(control))
// 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
Expand Down Expand Up @@ -139,9 +144,15 @@ export const pageScript = String.raw`(() => {
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)
return visibleControls(root).map(describe)
},
signature: () => {
const menu = openMenu()
const active = focused()
return {
now: performance.now(),
key: [menu, active, ...(document.body === null ? [] : visibleControls(document.body))].map((element) => element === null ? "-" : idOf(element)).join(" ")
}
},
groupStops: (control, stops) => {
const target = element(control)
Expand Down
Loading
Loading