@typeonce/ritmo-devtools 0.24.0 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +197 -1
  3. package/dist/Fuzz.d.ts +38 -6
  4. package/dist/Fuzz.d.ts.map +1 -1
  5. package/dist/Fuzz.js +37 -11
  6. package/dist/Fuzz.js.map +1 -1
  7. package/dist/Replay.d.ts +1 -1
  8. package/dist/cli.js +171 -3
  9. package/dist/cli.js.map +1 -1
  10. package/dist/internal/dependencyScan.js +1 -1
  11. package/dist/internal/dependencyScan.js.map +1 -1
  12. package/dist/internal/fuzzNetwork.d.ts +15 -2
  13. package/dist/internal/fuzzNetwork.d.ts.map +1 -1
  14. package/dist/internal/fuzzNetwork.js +30 -7
  15. package/dist/internal/fuzzNetwork.js.map +1 -1
  16. package/dist/internal/keyboardPage.d.ts +29 -0
  17. package/dist/internal/keyboardPage.d.ts.map +1 -0
  18. package/dist/internal/keyboardPage.js +199 -0
  19. package/dist/internal/keyboardPage.js.map +1 -0
  20. package/dist/internal/keyboardWalk.d.ts +91 -0
  21. package/dist/internal/keyboardWalk.d.ts.map +1 -0
  22. package/dist/internal/keyboardWalk.js +373 -0
  23. package/dist/internal/keyboardWalk.js.map +1 -0
  24. package/dist/internal/layoutPage.d.ts +35 -0
  25. package/dist/internal/layoutPage.d.ts.map +1 -0
  26. package/dist/internal/layoutPage.js +535 -0
  27. package/dist/internal/layoutPage.js.map +1 -0
  28. package/dist/internal/layoutWalk.d.ts +84 -0
  29. package/dist/internal/layoutWalk.d.ts.map +1 -0
  30. package/dist/internal/layoutWalk.js +252 -0
  31. package/dist/internal/layoutWalk.js.map +1 -0
  32. package/dist/internal/pageOpen.d.ts +86 -0
  33. package/dist/internal/pageOpen.d.ts.map +1 -0
  34. package/dist/internal/pageOpen.js +166 -0
  35. package/dist/internal/pageOpen.js.map +1 -0
  36. package/dist/internal/route.d.ts +94 -0
  37. package/dist/internal/route.d.ts.map +1 -0
  38. package/dist/internal/route.js +230 -0
  39. package/dist/internal/route.js.map +1 -0
  40. package/dist/internal/version.d.ts +1 -1
  41. package/dist/internal/version.js +1 -1
  42. package/package.json +3 -3
  43. package/src/Fuzz.ts +62 -11
  44. package/src/cli.ts +165 -3
  45. package/src/internal/dependencyScan.ts +1 -1
  46. package/src/internal/fuzzNetwork.ts +33 -7
  47. package/src/internal/keyboardPage.ts +198 -0
  48. package/src/internal/keyboardWalk.ts +474 -0
  49. package/src/internal/layoutPage.ts +534 -0
  50. package/src/internal/layoutWalk.ts +365 -0
  51. package/src/internal/pageOpen.ts +225 -0
  52. package/src/internal/route.ts +276 -0
  53. package/src/internal/version.ts +1 -1
