@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,365 @@
1
+ /**
2
+ * `ritmo-devtools layout`: opens each screen of a route in Chromium at each
3
+ * of the route's viewports and reports what is broken in the layout the
4
+ * player sees, whatever the game.
5
+ *
6
+ * Errors (they fail the run) are what the browser measures exactly and a
7
+ * game never means:
8
+ *
9
+ * - `overlap`: two things drawn over each other, neither part of the other
10
+ * (text over text, text over a button, a button over a Touch button), with
11
+ * nothing drawn above both;
12
+ * - `cut-text`: text the edge of a box cuts, with nothing to say it is cut;
13
+ * - `off-screen`: part of a text or control past the edge of the screen;
14
+ * - `safe-area`: part of a text or control in the space the device keeps
15
+ * (a notch, the home bar), from the viewport's insets;
16
+ * - `small-target`: the area that takes a tap is under `minTarget` either
17
+ * side (hit tests through the control's centre, so a `::after` that
18
+ * extends it counts);
19
+ * - `layout-shift`: something moved while nothing was pressed (Chromium's
20
+ * own layout-shift entries);
21
+ * - `never-settled`: the layout kept moving, so nothing could be measured.
22
+ *
23
+ * Warnings (reported, never failing) are what a game may mean:
24
+ *
25
+ * - `truncated-text`: text shortened with an ellipsis or a line clamp;
26
+ * - `scroll-edge`: a control half hidden at the edge of a scrolling area, or
27
+ * a scrolling area that runs past the screen;
28
+ * - every finding of the longer-text pass, which loads each screen again
29
+ * with every text about 40% longer: a layout with no room to spare, not a
30
+ * layout broken today.
31
+ *
32
+ * A route's `allow` lists what a game means, by check and selector. The
33
+ * page side is `layoutPage.ts`; reaching a screen is the keyboard walk's.
34
+ *
35
+ * @internal
36
+ */
37
+ import { mkdirSync } from "node:fs"
38
+ import { join } from "node:path"
39
+
40
+ import type * as PlaywrightTypes from "playwright"
41
+
42
+ import { pageScript } from "./layoutPage.ts"
43
+ import type { Opened } from "./pageOpen.ts"
44
+ import { open, reach, stalledSaw } from "./pageOpen.ts"
45
+ import type { Allow, LayoutCheckId, Route, Screen, Viewport } from "./route.ts"
46
+
47
+ /** Every check the audit decides on each screen at each viewport. */
48
+ export type CheckId = LayoutCheckId | "never-settled"
49
+
50
+ export const checks: ReadonlyArray<CheckId> = ["overlap", "cut-text", "off-screen", "safe-area", "small-target", "layout-shift", "never-settled", "truncated-text", "scroll-edge"]
51
+
52
+ /** What a finding is about: the route, the page, or a check. */
53
+ export type FindingCheck = CheckId | "route-step" | "page-error" | "nothing-measured"
54
+
55
+ export type Severity = "error" | "warning"
56
+
57
+ const warnings: ReadonlySet<FindingCheck> = new Set<FindingCheck>(["truncated-text", "scroll-edge"])
58
+
59
+ /** An element as the report names it. */
60
+ export interface Element {
61
+ readonly kind: "text" | "control" | "touch"
62
+ readonly selector: string
63
+ readonly text: string
64
+ }
65
+
66
+ export interface Box {
67
+ readonly l: number
68
+ readonly t: number
69
+ readonly r: number
70
+ readonly b: number
71
+ }
72
+
73
+ /**
74
+ * One finding: the check, how much it matters, where (screen, viewport, and
75
+ * which pass), the element (and the other one of an overlap), what was
76
+ * measured, and what to change.
77
+ */
78
+ export interface Finding {
79
+ readonly check: FindingCheck
80
+ readonly severity: Severity
81
+ readonly screen: string
82
+ readonly viewport: string
83
+ readonly pass: "normal" | "longer-text"
84
+ readonly element?: Element
85
+ readonly other?: Element
86
+ readonly box?: Box
87
+ readonly saw: string
88
+ readonly fix: string
89
+ /** The screenshot that marks it, and its number there, with `screenshots`. */
90
+ readonly screenshot?: { readonly file: string; readonly number: number }
91
+ }
92
+
93
+ /** One check on one screen at one viewport: `warned` has only warnings, `count` its findings. */
94
+ export interface Outcome {
95
+ readonly check: CheckId
96
+ readonly screen: string
97
+ readonly viewport: string
98
+ readonly status: "passed" | "failed" | "warned" | "not-checked"
99
+ readonly count: number
100
+ readonly reason?: string
101
+ }
102
+
103
+ export interface Report {
104
+ readonly ok: boolean
105
+ readonly url: string
106
+ readonly screens: ReadonlyArray<string>
107
+ readonly viewports: ReadonlyArray<string>
108
+ readonly findings: ReadonlyArray<Finding>
109
+ readonly outcomes: ReadonlyArray<Outcome>
110
+ /** Findings the route's `allow` left out. */
111
+ readonly allowed: number
112
+ }
113
+
114
+ export const fixes: Record<FindingCheck, string> = {
115
+ overlap: "give each its own space at this size (anchor them to different edges, let one wrap or shrink); when one is meant to sit over the other, list it in the route's allow",
116
+ "cut-text": "let the text wrap or give its box room at this size; when a cut is meant, end it with text-overflow: ellipsis so the player sees that text is missing",
117
+ "off-screen": "keep it inside the screen at this size: anchor it to the edges, or let the layout wrap or shrink",
118
+ "safe-area": "keep it out of the device's own space: offset its edge by env(safe-area-inset-*)",
119
+ "small-target": "make the area that takes a tap bigger (padding, or a ::after that extends it), or set the route's minTarget when the game's own rule is smaller",
120
+ "layout-shift": "keep its size while its content changes: size it to its widest value (a min-width, font-variant-numeric: tabular-nums for numbers), and animate with transform",
121
+ "never-settled": "keep the layout still while nothing happens: animate with transform, not position or size, and honour prefers-reduced-motion; or wait longer in the route's steps",
122
+ "truncated-text": "check the player can still tell what it says, and show the whole text where there is room; list it in the route's allow when the cut is meant",
123
+ "scroll-edge": "when the player must find what is past the edge, show that the area scrolls; otherwise nothing to change",
124
+ "route-step": "fix the route so this step can run, or the page so it shows what the step names; this screen was not measured",
125
+ "page-error": "fix the error the page threw; the screen was still measured, unless the page stopped answering",
126
+ "nothing-measured": "give this screen steps that reach what the game shows, or take it out of the route; drawing on a canvas is not measured, only text, controls, and Touch buttons"
127
+ }
128
+
129
+ /** What the audit needs from outside. */
130
+ export interface Options {
131
+ readonly url: string
132
+ readonly route: Route
133
+ /** The most milliseconds a loaded page gets to stop changing before the route's steps run (default 1500). */
134
+ readonly settle?: number
135
+ /** How many milliseconds a page may go without answering before it is closed and reported (default 20000). */
136
+ readonly stall?: number
137
+ /** Milliseconds of a still screen watched for layout shifts (default 1500). */
138
+ readonly steadyFor?: number
139
+ /** Longest wait for the layout to hold still, in milliseconds (default 6000). */
140
+ readonly settleLimit?: number
141
+ /** A directory for one screenshot per screen and viewport with findings, each finding boxed and numbered. */
142
+ readonly screenshots?: string
143
+ /** The longer-text pass (default true). */
144
+ readonly longerText?: boolean
145
+ }
146
+
147
+ interface PageFinding {
148
+ readonly check: CheckId
149
+ readonly element?: Element
150
+ readonly other?: Element
151
+ readonly box?: Box
152
+ readonly saw: string
153
+ }
154
+
155
+ interface Audited {
156
+ readonly findings: ReadonlyArray<PageFinding>
157
+ readonly measured: number
158
+ readonly allowed: number
159
+ }
160
+
161
+ const callPage = (page: PlaywrightTypes.Page, name: string, argument?: unknown): Promise<unknown> =>
162
+ page.evaluate(
163
+ ({ name, argument }) => (Reflect.get(globalThis, "__ritmoLayout") as Record<string, (argument: unknown) => unknown>)[name]!(argument),
164
+ { name, argument }
165
+ )
166
+
167
+ const fileName = (text: string): string => text.replace(/[^a-z0-9@._-]+/gi, "-")
168
+
169
+ /** Waits for fonts, then until two layout readings 250 ms apart agree; the elements that still move when they never do. */
170
+ const settleLayout = async (page: PlaywrightTypes.Page, limit: number): Promise<ReadonlyArray<string> | undefined> => {
171
+ await page.evaluate("document.fonts.ready.then(() => true)").catch(() => true)
172
+ let last = await callPage(page, "snapshot") as string
173
+ for (let waited = 0; waited < limit; waited += 250) {
174
+ await page.waitForTimeout(250)
175
+ const next = await callPage(page, "snapshot") as string
176
+ if (next === last) return undefined
177
+ last = next
178
+ }
179
+ const before = JSON.parse(last) as ReadonlyArray<ReadonlyArray<string | number>>
180
+ await page.waitForTimeout(250)
181
+ const after = JSON.parse(await callPage(page, "snapshot") as string) as ReadonlyArray<ReadonlyArray<string | number>>
182
+ const kept = new Map(before.map((entry) => [String(entry[0]), JSON.stringify(entry)]))
183
+ const moving = after.filter((entry) => kept.get(String(entry[0])) !== JSON.stringify(entry)).map((entry) => String(entry[0]))
184
+ return moving.length > 0 ? moving : ["elements that come and go"]
185
+ }
186
+
187
+ const colors: Record<Severity, string> = { error: "#e5195f", warning: "#f5a000" }
188
+
189
+ const keyOf = (finding: PageFinding): string => `${finding.check}|${finding.element?.selector ?? ""}|${finding.other?.selector ?? ""}`
190
+
191
+ const describeElement = (element: Element): string =>
192
+ element.kind === "touch"
193
+ ? `touch button ${JSON.stringify(element.text)} on ${element.selector}`
194
+ : `${element.kind} ${element.text === "" ? "(no text)" : JSON.stringify(element.text)} at ${element.selector}`
195
+
196
+ /** Runs the audit in an open Chromium; the caller launches and closes it. */
197
+ export const walk = async (browser: PlaywrightTypes.Browser, options: Options): Promise<Report> => {
198
+ const findings: Array<Finding> = []
199
+ const outcomes: Array<Outcome> = []
200
+ let allowed = 0
201
+ if (options.screenshots !== undefined) mkdirSync(options.screenshots, { recursive: true })
202
+ for (const screen of options.route.screens) {
203
+ for (const viewport of options.route.viewports) {
204
+ const result = await auditScreen(browser, options, screen, viewport)
205
+ findings.push(...result.findings)
206
+ outcomes.push(...result.outcomes)
207
+ allowed += result.allowed
208
+ }
209
+ }
210
+ return {
211
+ ok: findings.every((finding) => finding.severity === "warning"),
212
+ url: options.url,
213
+ screens: options.route.screens.map((screen) => screen.name),
214
+ viewports: options.route.viewports.map((viewport) => viewport.name),
215
+ findings,
216
+ outcomes,
217
+ allowed
218
+ }
219
+ }
220
+
221
+ interface ScreenResult {
222
+ readonly findings: ReadonlyArray<Finding>
223
+ readonly outcomes: ReadonlyArray<Outcome>
224
+ readonly allowed: number
225
+ }
226
+
227
+ const auditScreen = async (browser: PlaywrightTypes.Browser, options: Options, screen: Screen, viewport: Viewport): Promise<ScreenResult> => {
228
+ const settle = options.settle ?? 1500
229
+ const limit = options.settleLimit ?? 6000
230
+ const stall = options.stall ?? 20_000
231
+ const allow: ReadonlyArray<Allow> = [...options.route.allow, ...screen.allow]
232
+ const findings: Array<Finding> = []
233
+ const at = { screen: screen.name, viewport: viewport.name }
234
+ const walkFinding = (check: FindingCheck, saw: string): Finding => ({ check, severity: "error", ...at, pass: "normal", saw, fix: fixes[check] })
235
+ const notChecked = (reason: string): ScreenResult => ({
236
+ findings,
237
+ outcomes: checks.map((check) => ({ check, ...at, status: "not-checked", count: 0, reason })),
238
+ allowed: 0
239
+ })
240
+ const opening = { width: viewport.width, height: viewport.height, touch: viewport.touch, insets: viewport.insets, reducedMotion: true, scripts: [pageScript] }
241
+
242
+ // The screen as the player sees it.
243
+ let opened: Opened = await open(browser, stall, opening)
244
+ // What was seen before a page stopped answering is dropped with it: the report says one thing about the screen.
245
+ const stalled = (): ScreenResult => {
246
+ findings.length = 0
247
+ findings.push(walkFinding("page-error", stalledSaw(stall)))
248
+ return notChecked("the page stopped answering")
249
+ }
250
+ let base: Audited
251
+ let shifted: Audited
252
+ try {
253
+ const reached = await reach(opened, options.url, screen, settle)
254
+ if (opened.stalled()) return stalled()
255
+ if (reached !== undefined) {
256
+ findings.push(walkFinding("route-step", reached))
257
+ return notChecked(`the route did not reach this screen (${reached})`)
258
+ }
259
+ const moving = await settleLayout(opened.page, limit)
260
+ if (opened.errors.length > 0) findings.push(walkFinding("page-error", `the page threw while the screen opened: ${opened.errors[0]}`))
261
+ if (moving !== undefined) {
262
+ findings.push({ ...walkFinding("never-settled", `the layout kept moving for ${limit / 1000} s: ${moving.slice(0, 4).join(", ")}${moving.length > 4 ? ` and ${moving.length - 4} more` : ""}`) })
263
+ return { ...notChecked("the layout never held still"), outcomes: checks.map((check) => check === "never-settled" ? { check, ...at, status: "failed" as const, count: 1 } : { check, ...at, status: "not-checked" as const, count: 0, reason: "the layout never held still" }) }
264
+ }
265
+ await callPage(opened.page, "steady")
266
+ base = await callPage(opened.page, "audit", { width: viewport.width, height: viewport.height, insets: viewport.insets, minTarget: options.route.minTarget, allow, checks: checks.filter((check) => check !== "layout-shift" && check !== "never-settled") }) as Audited
267
+ await opened.page.waitForTimeout(options.steadyFor ?? 1500)
268
+ shifted = await callPage(opened.page, "shifts", allow) as Audited
269
+ if (base.measured === 0) {
270
+ findings.push(walkFinding("nothing-measured", "the screen showed no text, control, or Touch button to measure"))
271
+ return notChecked("nothing to measure")
272
+ }
273
+ const normal = [...base.findings, ...shifted.findings].map((finding): Finding => ({
274
+ ...finding,
275
+ severity: warnings.has(finding.check) ? "warning" : "error",
276
+ ...at,
277
+ pass: "normal",
278
+ fix: fixes[finding.check]
279
+ }))
280
+ findings.push(...await shoot(opened, options, normal, `${screen.name}@${viewport.name}`))
281
+ } catch (error) {
282
+ if (!opened.stalled()) throw error
283
+ return stalled()
284
+ } finally {
285
+ await opened.close()
286
+ }
287
+
288
+ // The same screen with every text about 40% longer: what has no room to spare.
289
+ let longer: Audited | undefined
290
+ if (options.longerText !== false) {
291
+ opened = await open(browser, stall, opening)
292
+ try {
293
+ const reached = await reach(opened, options.url, screen, settle)
294
+ if (reached === undefined && !opened.stalled()) {
295
+ await callPage(opened.page, "pad")
296
+ const moving = await settleLayout(opened.page, limit)
297
+ if (moving === undefined) {
298
+ longer = await callPage(opened.page, "audit", { width: viewport.width, height: viewport.height, insets: viewport.insets, minTarget: options.route.minTarget, allow, checks: ["overlap", "cut-text", "off-screen", "safe-area"] }) as Audited
299
+ const known = new Set(base.findings.map(keyOf))
300
+ const fresh = longer.findings.filter((finding) => !known.has(keyOf(finding))).map((finding): Finding => ({
301
+ ...finding,
302
+ severity: "warning",
303
+ ...at,
304
+ pass: "longer-text",
305
+ saw: `with every text about 40% longer, ${finding.saw}`,
306
+ fix: `${fixes[finding.check]}; this is a layout with no room to spare (a longer name, a translation), not one broken today`
307
+ }))
308
+ findings.push(...await shoot(opened, options, fresh, `${screen.name}@${viewport.name}-longer-text`))
309
+ }
310
+ }
311
+ } catch (error) {
312
+ // The screen was measured once already: a page that hangs only with longer text is reported, and what was measured is kept.
313
+ if (!opened.stalled()) throw error
314
+ } finally {
315
+ if (opened.stalled()) findings.push({ ...walkFinding("page-error", `with every text about 40% longer, ${stalledSaw(stall)}`), pass: "longer-text" })
316
+ await opened.close()
317
+ }
318
+ }
319
+
320
+ const outcomes = checks.map((check): Outcome => {
321
+ const mine = findings.filter((finding) => finding.check === check && finding.pass === "normal")
322
+ const status = mine.some((finding) => finding.severity === "error") ? "failed" : mine.length > 0 ? "warned" : "passed"
323
+ return { check, ...at, status, count: mine.length }
324
+ })
325
+ return { findings, outcomes, allowed: base.allowed + shifted.allowed + (longer?.allowed ?? 0) }
326
+ }
327
+
328
+ /** With `screenshots`, boxes and numbers each finding on the page and saves it; the findings then name their file and number. */
329
+ const shoot = async (opened: Opened, options: Options, found: ReadonlyArray<Finding>, name: string): Promise<ReadonlyArray<Finding>> => {
330
+ if (options.screenshots === undefined || found.length === 0) return found
331
+ const file = join(options.screenshots, `${fileName(name)}.png`)
332
+ const numbered = found.map((finding, index) => ({ ...finding, screenshot: { file, number: index + 1 } }))
333
+ await callPage(opened.page, "mark", numbered.filter((finding) => finding.box !== undefined).map((finding) => ({ ...finding.box, number: finding.screenshot.number, color: colors[finding.severity] })))
334
+ await opened.page.screenshot({ path: file })
335
+ await callPage(opened.page, "unmark")
336
+ return numbered
337
+ }
338
+
339
+ /** The report as text: one line per finding, then each screen's checks per viewport, then the totals. */
340
+ export const format = (report: Report): string => {
341
+ const lines: Array<string> = []
342
+ for (const finding of report.findings) {
343
+ const where = `[${finding.screen} @ ${finding.viewport}${finding.pass === "longer-text" ? ", longer text" : ""}]`
344
+ const what = finding.element === undefined ? "" : ` ${describeElement(finding.element)}${finding.other === undefined ? "" : `, and ${describeElement(finding.other)}`}`
345
+ const shot = finding.screenshot === undefined ? "" : ` (${finding.screenshot.file} #${finding.screenshot.number})`
346
+ lines.push(`${finding.severity === "error" ? "FAIL" : "warn"} ${finding.check} ${where}${what}: ${finding.saw}.${shot} Fix: ${finding.fix}.`)
347
+ }
348
+ if (lines.length > 0) lines.push("")
349
+ for (const screen of report.screens) {
350
+ lines.push(`[${screen}]`)
351
+ for (const viewport of report.viewports) {
352
+ const mine = report.outcomes.filter((outcome) => outcome.screen === screen && outcome.viewport === viewport)
353
+ const skipped = mine.find((outcome) => outcome.status === "not-checked" && outcome.check !== "never-settled") ?? mine.find((outcome) => outcome.status === "not-checked")
354
+ const said = mine.filter((outcome) => outcome.status === "failed" || outcome.status === "warned").map((outcome) => `${outcome.status === "failed" ? "FAIL" : "warn"} ${outcome.check} (${outcome.count})`)
355
+ const passed = mine.filter((outcome) => outcome.status === "passed").length
356
+ const parts = [...said, ...(passed > 0 ? [`pass ${passed} more`] : [])]
357
+ lines.push(` ${viewport}: ${parts.join(", ")}${skipped?.reason === undefined ? "" : `${parts.length > 0 ? "; " : ""}not checked: ${skipped.reason}`}`)
358
+ }
359
+ }
360
+ const errors = report.findings.filter((finding) => finding.severity === "error").length
361
+ const warned = report.findings.length - errors
362
+ lines.push("")
363
+ lines.push(`layout audit of ${report.url}: ${errors} error${errors === 1 ? "" : "s"}, ${warned} warning${warned === 1 ? "" : "s"} on ${report.screens.length} screen${report.screens.length === 1 ? "" : "s"} at ${report.viewports.length} viewport${report.viewports.length === 1 ? "" : "s"}${report.allowed > 0 ? ` (${report.allowed} left out by the route's allow)` : ""}`)
364
+ return lines.join("\n")
365
+ }
@@ -0,0 +1,225 @@
1
+ /**
2
+ * Opening one screen of a route in Chromium, for `ritmo-devtools keyboard`
3
+ * and `ritmo-devtools layout`: a page at a viewport, the keyboard walk's page
4
+ * script installed (it finds controls by the names a report prints), the
5
+ * route's steps run, and errors the page throws collected.
6
+ *
7
+ * A loaded screen is ready once it has stopped changing: no request in
8
+ * flight, and the same menu, focus, and visible controls for 400 ms, or
9
+ * `settle` at the latest. A page that stops answering for `stall`
10
+ * milliseconds (its main thread is busy, or its renderer hung) is closed, so
11
+ * a walk reports it instead of waiting for ever.
12
+ *
13
+ * @internal
14
+ */
15
+ import type * as PlaywrightTypes from "playwright"
16
+
17
+ import { pageScript } from "./keyboardPage.ts"
18
+ import type { Insets, Screen } from "./route.ts"
19
+ import { screenUrl } from "./route.ts"
20
+
21
+ /** A control as the report names it: its role and name from the accessibility tree, and a CSS selector that finds it. */
22
+ export interface Control {
23
+ readonly role: string
24
+ readonly name: string
25
+ readonly selector: string
26
+ }
27
+
28
+ export interface Described {
29
+ readonly id: number
30
+ readonly tag: string
31
+ readonly selector: string
32
+ readonly keys: ReadonlyArray<string>
33
+ readonly native: boolean
34
+ /** A link to another site: pressing it for real would leave the game, so it is not pressed. */
35
+ readonly external: boolean
36
+ readonly canvas: boolean
37
+ }
38
+
39
+ export interface PageState {
40
+ readonly active: Described | null
41
+ readonly menu: Described | null
42
+ readonly inMenu: boolean
43
+ readonly url: string
44
+ }
45
+
46
+ export interface Opened {
47
+ readonly page: PlaywrightTypes.Page
48
+ readonly errors: Array<string>
49
+ /** Requests in flight, and a count that moves whenever one starts or ends. */
50
+ readonly network: { inFlight: number; activity: number }
51
+ /** True once the page stopped answering and was closed for it. */
52
+ readonly stalled: () => boolean
53
+ readonly state: () => Promise<PageState>
54
+ readonly control: (described: Described) => Promise<Control>
55
+ readonly close: () => Promise<void>
56
+ }
57
+
58
+ /** How to open a page: its size, a touch screen or not, what the device keeps for itself, and more scripts to install. */
59
+ export interface OpenOptions {
60
+ readonly width: number
61
+ readonly height: number
62
+ readonly touch: boolean
63
+ readonly insets?: Insets
64
+ readonly reducedMotion?: boolean
65
+ readonly scripts?: ReadonlyArray<string>
66
+ }
67
+
68
+ const desktop: OpenOptions = { width: 1280, height: 800, touch: false }
69
+
70
+ /** What a walk says of a page that stopped answering. */
71
+ export const stalledSaw = (stall: number): string => `the page stopped answering for ${stall / 1000} seconds: its main thread is busy, or its renderer hung`
72
+
73
+ /** Whether the page runs a script within `most` milliseconds. A page that is closed or navigating has answered. */
74
+ const answers = (page: PlaywrightTypes.Page, most: number): Promise<boolean> =>
75
+ new Promise((resolve) => {
76
+ // oxlint-disable-next-line ritmo/use-clock-for-time -- a tool on the developer's machine, not a simulation: it times a page that no longer answers, so no page timer or tick can do it
77
+ const timer = setTimeout(() => resolve(false), most)
78
+ void page.evaluate(() => true).then(() => true, () => true).then((answered) => {
79
+ clearTimeout(timer)
80
+ resolve(answered)
81
+ })
82
+ })
83
+
84
+ /** Opens a page that is closed once it has not answered for `stall` milliseconds. */
85
+ export const open = async (browser: PlaywrightTypes.Browser, stall: number, options: OpenOptions = desktop): Promise<Opened> => {
86
+ const context = await browser.newContext({
87
+ viewport: { width: options.width, height: options.height },
88
+ hasTouch: options.touch,
89
+ isMobile: options.touch,
90
+ reducedMotion: options.reducedMotion === true ? "reduce" : "no-preference"
91
+ })
92
+ const page = await context.newPage()
93
+ await page.addInitScript(pageScript)
94
+ for (const script of options.scripts ?? []) await page.addInitScript(script)
95
+ const errors: Array<string> = []
96
+ page.on("pageerror", (error) => errors.push(error.message))
97
+ const network = { inFlight: 0, activity: 0 }
98
+ page.on("request", () => {
99
+ network.inFlight++
100
+ network.activity++
101
+ })
102
+ const ended = (): void => {
103
+ network.inFlight = Math.max(0, network.inFlight - 1)
104
+ network.activity++
105
+ }
106
+ page.on("requestfinished", ended)
107
+ page.on("requestfailed", ended)
108
+ const cdp = await context.newCDPSession(page)
109
+ // The device's own space (a notch, a home bar): what CSS reads as env(safe-area-inset-*).
110
+ if (options.insets !== undefined) await cdp.send("Emulation.setSafeAreaInsetsOverride", { insets: options.insets })
111
+ const state = () => page.evaluate(() => (Reflect.get(globalThis, "__ritmoKeyboardWalk") as { state: () => PageState }).state())
112
+ const control = async (described: Described): Promise<Control> => {
113
+ try {
114
+ const evaluated = await cdp.send("Runtime.evaluate", { expression: `__ritmoKeyboardWalk.element(${described.id})`, objectGroup: "ritmo-keyboard" })
115
+ const objectId = evaluated.result.objectId
116
+ if (objectId === undefined) return { role: "", name: "", selector: described.selector }
117
+ const tree = await cdp.send("Accessibility.getPartialAXTree", { objectId, fetchRelatives: false })
118
+ const node = tree.nodes[0]
119
+ const role = node?.role?.value
120
+ const name = node?.name?.value
121
+ return { role: typeof role === "string" ? role : "", name: typeof name === "string" ? name.trim() : "", selector: described.selector }
122
+ } catch {
123
+ return { role: "", name: "", selector: described.selector }
124
+ }
125
+ }
126
+ // Closing a page that stopped answering rejects every call still waiting on it, so the walk moves on.
127
+ let stalled = false
128
+ const watch = async (): Promise<void> => {
129
+ while (!page.isClosed()) {
130
+ if (!(await answers(page, stall))) {
131
+ stalled = !page.isClosed()
132
+ await page.close().catch(() => undefined)
133
+ return
134
+ }
135
+ await page.waitForTimeout(1000).catch(() => undefined)
136
+ }
137
+ }
138
+ void watch()
139
+ return { page, errors, network, stalled: () => stalled, state, control, close: () => context.close().catch(() => undefined) }
140
+ }
141
+
142
+ /** Opens the screen: loads its URL, lets it settle, and runs its steps. A failed step is returned as its message. */
143
+ export const reach = async (opened: Opened, url: string, screen: Screen, settle: number): Promise<string | undefined> => {
144
+ const { page } = opened
145
+ try {
146
+ await page.goto(screenUrl(url, screen.path), { waitUntil: "load" })
147
+ } catch (error) {
148
+ return `the page did not load: ${error instanceof Error ? error.message : String(error)}`
149
+ }
150
+ await settled(opened, settle)
151
+ for (const [index, step] of screen.steps.entries()) {
152
+ const at = `steps[${index}]`
153
+ try {
154
+ if ("press" in step) await page.keyboard.press(step.press)
155
+ else if ("type" in step) await page.keyboard.type(step.type)
156
+ else if ("wait" in step) await page.waitForTimeout(step.wait)
157
+ else if ("waitFor" in step) {
158
+ const target = await find(opened, step.waitFor, 15_000)
159
+ if (target === undefined) return `${at}: no visible ${step.waitFor.role} named ${JSON.stringify(step.waitFor.name)} showed within 15 seconds (names are the ones this report prints)`
160
+ } else {
161
+ const target = await find(opened, step.click, 5000)
162
+ if (target === undefined) return `${at}: no visible ${step.click.role} named ${JSON.stringify(step.click.name)} to click (names are the ones this report prints)`
163
+ await page.locator(target.selector).first().click({ timeout: 5000 })
164
+ }
165
+ } catch (error) {
166
+ return `${at} failed: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`
167
+ }
168
+ await page.waitForTimeout(300)
169
+ }
170
+ return undefined
171
+ }
172
+
173
+ /**
174
+ * The first visible element with this role and accessible name (in the open
175
+ * menu first, then on the page), by the names
176
+ * this report prints (Chromium's accessibility tree), so a name copied from a
177
+ * report finds its control. Waits up to about `most` milliseconds for it to show.
178
+ */
179
+ export const find = async (opened: Opened, wanted: { readonly role: string; readonly name: string }, most: number): Promise<Described | undefined> => {
180
+ for (let waited = 0; waited <= most; waited += 150) {
181
+ // An open menu first: its button wins over one of the same name behind it (a confirm's "Skip" over the HUD's).
182
+ const menu = (await opened.state()).menu
183
+ const inMenu = menu === null ? [] : await call(opened.page, "controls", menu.id) as ReadonlyArray<Described>
184
+ const candidates = [...inMenu, ...await call(opened.page, "controls", null) as ReadonlyArray<Described>]
185
+ for (const candidate of candidates) {
186
+ const control = await opened.control(candidate)
187
+ if (control.role === wanted.role && control.name === wanted.name) return candidate
188
+ }
189
+ await opened.page.waitForTimeout(150)
190
+ }
191
+ return undefined
192
+ }
193
+
194
+ /**
195
+ * Waits for a loaded page to stop changing: no request in flight, and the
196
+ * same menu, focus, and visible controls for 400 ms of the page's own clock,
197
+ * or `most` milliseconds at the latest. A page that never goes quiet (it
198
+ * polls a server, or keeps redrawing its controls) waits the whole `most`.
199
+ */
200
+ export const settled = async (opened: Opened, most: number): Promise<void> => {
201
+ const quiet = 400
202
+ let start: number | undefined
203
+ let since = 0
204
+ let seen: string | undefined
205
+ // The count bounds a page whose clock cannot be read (it is navigating).
206
+ for (let polls = 0; polls * 50 <= most * 2; polls++) {
207
+ try {
208
+ const at = await opened.page.evaluate(() => (Reflect.get(globalThis, "__ritmoKeyboardWalk") as { signature: () => { now: number; key: string } }).signature())
209
+ const key = `${at.key} ${opened.network.activity}`
210
+ if (start === undefined || at.now < since) start = since = at.now
211
+ if (key !== seen || opened.network.inFlight > 0) since = at.now
212
+ seen = key
213
+ if (at.now - since >= quiet || at.now - start >= most) return
214
+ } catch {
215
+ seen = undefined
216
+ }
217
+ await opened.page.waitForTimeout(50)
218
+ }
219
+ }
220
+
221
+ export const call = <A>(page: PlaywrightTypes.Page, name: string, argument: A): Promise<unknown> =>
222
+ page.evaluate(
223
+ ({ name, argument }) => (Reflect.get(globalThis, "__ritmoKeyboardWalk") as Record<string, (argument: unknown, more?: unknown) => unknown>)[name]!(argument),
224
+ { name, argument }
225
+ )