@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,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
|
+
)
|