Repository navigation
ritmo-devtools keyboard: walk a game's page by keyboard in Chromium - #234
Merged
Merged
Conversation
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 <body> (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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
Member
Author
|
Review pass (commit 4b3a348), after rerunning the walk on the still-time, tabletop-grand-prix, and landkeep
emberworks passed with no false alarm. 🤖 Generated with Claude Code |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this adds
ritmo-devtools keyboard [--url <url>] [--route <file>] [--json]plays a game's page by keyboard in Chromium and fails on six generic invariants:focus-outside-menutab-leaves-menuunnamed-controlkey-not-pressedfocus-dropped<body>unreachable-controlWhat counts:
dialog:modal, a shownaria-modal="true"element (the samecheckVisibilitytestKeyboard.actionsuses), or a shown dialog (<dialog open>,role="dialog",role="alertdialog").getByRoledidn't find it.Never a false pass:
not checkedwith the reason, never as passed: no menu open, nothing reachable by Tab, a custom control that showed neither a click nor a state change, a link to another site, a control markednoPress.not checked.Side effects:
key-not-pressedstops the click it caused at awindowcapture listener installed before the game's scripts. A custom control (e.g.role="switch") counts as pressed when itsaria-checked,aria-pressed,aria-expandedoraria-selectedchanges.focus-droppedpresses each control for real, on a fresh load of its screen. The README says so, and a route marks what must not be pressed (noPress). Links to another site are never pressed for real, and a popup a press opens is closed and counted as not checked.WeakMap; the game's DOM is never changed.Serving and output:
--urlit serves the working directory with the game's own Vite config.verify's engine uses a bare server and can't serve a game's page.playwrightandvitepeers are the optional onesverifyalready uses; neither range changes (the walk uses only APIs from before 1.40).ui-and-render.mdsteps 7 and 8, or atKeyboard.actionsandritmo/use-keyboard-for-game-keys.--jsoncarries the same facts. Exit codes: 0 nothing failed, 1 any failure, 2 usage, an invalid route, a missing tool, or a dev server that didn't start.Where it lives: the walk is internal to the CLI (
src/internal/keyboardWalk.ts,src/internal/keyboardPage.ts), likescan; there is no new TypeScript API.Docs: the README gets a "Keyboard walk" section. The UI playbook's Check line names the command.
The three games (clones, not the game folders)
Fix texts are trimmed to
…below; obvious "not checked" reasons (no menu, nothing reachable) are left out.still-time (Ritmo 0.19.1), no route
Expected: fails
focus-outside-menuandtab-leaves-menu. It failsfocus-outside-menubut passestab-leaves-menu. On the title, every control outside the menu is hidden: I listed every focusable element, and only the menu's 7 buttons are visible. So Tab has nowhere to go. The expectation was wrong; the walk is right. It also failsfocus-dropped, because Play and Rooms rebuild the menu withreplaceChildrenor close it into play.still-time, with a route into play and pause
{ "screens": [ { "name": "title" }, { "name": "play", "steps": [{ "click": { "role": "button", "name": "PLAY" } }, { "press": "s" }, { "wait": 800 }] }, { "name": "pause", "steps": [{ "click": { "role": "button", "name": "PLAY" } }, { "press": "s" }, { "wait": 800 }, { "press": "Escape" }] } ] }(
sskips the first room's cutscene, which fades the HUD out to opacity 0.)Expected:
key-not-pressedon the in-game menu button. It fails exactly there: on Menu and Restart, Enter and Space are taken by the game's ownwindowkey listener, which callspreventDefault().tabletop-grand-prix (Ritmo 0.23.0)
?server=fakeis the game's in-page stand-in server, which shows the leaderboard panel.lcloses it.{ "screens": [ { "name": "start" }, { "name": "board", "path": "?server=fake" }, { "name": "board-closed", "path": "?server=fake", "steps": [{ "press": "l" }, { "wait": 600 }] } ] }Expected:
unreachable-control. It fails on every leaderboard button, the "L BOARD" opener and the maker's link, all of which the game sets totabIndex = -1. Its other bug, astopSpacelistener that prevents Space on every non-field target, is hidden behind this one: no button can take focus, sokey-not-pressedcan't be judged.landkeep
ui-sdkbranch (f32babb, Ritmo 0.24.0)The screens are the ones its own
scripts/keyboard.tsvisits:{ "screens": [ { "name": "title" }, { "name": "settings", "steps": [{ "press": "Enter" }, { "wait": 1500 }, { "press": "ArrowDown" }, { "press": "Enter" }, { "wait": 700 }] }, { "name": "map-card", "path": "?map=8&seed=7" }, { "name": "choosing", "path": "?map=8&seed=7", "steps": [{ "press": "Escape" }, { "wait": 900 }] }, { "name": "dusk", "path": "?moments&moment=downpour&map=8&hold", "steps": [{ "wait": 2500 }] }, { "name": "end", "path": "?moments&moment=end-fail&map=8", "steps": [{ "wait": 5000 }] } ] }Expected: a pass. It passes 33 checks and fails one, which is real. On the dusk screen, "Got it" on a coach line hides the line by removing a CSS class. The focused button disappears, Chromium drops focus to
<body>, and nothing moves it to the land. landkeep's own script clicks "Got it" with the mouse, so it never sees this. Nothing here is a failure that #232 fixed: the game is on 0.24.0.What landkeep's own script checks that the generic walk does not:
aria-pressed="true"), and that focus lands on the canvas specifically. The walk only checks that focus isn't on<body>;aria-checkedchanges, but doesn't check the value;patchHtmlhelper, and its dev warning about a region rewritten whole. The walk sees page errors, not console warnings.Findings I'd question
Possible false positives:
focus-droppedon Play and Resume. These close the menu into play, and focus falls to<body>. still-time reads keys with its ownwindowlistener, so the player can still play. But Tab then starts from the top of the page, and theKeyboardJSDoc asks for focus on the canvas. I'd keep it as a failure.lkey opens the board, so a keyboard player can reach it without the button. The walk can't know a control has a shortcut.Known false negatives:
tab-leaves-menucan only fail where something focusable is visible outside the menu, so a non-modal menu over a page with nothing else to reach passes. That is still-time's case.focus-droppedpresses each control with its first key only (Enter, or Space for a checkbox).transformor by being off-screen still counts as visible.unreachable-controllooks only inside the open menu when there is one: the page behind a modal is inert by design.Left out
<body>".waitsteps cover a slow screen.Speed: landkeep's six screens took 5½ minutes, because each control pressed for real reloads its screen (32 controls on the dusk screen).
noPresson a screen skips that.Tests and CI
test/KeyboardWalk.test.ts:<dialog>, one per failing check, a page error, a failed route step,noPress, the Vite-served start page, and--json.PlaywrightEngine.test.ts. They are added to the "Browser engine tests" step of the CI job that already installs browsers. They take about 45 s.pnpm run check: 1,999 tests, including the Chromium ones.pnpm pack:check.pnpm --dir website build: there is no website change; I ran it because the CLI is public.dist/cli.js keyboardrun on the passing fixture.🤖 Generated with Claude Code