@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.
- package/CHANGELOG.md +35 -0
- package/README.md +197 -1
- package/dist/Fuzz.d.ts +38 -6
- package/dist/Fuzz.d.ts.map +1 -1
- package/dist/Fuzz.js +37 -11
- package/dist/Fuzz.js.map +1 -1
- package/dist/Replay.d.ts +1 -1
- package/dist/cli.js +171 -3
- package/dist/cli.js.map +1 -1
- package/dist/internal/dependencyScan.js +1 -1
- package/dist/internal/dependencyScan.js.map +1 -1
- package/dist/internal/fuzzNetwork.d.ts +15 -2
- package/dist/internal/fuzzNetwork.d.ts.map +1 -1
- package/dist/internal/fuzzNetwork.js +30 -7
- package/dist/internal/fuzzNetwork.js.map +1 -1
- package/dist/internal/keyboardPage.d.ts +29 -0
- package/dist/internal/keyboardPage.d.ts.map +1 -0
- package/dist/internal/keyboardPage.js +199 -0
- package/dist/internal/keyboardPage.js.map +1 -0
- package/dist/internal/keyboardWalk.d.ts +91 -0
- package/dist/internal/keyboardWalk.d.ts.map +1 -0
- package/dist/internal/keyboardWalk.js +373 -0
- package/dist/internal/keyboardWalk.js.map +1 -0
- package/dist/internal/layoutPage.d.ts +35 -0
- package/dist/internal/layoutPage.d.ts.map +1 -0
- package/dist/internal/layoutPage.js +535 -0
- package/dist/internal/layoutPage.js.map +1 -0
- package/dist/internal/layoutWalk.d.ts +84 -0
- package/dist/internal/layoutWalk.d.ts.map +1 -0
- package/dist/internal/layoutWalk.js +252 -0
- package/dist/internal/layoutWalk.js.map +1 -0
- package/dist/internal/pageOpen.d.ts +86 -0
- package/dist/internal/pageOpen.d.ts.map +1 -0
- package/dist/internal/pageOpen.js +166 -0
- package/dist/internal/pageOpen.js.map +1 -0
- package/dist/internal/route.d.ts +94 -0
- package/dist/internal/route.d.ts.map +1 -0
- package/dist/internal/route.js +230 -0
- package/dist/internal/route.js.map +1 -0
- package/dist/internal/version.d.ts +1 -1
- package/dist/internal/version.js +1 -1
- package/package.json +3 -3
- package/src/Fuzz.ts +62 -11
- package/src/cli.ts +165 -3
- package/src/internal/dependencyScan.ts +1 -1
- package/src/internal/fuzzNetwork.ts +33 -7
- package/src/internal/keyboardPage.ts +198 -0
- package/src/internal/keyboardWalk.ts +474 -0
- package/src/internal/layoutPage.ts +534 -0
- package/src/internal/layoutWalk.ts +365 -0
- package/src/internal/pageOpen.ts +225 -0
- package/src/internal/route.ts +276 -0
- 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
|
+
}
|