@@ -0,0 +1,474 @@
1
+ /**
2
+ * `ritmo-devtools keyboard`: plays a game's page by keyboard in Chromium and
3
+ * checks what a keyboard player relies on, on each screen of a route.
4
+ *
5
+ * Six checks, each decided per screen as passed, failed, or not checked
6
+ * (with the reason), never passed by default:
7
+ *
8
+ * - `focus-outside-menu`: a menu is open and focus is outside it;
9
+ * - `tab-leaves-menu`: Tab moves focus out of the open menu;
10
+ * - `unnamed-control`: a control the keyboard reaches (by Tab, or by the
11
+ * arrows of its group) has no accessible name;
12
+ * - `key-not-pressed`: Enter or Space on the focused control did not press
13
+ * it (the click is stopped, so this changes nothing);
14
+ * - `focus-dropped`: pressing a control dropped focus to `<body>` (the
15
+ * control is pressed for real, after a reload of the screen);
16
+ * - `unreachable-control`: a visible control neither Tab nor the arrows of
17
+ * its group reach.
18
+ *
19
+ * A loaded screen is walked once it has stopped changing: no request in
20
+ * flight, and the same menu, focus, and visible controls for 400 ms, or
21
+ * `settle` at the latest. `focus-dropped` presses on several pages at once
22
+ * (`pages`); a press that did not keep focus is run again with no other page
23
+ * open, and that second result is the one reported, so a failure never comes
24
+ * from a busy machine.
25
+ *
26
+ * A page that stops answering for `stall` milliseconds (its main thread is
27
+ * busy, or its renderer hung) is closed and reported as a `page-error`, so
28
+ * the walk fails instead of waiting for ever.
29
+ *
30
+ * A screen on which no check could be decided is a failure too
31
+ * (`nothing-checked`): nothing checked is never an exit code of 0.
32
+ *
33
+ * A menu is a `dialog:modal`, a shown `aria-modal="true"` element (the
34
+ * `checkVisibility` test `Keyboard.actions` uses), or a shown dialog
35
+ * (`<dialog open>`, `role="dialog"`, `role="alertdialog"`). Accessible names
36
+ * come from Chromium's own accessibility tree.
37
+ *
38
+ * @internal
39
+ */
40
+ import type * as PlaywrightTypes from "playwright"
41
+
42
+ import type { Control, Described, Opened, PageState } from "./pageOpen.ts"
43
+ import { call, open, reach, stalledSaw } from "./pageOpen.ts"
44
+ import type { ControlName, Route, Screen } from "./route.ts"
45
+
46
+ /** The six checks. */
47
+ export type CheckId = "focus-outside-menu" | "tab-leaves-menu" | "unnamed-control" | "key-not-pressed" | "focus-dropped" | "unreachable-control"
48
+
49
+ export const checks: ReadonlyArray<CheckId> = ["focus-outside-menu", "tab-leaves-menu", "unnamed-control", "key-not-pressed", "focus-dropped", "unreachable-control"]
50
+
51
+ /** One failure: which check, on which screen, which control, what the walk saw, and what to change. */
52
+ export interface Failure {
53
+ readonly check: CheckId | "route-step" | "page-error" | "nothing-checked"
54
+ readonly screen: string
55
+ readonly control?: Control
56
+ readonly saw: string
57
+ readonly fix: string
58
+ }
59
+
60
+ /** A control a check could not decide, and why. */
61
+ export interface Undecided {
62
+ readonly control?: Control
63
+ readonly reason: string
64
+ }
65
+
66
+ /** One check on one screen. `passed` counts only what was decided; `undecided` lists the rest. */
67
+ export interface Outcome {
68
+ readonly check: CheckId
69
+ readonly screen: string
70
+ readonly status: "passed" | "failed" | "not-checked"
71
+ /** How many controls (or menus) the check decided. */
72
+ readonly decided: number
73
+ readonly undecided: ReadonlyArray<Undecided>
74
+ }
75
+
76
+ export interface Report {
77
+ readonly ok: boolean
78
+ readonly url: string
79
+ readonly screens: ReadonlyArray<string>
80
+ readonly failures: ReadonlyArray<Failure>
81
+ readonly outcomes: ReadonlyArray<Outcome>
82
+ }
83
+
84
+ export const fixes: Record<Failure["check"], string> = {
85
+ "focus-outside-menu": "move focus into the menu when it opens: showModal() on a <dialog> does it, an aria-modal element must focus its first control itself (ui-and-render.md step 8)",
86
+ "tab-leaves-menu": "keep Tab inside the open menu: open it with showModal() on a <dialog>, or make the page behind an aria-modal element inert (ui-and-render.md step 8)",
87
+ "unnamed-control": "give it a name: visible text, or aria-label on an icon (ui-and-render.md step 7)",
88
+ "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)",
89
+ "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)",
90
+ "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",
91
+ "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",
92
+ "page-error": "fix the error the page threw; the checks it interrupted did not run",
93
+ "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 <button>, a link, a form field, or an ARIA role, are not for this walk"
94
+ }
95
+
96
+ /** What the walk needs from outside: the page's URL, the route, and how long to let a screen settle. */
97
+ export interface Options {
98
+ readonly url: string
99
+ readonly route: Route
100
+ /** The most milliseconds a loaded page gets to stop changing before the route's steps run (default 1500). */
101
+ readonly settle?: number
102
+ /** How many pages press controls at once for `focus-dropped` (default 1). */
103
+ readonly pages?: number
104
+ /** How many milliseconds a page may go without answering before it is closed and reported (default 20000). */
105
+ readonly stall?: number
106
+ }
107
+
108
+ interface PressResult {
109
+ readonly pressed: boolean
110
+ readonly keydownPrevented: boolean | null
111
+ readonly keyupPrevented: boolean | null
112
+ }
113
+
114
+ const keyName = (key: string): string => key === " " ? "Space" : key
115
+
116
+ const describeControl = (control: Control): string =>
117
+ `${control.role === "" ? "element" : control.role} ${control.name === "" ? "(no name)" : JSON.stringify(control.name)} at ${control.selector}`
118
+
119
+ /** Runs the walk in an open Chromium; the caller launches and closes it. */
120
+ export const walk = async (browser: PlaywrightTypes.Browser, options: Options): Promise<Report> => {
121
+ const settle = options.settle ?? 1500
122
+ const failures: Array<Failure> = []
123
+ const outcomes: Array<Outcome> = []
124
+ for (const screen of options.route.screens) {
125
+ const result = await walkScreen(browser, { url: options.url, settle, pages: Math.max(1, options.pages ?? 1), stall: options.stall ?? 20_000 }, screen)
126
+ failures.push(...result.failures)
127
+ outcomes.push(...result.outcomes)
128
+ }
129
+ return { ok: failures.length === 0, url: options.url, screens: options.route.screens.map((screen) => screen.name), failures, outcomes }
130
+ }
131
+
132
+ /** What every page of one walk shares. */
133
+ interface Walk {
134
+ readonly url: string
135
+ readonly settle: number
136
+ readonly pages: number
137
+ readonly stall: number
138
+ }
139
+
140
+ /** Runs `run` on every item, at most `most` at once; the results keep the items' order. */
141
+ const inParallel = async <A, B>(items: ReadonlyArray<A>, most: number, run: (item: A) => Promise<B>): Promise<ReadonlyArray<B>> => {
142
+ const results: Array<B> = []
143
+ let next = 0
144
+ const worker = async (): Promise<void> => {
145
+ while (next < items.length) {
146
+ const index = next++
147
+ results[index] = await run(items[index]!)
148
+ }
149
+ }
150
+ await Promise.all(Array.from({ length: Math.min(most, items.length) }, worker))
151
+ return results
152
+ }
153
+
154
+ const press = async (opened: Opened, key: string, stop: boolean, wait: number): Promise<PressResult> => {
155
+ await call(opened.page, "arm", stop)
156
+ await opened.page.keyboard.press(key)
157
+ await opened.page.waitForTimeout(wait)
158
+ return await call(opened.page, "result", undefined) as PressResult
159
+ }
160
+
161
+ const notChecked = (check: CheckId, screen: string, reason: string): Outcome => ({ check, screen, status: "not-checked", decided: 0, undecided: [{ reason }] })
162
+
163
+ const matches = (control: Control, names: ReadonlyArray<ControlName>): boolean =>
164
+ names.some((entry) => entry.name === control.name && (entry.role === undefined || entry.role === control.role))
165
+
166
+ interface ScreenResult {
167
+ readonly failures: ReadonlyArray<Failure>
168
+ readonly outcomes: ReadonlyArray<Outcome>
169
+ }
170
+
171
+ const walkScreen = async (browser: PlaywrightTypes.Browser, { url, settle, pages, stall }: Walk, screen: Screen): Promise<ScreenResult> => {
172
+ const failures: Array<Failure> = []
173
+ const outcomes: Array<Outcome> = []
174
+ const fail = (check: Failure["check"], saw: string, control?: Control): void => {
175
+ failures.push(control === undefined ? { check, screen: screen.name, saw, fix: fixes[check] } : { check, screen: screen.name, control, saw, fix: fixes[check] })
176
+ }
177
+ const skipAll = (reason: string): ScreenResult => ({ failures, outcomes: checks.map((check) => notChecked(check, screen.name, reason)) })
178
+
179
+ const opened = await open(browser, stall)
180
+ // What was seen before a page stopped answering is dropped with it: the report says one thing about the screen.
181
+ const stalled = (): ScreenResult => {
182
+ failures.length = 0
183
+ fail("page-error", stalledSaw(stall))
184
+ return skipAll("the page stopped answering")
185
+ }
186
+ try {
187
+ const reached = await reach(opened, url, screen, settle)
188
+ if (opened.stalled()) return stalled()
189
+ if (reached !== undefined) {
190
+ fail("route-step", reached)
191
+ return skipAll(`the route did not reach this screen (${reached})`)
192
+ }
193
+ if (opened.errors.length > 0) {
194
+ fail("page-error", `the page threw while the screen opened: ${opened.errors[0]}`)
195
+ return skipAll("the page threw while the screen opened")
196
+ }
197
+
198
+ // Pass 1: the Tab walk, with Enter and Space on each stop (the click stopped).
199
+ const start = await opened.state()
200
+ const menu = start.menu
201
+ const stops: Array<Described> = []
202
+ const escapes: Array<Described> = []
203
+ const presses: Array<{ readonly stop: Described; readonly key: string; readonly result: PressResult }> = []
204
+ const visit = async (at: PageState): Promise<void> => {
205
+ const active = at.active!
206
+ stops.push(active)
207
+ if (menu !== null && at.menu?.id === menu.id && !at.inMenu) escapes.push(active)
208
+ for (const key of active.keys) {
209
+ const result = await press(opened, key, true, 80)
210
+ presses.push({ stop: active, key, result })
211
+ // The game may move focus on a key it took: walk on from where focus is now.
212
+ const after = await opened.state()
213
+ if (after.active?.id !== active.id) break
214
+ }
215
+ }
216
+ if (start.active !== null) await visit(start)
217
+ let atBody = 0
218
+ for (let tabs = 0; tabs < 120; tabs++) {
219
+ await opened.page.keyboard.press("Tab")
220
+ await opened.page.waitForTimeout(40)
221
+ const at = await opened.state()
222
+ if (at.active === null) {
223
+ if (++atBody >= 2) break
224
+ continue
225
+ }
226
+ atBody = 0
227
+ if (stops.some((stop) => stop.id === at.active!.id)) break
228
+ await visit(at)
229
+ }
230
+ const pageErrors = opened.errors.length
231
+ if (pageErrors > 0) {
232
+ fail("page-error", `the page threw during the Tab walk: ${opened.errors[0]}`)
233
+ return skipAll("the page threw during the Tab walk")
234
+ }
235
+
236
+ // focus-outside-menu and tab-leaves-menu.
237
+ if (menu === null) {
238
+ outcomes.push(notChecked("focus-outside-menu", screen.name, "no menu is open on this screen"))
239
+ outcomes.push(notChecked("tab-leaves-menu", screen.name, "no menu is open on this screen"))
240
+ } else {
241
+ const menuControl = await opened.control(menu)
242
+ const where = start.active === null ? "<body>" : describeControl(await opened.control(start.active))
243
+ if (!start.inMenu) fail("focus-outside-menu", `this menu is open and focus is on ${where}`, menuControl)
244
+ outcomes.push({ check: "focus-outside-menu", screen: screen.name, status: start.inMenu ? "passed" : "failed", decided: 1, undecided: [] })
245
+ const inside = stops.length - escapes.length
246
+ if (escapes.length > 0) {
247
+ 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)
248
+ outcomes.push({ check: "tab-leaves-menu", screen: screen.name, status: "failed", decided: 1, undecided: [] })
249
+ } else if (inside === 0) {
250
+ outcomes.push(notChecked("tab-leaves-menu", screen.name, "Tab reached nothing inside the open menu"))
251
+ } else {
252
+ outcomes.push({ check: "tab-leaves-menu", screen: screen.name, status: "passed", decided: 1, undecided: [] })
253
+ }
254
+ }
255
+
256
+ const controls = new Map<number, Control>()
257
+ for (const stop of stops) controls.set(stop.id, await opened.control(stop))
258
+
259
+ // key-not-pressed.
260
+ {
261
+ const undecided: Array<Undecided> = []
262
+ const failedIds = new Set<number>()
263
+ let decided = 0
264
+ const byStop = new Map<number, Array<(typeof presses)[number]>>()
265
+ for (const entry of presses) byStop.set(entry.stop.id, [...byStop.get(entry.stop.id) ?? [], entry])
266
+ for (const [id, entries] of byStop) {
267
+ const stop = entries[0]!.stop
268
+ const control = controls.get(id)!
269
+ if (!stop.native) {
270
+ if (entries.some((entry) => entry.result.pressed)) decided++
271
+ 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" })
272
+ continue
273
+ }
274
+ decided++
275
+ for (const entry of entries) {
276
+ if (entry.result.pressed) continue
277
+ 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"
278
+ fail("key-not-pressed", `${keyName(entry.key)} with it focused did not press it: ${prevented}`, control)
279
+ failedIds.add(id)
280
+ }
281
+ }
282
+ const pressable = stops.filter((stop) => stop.keys.length > 0)
283
+ outcomes.push(decided === 0
284
+ ? { 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" }] }
285
+ : { check: "key-not-pressed", screen: screen.name, status: failedIds.size > 0 ? "failed" : "passed", decided, undecided })
286
+
287
+ // unreachable-control: what Tab missed, unless the arrows of its group reach it.
288
+ const visible = await call(opened.page, "controls", menu?.id ?? null) as ReadonlyArray<Described>
289
+ const reachedIds = new Set(stops.map((stop) => stop.id))
290
+ const missed = visible.filter((control) => !reachedIds.has(control.id))
291
+ // Named before the arrow keys are pressed: a game that takes them may redraw what they name.
292
+ for (const control of missed) controls.set(control.id, await opened.control(control))
293
+ const probed = new Map<number, Set<number>>()
294
+ const unreachable: Array<Described> = []
295
+ for (const control of missed) {
296
+ const from = await opened.page.evaluate(
297
+ ({ control, stops }) => (Reflect.get(globalThis, "__ritmoKeyboardWalk") as { groupStops: (control: number, stops: ReadonlyArray<number>) => ReadonlyArray<number> }).groupStops(control, stops),
298
+ { control: control.id, stops: [...reachedIds] }
299
+ )
300
+ let found = false
301
+ for (const stop of from.slice(0, 2)) {
302
+ let reachedFrom = probed.get(stop)
303
+ if (reachedFrom === undefined) {
304
+ reachedFrom = await probe(opened, stop, missed.length + 1)
305
+ probed.set(stop, reachedFrom)
306
+ }
307
+ if (reachedFrom.has(control.id)) {
308
+ found = true
309
+ break
310
+ }
311
+ }
312
+ if (!found) unreachable.push(control)
313
+ }
314
+ for (const control of unreachable) {
315
+ fail("unreachable-control", `it is visible${menu === null ? "" : " in the open menu"}, and neither Tab nor the arrow keys of its group reach it`, controls.get(control.id))
316
+ }
317
+ outcomes.push(visible.length === 0
318
+ ? notChecked("unreachable-control", screen.name, menu === null ? "no visible control on this screen" : "no visible control in the open menu")
319
+ : { check: "unreachable-control", screen: screen.name, status: unreachable.length > 0 ? "failed" : "passed", decided: visible.length, undecided: [] })
320
+ if (opened.errors.length > pageErrors) fail("page-error", `the page threw during the arrow-key probe: ${opened.errors[pageErrors]}`)
321
+
322
+ // unnamed-control: every control the keyboard reaches, by Tab or by the arrows of its group.
323
+ const reached = [...stops.filter((stop) => !stop.canvas), ...missed.filter((control) => !unreachable.includes(control))]
324
+ if (reached.length === 0) outcomes.push(notChecked("unnamed-control", screen.name, "the keyboard reached no control"))
325
+ else {
326
+ const unnamed = reached.filter((control) => controls.get(control.id)!.name === "")
327
+ for (const control of unnamed) fail("unnamed-control", "the keyboard reaches it and it has no accessible name", controls.get(control.id))
328
+ outcomes.push({ check: "unnamed-control", screen: screen.name, status: unnamed.length > 0 ? "failed" : "passed", decided: reached.length, undecided: [] })
329
+ }
330
+
331
+ // Pass 2, focus-dropped: press each control for real, on a fresh copy of the screen.
332
+ if (screen.noPress === true) {
333
+ outcomes.push(notChecked("focus-dropped", screen.name, "the route marks this screen not to be pressed (noPress: true)"))
334
+ } else {
335
+ const skip = screen.noPress
336
+ const results = { decided: 0, undecided: [] as Array<Undecided>, failed: 0 }
337
+ const candidates = stops.filter((stop) => stop.native && stop.keys.length > 0)
338
+ const skipped = (stop: Described): string | undefined =>
339
+ matches(controls.get(stop.id)!, skip)
340
+ ? "the route marks it not to be pressed"
341
+ : stop.external
342
+ ? "a link to another site is not pressed for real"
343
+ : failedIds.has(stop.id)
344
+ ? "Enter or Space does not press it (key-not-pressed)"
345
+ : undefined
346
+ const pressed = await inParallel(candidates.filter((stop) => skipped(stop) === undefined), pages, (stop) => pressForReal(browser, { url, settle, pages, stall }, screen, stop))
347
+ let at = 0
348
+ for (const stop of candidates) {
349
+ const control = controls.get(stop.id)!
350
+ const reason = skipped(stop)
351
+ if (reason !== undefined) {
352
+ results.undecided.push({ control, reason })
353
+ continue
354
+ }
355
+ let outcome = pressed[at++]!
356
+ // A press that shared the machine with others and did not keep focus is run again alone: only that result is reported.
357
+ if (pages > 1 && outcome._tag !== "Kept") outcome = await pressForReal(browser, { url, settle, pages, stall }, screen, stop)
358
+ if (outcome._tag === "Undecided") results.undecided.push({ control, reason: outcome.reason })
359
+ else if (outcome._tag === "PageError") {
360
+ fail("page-error", outcome.saw, control)
361
+ results.undecided.push({ control, reason: outcome.reason })
362
+ } else {
363
+ results.decided++
364
+ if (outcome._tag === "Dropped") {
365
+ results.failed++
366
+ fail("focus-dropped", `${keyName(outcome.key)} pressed it and focus fell to <body>`, control)
367
+ }
368
+ }
369
+ }
370
+ outcomes.push(results.decided === 0
371
+ ? { 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" }] }
372
+ : { check: "focus-dropped", screen: screen.name, status: results.failed > 0 ? "failed" : "passed", decided: results.decided, undecided: results.undecided })
373
+ }
374
+ }
375
+ // Nothing decided is not a pass: the route missed the game's controls, or the page has none this walk can see.
376
+ if (failures.length === 0 && outcomes.every((outcome) => outcome.status === "not-checked")) {
377
+ fail("nothing-checked", "no check could be decided on this screen: no menu is open, and it shows no control")
378
+ }
379
+ return { failures, outcomes: checks.map((check) => outcomes.find((outcome) => outcome.check === check)!) }
380
+ } catch (error) {
381
+ if (!opened.stalled()) throw error
382
+ return stalled()
383
+ } finally {
384
+ await opened.close()
385
+ }
386
+ }
387
+
388
+ /** Every element the arrow keys reach from `stop`, focused by script after the walk's last key. */
389
+ const probe = async (opened: Opened, stop: number, most: number): Promise<Set<number>> => {
390
+ const reached = new Set<number>()
391
+ for (const keys of [["ArrowRight", "ArrowLeft"], ["ArrowDown", "ArrowUp"]] as const) {
392
+ for (const key of keys) {
393
+ const focused = await call(opened.page, "focus", stop)
394
+ if (focused !== true) return reached
395
+ for (let step = 0; step < most; step++) {
396
+ await opened.page.keyboard.press(key)
397
+ await opened.page.waitForTimeout(30)
398
+ const at = await opened.state()
399
+ if (at.active === null || reached.has(at.active.id)) break
400
+ reached.add(at.active.id)
401
+ }
402
+ }
403
+ }
404
+ return reached
405
+ }
406
+
407
+ type Pressed =
408
+ | { readonly _tag: "Kept"; readonly key: string }
409
+ | { readonly _tag: "Dropped"; readonly key: string }
410
+ | { readonly _tag: "PageError"; readonly saw: string; readonly reason: string }
411
+ | { readonly _tag: "Undecided"; readonly reason: string }
412
+
413
+ /** Reloads the screen, tabs to the control again (by its selector), and presses it with the click let through. */
414
+ const pressForReal = async (browser: PlaywrightTypes.Browser, { url, settle, stall }: Walk, screen: Screen, stop: Described): Promise<Pressed> => {
415
+ const opened = await open(browser, stall)
416
+ try {
417
+ const reached = await reach(opened, url, screen, settle)
418
+ if (opened.stalled()) return { _tag: "PageError", saw: stalledSaw(stall), reason: "the page stopped answering" }
419
+ if (reached !== undefined) return { _tag: "Undecided", reason: `the route did not reach the screen again (${reached})` }
420
+ let at = await opened.state()
421
+ for (let tabs = 0; at.active?.selector !== stop.selector && tabs < 120; tabs++) {
422
+ await opened.page.keyboard.press("Tab")
423
+ await opened.page.waitForTimeout(40)
424
+ at = await opened.state()
425
+ }
426
+ if (at.active?.selector !== stop.selector) return { _tag: "Undecided", reason: "Tab did not reach it again after a reload" }
427
+ const key = stop.keys[0]!
428
+ const before = opened.errors.length
429
+ const popups: Array<PlaywrightTypes.Page> = []
430
+ const onPopup = (popup: PlaywrightTypes.Page): void => {
431
+ popups.push(popup)
432
+ }
433
+ opened.page.on("popup", onPopup)
434
+ const result = await press(opened, key, false, 700)
435
+ opened.page.off("popup", onPopup)
436
+ await Promise.all(popups.map((popup) => popup.close().catch(() => undefined)))
437
+ if (popups.length > 0) return { _tag: "Undecided", reason: "the press opened another page" }
438
+ if (opened.errors.length > before) return { _tag: "PageError", saw: `the page threw when ${keyName(key)} pressed it: ${opened.errors[before]!}`, reason: "the page threw when it was pressed" }
439
+ const after = await opened.state()
440
+ if (after.url.replace(/#.*$/, "") !== at.url.replace(/#.*$/, "")) return { _tag: "Undecided", reason: "the press left the page" }
441
+ if (!result.pressed) return { _tag: "Undecided", reason: `${keyName(key)} did not press it after a reload` }
442
+ return after.active === null ? { _tag: "Dropped", key } : { _tag: "Kept", key }
443
+ } catch (error) {
444
+ if (opened.stalled()) return { _tag: "PageError", saw: stalledSaw(stall), reason: "the page stopped answering" }
445
+ return { _tag: "Undecided", reason: `the press failed: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}` }
446
+ } finally {
447
+ await opened.close()
448
+ }
449
+ }
450
+
451
+ /** The report as text: one line per failure, then what passed and what was not checked, per screen. */
452
+ export const format = (report: Report): string => {
453
+ const lines: Array<string> = []
454
+ for (const failure of report.failures) {
455
+ lines.push(`FAIL ${failure.check} [${failure.screen}]${failure.control === undefined ? "" : ` ${describeControl(failure.control)}`}: ${failure.saw}. Fix: ${failure.fix}.`)
456
+ }
457
+ if (lines.length > 0) lines.push("")
458
+ for (const screen of report.screens) {
459
+ const outcomes = report.outcomes.filter((outcome) => outcome.screen === screen)
460
+ lines.push(`[${screen}]`)
461
+ for (const outcome of outcomes) {
462
+ const count = outcome.decided > 0 ? ` (${outcome.decided} decided)` : ""
463
+ lines.push(` ${outcome.status === "passed" ? "pass" : outcome.status === "failed" ? "FAIL" : "not checked"} ${outcome.check}${count}`)
464
+ for (const entry of outcome.undecided) lines.push(` not checked${entry.control === undefined ? "" : ` ${describeControl(entry.control)}`}: ${entry.reason}`)
465
+ }
466
+ }
467
+ const failed = report.outcomes.filter((outcome) => outcome.status === "failed").length
468
+ const passed = report.outcomes.filter((outcome) => outcome.status === "passed").length
469
+ const skipped = report.outcomes.filter((outcome) => outcome.status === "not-checked").length
470
+ const other = report.failures.filter((failure) => failure.check === "route-step" || failure.check === "page-error" || failure.check === "nothing-checked").length
471
+ lines.push("")
472
+ lines.push(`keyboard walk of ${report.url}: ${report.failures.length} failure${report.failures.length === 1 ? "" : "s"}${other > 0 ? ` (${other} from the route or the page, not from a check)` : ""}; checks ${failed} failed, ${passed} passed, ${skipped} not checked on ${report.screens.length} screen${report.screens.length === 1 ? "" : "s"}`)
473
+ return lines.join("\n")
474
+ }