@dloizides/game-e2e 1.4.0 → 1.5.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 +8 -0
- package/README.md +122 -116
- package/dist/index.d.mts +53 -1
- package/dist/index.d.ts +53 -1
- package/dist/index.js +132 -5
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +126 -6
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to `@dloizides/game-e2e` are documented here.
|
|
4
4
|
|
|
5
|
+
## 1.5.0
|
|
6
|
+
|
|
7
|
+
TEXT-FIT-1 "UI text never overflows its box at 360x640 or desktop, in every state":
|
|
8
|
+
|
|
9
|
+
- `expectTextFits(page, selector?, options?)`, `measureTextFit`, `readTextBoxes`, `summariseTextFit`, `textFitFindings`:
|
|
10
|
+
fails when visible text is wider/taller than its box or spills its parent, across named UI states. Trigger: Surge's
|
|
11
|
+
"Daily run" button with the "Completed today" badge ran past the button edge at 360x640 and 1280.
|
|
12
|
+
|
|
5
13
|
## 1.4.0
|
|
6
14
|
|
|
7
15
|
GAME-E2E-PRESS-1 "Faster pad presses in game-e2e walks":
|
package/README.md
CHANGED
|
@@ -1,116 +1,122 @@
|
|
|
1
|
-
# @dloizides/game-e2e
|
|
2
|
-
|
|
3
|
-
Playwright helpers for the EisaiPollis browser games. Aurora, Surge and Morphe each held a copy of the
|
|
4
|
-
same fixtures; this package is the one copy. Where the three differed, the default is the strictest
|
|
5
|
-
behaviour and the looser one is an option.
|
|
6
|
-
|
|
7
|
-
```bash
|
|
8
|
-
npm install -D @dloizides/game-e2e
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
`@playwright/test` (>= 1.57) is a peer dependency.
|
|
12
|
-
|
|
13
|
-
## Projects: device descriptors, never a bare viewport
|
|
14
|
-
|
|
15
|
-
```ts
|
|
16
|
-
import { defineConfig } from '@playwright/test';
|
|
17
|
-
import { gameProjects } from '@dloizides/game-e2e';
|
|
18
|
-
|
|
19
|
-
export default defineConfig({ projects: gameProjects() });
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
`gameProjects()` returns `phone` (Galaxy S5 descriptor: mobile UA, touch, `isMobile`, at 360x640) and
|
|
23
|
-
`desktop` (Desktop Chrome at 1280x720, scale factor 1). A bare `viewport` has no touch flag, no scale
|
|
24
|
-
factor and no mobile UA, so it is not offered. `phone(w, h, dsf?)` and `desktop(w, h, dsf?)` build a
|
|
25
|
-
single context, e.g. `test.use(phone(390, 844))`.
|
|
26
|
-
|
|
27
|
-
## Visible height and fit
|
|
28
|
-
|
|
29
|
-
```ts
|
|
30
|
-
await armVisibleHeight(page);
|
|
31
|
-
await page.goto('/');
|
|
32
|
-
await shrinkVisibleHeight(page, 560, { relayoutGlobal: '__auroraGame' });
|
|
33
|
-
await expectFitTo(page, 560);
|
|
34
|
-
await expectCanvasHeight(page, 560, { canvasSelector: '#game-container canvas' });
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
| Option | Default | Why |
|
|
38
|
-
|---|---|---|
|
|
39
|
-
| `shrinkVisibleHeight` `relayoutGlobal` | none | Aurora's behaviour: wait until every active Phaser scene on `window[relayoutGlobal]` re-creates. Throws when the global is missing (Aurora's copy passed silently). Without it, the call only fires the resize (Surge, Morphe). |
|
|
40
|
-
| `expectCanvasHeight` / `expectCanvasInside` `canvasSelector` | `canvas` | Aurora `#game-container canvas`, Surge `#app canvas`, Morphe `#game-root canvas`. |
|
|
41
|
-
| `expectCanvasHeight` `timeout` | 15 s | Aurora's value; Surge used 10 s. |
|
|
42
|
-
|
|
43
|
-
## Boxes and overlaps
|
|
44
|
-
|
|
45
|
-
`domControls(page, selector?)` names each control `tag#id:text` or `tag.class:text` (Surge's form; Aurora and
|
|
46
|
-
Morphe dropped the text, which made two unnamed buttons indistinguishable). `findOverlaps(a, b)` and
|
|
47
|
-
`findOverlapsWithin(boxes)` return the overlapping pairs; `canvasBoxToPage(frame, bounds, name, band?)`
|
|
48
|
-
is the game-space to CSS-px transform the scene-target probes use.
|
|
49
|
-
|
|
50
|
-
## Pixel and region diff
|
|
51
|
-
|
|
52
|
-
```ts
|
|
53
|
-
const r = await diffPngs(browser, before, after);
|
|
54
|
-
const s = await regionDiff(page.context(), { png: a, region: { x: 0, y: 0, w: 200, h: 80 } }, { png: b, region: null }, { tolerance: ANTI_ALIAS_TOLERANCE });
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
Returns `{ differing, total, ratio, bbox }`. Default is exact (any RGB change counts) and the two PNGs must
|
|
58
|
-
be the same size, as in Aurora. `tolerance: ANTI_ALIAS_TOLERANCE` (48) and `width`/`height` give Surge's
|
|
59
|
-
tolerant comparison of both images scaled to one size. Alpha is ignored in both.
|
|
60
|
-
|
|
61
|
-
## Mobile gates
|
|
62
|
-
|
|
63
|
-
- `expectTouchTargets(page, where)` / `auditRoute` + `expectTouchTargetsAcrossRoutes(readings, portal)`:
|
|
64
|
-
every reachable pressable is at least 44x44 (`MIN_TARGET_PX`) and has a role or an accessible name. One
|
|
65
|
-
assertion per portal; a route that reads zero targets fails as a broken probe.
|
|
66
|
-
- `expectNoHorizontalOverflow(page, where)` / `measureHorizontalOverflow` +
|
|
67
|
-
`expectNoHorizontalOverflowAcrossRoutes`: overflow is `scrollWidth` minus the narrower of
|
|
68
|
-
`visualViewport.width` and `clientWidth`. Morphe compared against `clientWidth`, Aurora against the visual
|
|
69
|
-
viewport; the gate fails if either says the page scrolls sideways.
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
|
82
|
-
|
|
83
|
-
| `game-fit.ts` `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
|
91
|
-
|
|
92
|
-
| `
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
|
97
|
-
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
|
106
|
-
|
|
107
|
-
| `
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
1
|
+
# @dloizides/game-e2e
|
|
2
|
+
|
|
3
|
+
Playwright helpers for the EisaiPollis browser games. Aurora, Surge and Morphe each held a copy of the
|
|
4
|
+
same fixtures; this package is the one copy. Where the three differed, the default is the strictest
|
|
5
|
+
behaviour and the looser one is an option.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install -D @dloizides/game-e2e
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
`@playwright/test` (>= 1.57) is a peer dependency.
|
|
12
|
+
|
|
13
|
+
## Projects: device descriptors, never a bare viewport
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { defineConfig } from '@playwright/test';
|
|
17
|
+
import { gameProjects } from '@dloizides/game-e2e';
|
|
18
|
+
|
|
19
|
+
export default defineConfig({ projects: gameProjects() });
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
`gameProjects()` returns `phone` (Galaxy S5 descriptor: mobile UA, touch, `isMobile`, at 360x640) and
|
|
23
|
+
`desktop` (Desktop Chrome at 1280x720, scale factor 1). A bare `viewport` has no touch flag, no scale
|
|
24
|
+
factor and no mobile UA, so it is not offered. `phone(w, h, dsf?)` and `desktop(w, h, dsf?)` build a
|
|
25
|
+
single context, e.g. `test.use(phone(390, 844))`.
|
|
26
|
+
|
|
27
|
+
## Visible height and fit
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
await armVisibleHeight(page);
|
|
31
|
+
await page.goto('/');
|
|
32
|
+
await shrinkVisibleHeight(page, 560, { relayoutGlobal: '__auroraGame' });
|
|
33
|
+
await expectFitTo(page, 560);
|
|
34
|
+
await expectCanvasHeight(page, 560, { canvasSelector: '#game-container canvas' });
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
| Option | Default | Why |
|
|
38
|
+
|---|---|---|
|
|
39
|
+
| `shrinkVisibleHeight` `relayoutGlobal` | none | Aurora's behaviour: wait until every active Phaser scene on `window[relayoutGlobal]` re-creates. Throws when the global is missing (Aurora's copy passed silently). Without it, the call only fires the resize (Surge, Morphe). |
|
|
40
|
+
| `expectCanvasHeight` / `expectCanvasInside` `canvasSelector` | `canvas` | Aurora `#game-container canvas`, Surge `#app canvas`, Morphe `#game-root canvas`. |
|
|
41
|
+
| `expectCanvasHeight` `timeout` | 15 s | Aurora's value; Surge used 10 s. |
|
|
42
|
+
|
|
43
|
+
## Boxes and overlaps
|
|
44
|
+
|
|
45
|
+
`domControls(page, selector?)` names each control `tag#id:text` or `tag.class:text` (Surge's form; Aurora and
|
|
46
|
+
Morphe dropped the text, which made two unnamed buttons indistinguishable). `findOverlaps(a, b)` and
|
|
47
|
+
`findOverlapsWithin(boxes)` return the overlapping pairs; `canvasBoxToPage(frame, bounds, name, band?)`
|
|
48
|
+
is the game-space to CSS-px transform the scene-target probes use.
|
|
49
|
+
|
|
50
|
+
## Pixel and region diff
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
const r = await diffPngs(browser, before, after);
|
|
54
|
+
const s = await regionDiff(page.context(), { png: a, region: { x: 0, y: 0, w: 200, h: 80 } }, { png: b, region: null }, { tolerance: ANTI_ALIAS_TOLERANCE });
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Returns `{ differing, total, ratio, bbox }`. Default is exact (any RGB change counts) and the two PNGs must
|
|
58
|
+
be the same size, as in Aurora. `tolerance: ANTI_ALIAS_TOLERANCE` (48) and `width`/`height` give Surge's
|
|
59
|
+
tolerant comparison of both images scaled to one size. Alpha is ignored in both.
|
|
60
|
+
|
|
61
|
+
## Mobile gates
|
|
62
|
+
|
|
63
|
+
- `expectTouchTargets(page, where)` / `auditRoute` + `expectTouchTargetsAcrossRoutes(readings, portal)`:
|
|
64
|
+
every reachable pressable is at least 44x44 (`MIN_TARGET_PX`) and has a role or an accessible name. One
|
|
65
|
+
assertion per portal; a route that reads zero targets fails as a broken probe.
|
|
66
|
+
- `expectNoHorizontalOverflow(page, where)` / `measureHorizontalOverflow` +
|
|
67
|
+
`expectNoHorizontalOverflowAcrossRoutes`: overflow is `scrollWidth` minus the narrower of
|
|
68
|
+
`visualViewport.width` and `clientWidth`. Morphe compared against `clientWidth`, Aurora against the visual
|
|
69
|
+
viewport; the gate fails if either says the page scrolls sideways.
|
|
70
|
+
|
|
71
|
+
- `expectTextFits(page, selector?, { states?, where?, tolerancePx? })` / `measureTextFit` / `readTextBoxes`:
|
|
72
|
+
TEXT-FIT-1 "UI text never overflows its box". Every visible element under `selector` (default `body *`)
|
|
73
|
+
that holds its own text fails when its `scrollWidth`/`scrollHeight` exceeds its box, or when its box
|
|
74
|
+
spills the block it sits in (scroll containers excepted). `states` walks named UI states (`enter(page)`)
|
|
75
|
+
and reports all of them in one assertion; a state that matched no text is a BLIND failure.
|
|
76
|
+
|
|
77
|
+
## Migration
|
|
78
|
+
|
|
79
|
+
### Aurora (`tests/design-ac/fixtures/`)
|
|
80
|
+
|
|
81
|
+
| Local | Export |
|
|
82
|
+
|---|---|
|
|
83
|
+
| `game-fit.ts` `phone`, `desktop` | `phone`, `desktop` (same signature) |
|
|
84
|
+
| `game-fit.ts` `armVisibleHeight` | `armVisibleHeight` |
|
|
85
|
+
| `game-fit.ts` `shrinkVisibleHeight(page, h)` | `shrinkVisibleHeight(page, h, { relayoutGlobal: '__auroraGame' })` |
|
|
86
|
+
| `game-fit.ts` `Box`, `overlaps`, `domControls` | `Box`, `overlaps`, `domControls` (names gain `:text`) |
|
|
87
|
+
| `game-fit.ts` `expectFitTo` | `expectFitTo` |
|
|
88
|
+
| `game-fit.ts` `expectCanvasHeight` | `expectCanvasHeight(page, h, { canvasSelector: '#game-container canvas' })` |
|
|
89
|
+
| `game-fit.ts` `sceneTargets`, `titleTexts` | stay local; may use `canvasBoxToPage` |
|
|
90
|
+
| `pixel-diff.ts` `countDiffPixels(browser, a, b)` | `diffPngs(browser, a, b)` (`differing`, `total`, `bbox` unchanged, plus `ratio`) |
|
|
91
|
+
| `mobile-gates.ts` (all) | same names: `MIN_TARGET_PX`, `auditTouchTargets`, `auditRoute`, `expectTouchTargets`, `expectTouchTargetsAcrossRoutes` |
|
|
92
|
+
| `mobile-overflow.ts` (all) | same names: `readHorizontalOverflow`, `measureHorizontalOverflow`, `expectNoHorizontalOverflow`, `expectNoHorizontalOverflowAcrossRoutes` |
|
|
93
|
+
|
|
94
|
+
### Surge (`e2e/fixtures/`)
|
|
95
|
+
|
|
96
|
+
| Local | Export |
|
|
97
|
+
|---|---|
|
|
98
|
+
| `game-fit.ts` `phone`, `desktop` | `phone`, `desktop` |
|
|
99
|
+
| `game-fit.ts` `armVisibleHeight`, `shrinkVisibleHeight` | same names |
|
|
100
|
+
| `game-fit.ts` `Box`, `overlaps`, `domControls`, `expectFitTo` | same names |
|
|
101
|
+
| `game-fit.ts` `expectCanvasHeight` | `expectCanvasHeight(page, h, { canvasSelector: '#app canvas', timeout: 10_000 })` |
|
|
102
|
+
| `game-fit.ts` `horizontalOverflow` | `horizontalOverflowPx` |
|
|
103
|
+
| `game-fit.ts` `openTitle` | stays local |
|
|
104
|
+
| `pixelDiff.ts` `CHANNEL_TOLERANCE` | `ANTI_ALIAS_TOLERANCE` |
|
|
105
|
+
| `pixelDiff.ts` `diffPngs(page, a, b, w, h)` | `(await diffPngs(page.context(), a, b, { width: w, height: h, tolerance: ANTI_ALIAS_TOLERANCE })).ratio` |
|
|
106
|
+
| `regionDiff.ts` `regionDiff(page, a, ra, b, rb, w, h)` | `(await regionDiff(page.context(), { png: a, region: ra }, { png: b, region: rb }, { width: w, height: h, tolerance: ANTI_ALIAS_TOLERANCE })).ratio` |
|
|
107
|
+
| `regionDiff.ts` `Region` | `Region` |
|
|
108
|
+
|
|
109
|
+
### Morphe (`e2e/fixtures/`)
|
|
110
|
+
|
|
111
|
+
| Local | Export |
|
|
112
|
+
|---|---|
|
|
113
|
+
| `game-fit.ts` `phone`, `desktop` | `phone`, `desktop` |
|
|
114
|
+
| `game-fit.ts` `armVisibleHeight`, `shrinkVisibleHeight` | same names |
|
|
115
|
+
| `game-fit.ts` `Box`, `overlaps`, `domControls`, `expectFitTo` | same names |
|
|
116
|
+
| `game-fit.ts` `expectCanvasInside` | `expectCanvasInside(page, h, { canvasSelector: '#game-root canvas' })` |
|
|
117
|
+
| `game-fit.ts` `expectNoHorizontalScroll(page, label)` | `expectNoHorizontalOverflow(page, label)` (stricter denominator) |
|
|
118
|
+
| `game-fit.ts` `openGame`, `gameTargets` | stay local; `gameTargets` may use `canvasBoxToPage` |
|
|
119
|
+
|
|
120
|
+
## Publish
|
|
121
|
+
|
|
122
|
+
`./publish.ps1 -Bump patch|minor|major` (guarded by `publish-guard.ps1`).
|
package/dist/index.d.mts
CHANGED
|
@@ -284,4 +284,56 @@ declare function walkHookMenus(page: Page, opts: HookWalkOptions): Promise<WalkR
|
|
|
284
284
|
/** NAV-1 gate for canvas menus: throws, naming every unreached item and problem, unless all screens walk. */
|
|
285
285
|
declare function expectHookMenuWalkable(page: Page, opts: HookWalkOptions): Promise<void>;
|
|
286
286
|
|
|
287
|
-
|
|
287
|
+
declare const TEXT_FIT_TOLERANCE_PX = 1;
|
|
288
|
+
/** One visible text element: its own box and content size, and the box of the block it sits in. */
|
|
289
|
+
interface TextBoxReading {
|
|
290
|
+
name: string;
|
|
291
|
+
text: string;
|
|
292
|
+
inline: boolean;
|
|
293
|
+
clientWidth: number;
|
|
294
|
+
clientHeight: number;
|
|
295
|
+
scrollWidth: number;
|
|
296
|
+
scrollHeight: number;
|
|
297
|
+
left: number;
|
|
298
|
+
top: number;
|
|
299
|
+
right: number;
|
|
300
|
+
bottom: number;
|
|
301
|
+
parentLeft: number;
|
|
302
|
+
parentTop: number;
|
|
303
|
+
parentRight: number;
|
|
304
|
+
parentBottom: number;
|
|
305
|
+
}
|
|
306
|
+
interface TextFitFinding {
|
|
307
|
+
name: string;
|
|
308
|
+
text: string;
|
|
309
|
+
why: string;
|
|
310
|
+
px: number;
|
|
311
|
+
}
|
|
312
|
+
interface StateTextFit {
|
|
313
|
+
state: string;
|
|
314
|
+
readings: readonly TextBoxReading[];
|
|
315
|
+
}
|
|
316
|
+
/** Every way one reading breaks the rule: content larger than its own box, or the box outside its parent's. */
|
|
317
|
+
declare function textFitFindings(r: TextBoxReading, tol?: number): TextFitFinding[];
|
|
318
|
+
/** Folds every UI state into one tally; a state that measured no text at all is a blind probe and counts as a problem. */
|
|
319
|
+
declare function summariseTextFit(states: readonly StateTextFit[], where: string, tol?: number): GateSummary;
|
|
320
|
+
|
|
321
|
+
declare const TEXT_FIT_SELECTOR = "body *";
|
|
322
|
+
/** A UI state to measure: `enter` puts the page into it (seed a save, open a screen, swap a label). */
|
|
323
|
+
interface TextFitState {
|
|
324
|
+
name: string;
|
|
325
|
+
enter: (page: Page) => Promise<void>;
|
|
326
|
+
}
|
|
327
|
+
interface TextFitOptions {
|
|
328
|
+
states?: readonly TextFitState[];
|
|
329
|
+
where?: string;
|
|
330
|
+
tolerancePx?: number;
|
|
331
|
+
}
|
|
332
|
+
/** Reads every visible element under `selector` that holds its own text, with the box of the block it sits in. */
|
|
333
|
+
declare function readTextBoxes(page: Page, selector?: string): Promise<TextBoxReading[]>;
|
|
334
|
+
/** Measures every given state (or the current page) and returns the per-state readings; asserts nothing. */
|
|
335
|
+
declare function measureTextFit(page: Page, selector?: string, states?: readonly TextFitState[]): Promise<StateTextFit[]>;
|
|
336
|
+
/** Fails when any visible text under `selector` is larger than its box or spills its parent, in any given UI state. */
|
|
337
|
+
declare function expectTextFits(page: Page, selector?: string, options?: TextFitOptions): Promise<StateTextFit[]>;
|
|
338
|
+
|
|
339
|
+
export { ANTI_ALIAS_TOLERANCE, type Band, type Box, CANVAS_TIMEOUT_MS, CONTROL_SELECTOR, type CanvasFrame, type CanvasOptions, type ControlIdentity, DEFAULT_CANVAS_SELECTOR, DESKTOP_DEVICE, DESKTOP_SIZE, type DiffOptions, type DiffResult, EXACT, FIT_TIMEOUT_MS, type FitOptions, GAME_SHELL_HEIGHT_VAR, type GameProject, type GameProjectsOptions, type GateSummary, HOOK_WALK_SIZES, type HookScreen, type HookWalkOptions, MAX_REPORTED, MIN_TARGET_PX, type OverflowMetrics, type OverflowReading, PHONE_DEVICE, PHONE_SIZE, type PadDriver, type PageFactory, RELAYOUT_TIMEOUT_MS, type Rect, type Region, type RegionInput, type RouteAudit, type RouteOverflow, STUB_FRAMES, type ShrinkOptions, type Size, type StateTextFit, TEXT_FIT_SELECTOR, TEXT_FIT_TOLERANCE_PX, type TargetAudit, type TargetFinding, type TargetProbeFunnel, type TextBoxReading, type TextFitFinding, type TextFitOptions, type TextFitState, WALK_INPUTS, type WalkInput, type WalkOptions, type WalkResult, type WalkScreen, armVisibleHeight, auditRoute, auditTouchTargets, canvasBoxToPage, controlName, countDiff, desktop, deviceDescriptor, diffPngs, domControls, expectCanvasHeight, expectCanvasInside, expectFitTo, expectHookMenuWalkable, expectMenuWalkable, expectNoHorizontalOverflow, expectNoHorizontalOverflowAcrossRoutes, expectTextFits, expectTouchTargets, expectTouchTargetsAcrossRoutes, findOverlaps, findOverlapsWithin, gameProjects, horizontalOverflowPx, measureHorizontalOverflow, measureTextFit, overlaps, phone, readHorizontalOverflow, readTextBoxes, regionDiff, renderFindings, renderOverflow, renderRouteAudit, renderWalk, routeProblems, shrinkVisibleHeight, stubGamepad, summariseOverflow, summariseTextFit, summariseTouchTargets, textFitFindings, toOverflowReading, walkFailed, walkHookMenus, walkMenus };
|
package/dist/index.d.ts
CHANGED
|
@@ -284,4 +284,56 @@ declare function walkHookMenus(page: Page, opts: HookWalkOptions): Promise<WalkR
|
|
|
284
284
|
/** NAV-1 gate for canvas menus: throws, naming every unreached item and problem, unless all screens walk. */
|
|
285
285
|
declare function expectHookMenuWalkable(page: Page, opts: HookWalkOptions): Promise<void>;
|
|
286
286
|
|
|
287
|
-
|
|
287
|
+
declare const TEXT_FIT_TOLERANCE_PX = 1;
|
|
288
|
+
/** One visible text element: its own box and content size, and the box of the block it sits in. */
|
|
289
|
+
interface TextBoxReading {
|
|
290
|
+
name: string;
|
|
291
|
+
text: string;
|
|
292
|
+
inline: boolean;
|
|
293
|
+
clientWidth: number;
|
|
294
|
+
clientHeight: number;
|
|
295
|
+
scrollWidth: number;
|
|
296
|
+
scrollHeight: number;
|
|
297
|
+
left: number;
|
|
298
|
+
top: number;
|
|
299
|
+
right: number;
|
|
300
|
+
bottom: number;
|
|
301
|
+
parentLeft: number;
|
|
302
|
+
parentTop: number;
|
|
303
|
+
parentRight: number;
|
|
304
|
+
parentBottom: number;
|
|
305
|
+
}
|
|
306
|
+
interface TextFitFinding {
|
|
307
|
+
name: string;
|
|
308
|
+
text: string;
|
|
309
|
+
why: string;
|
|
310
|
+
px: number;
|
|
311
|
+
}
|
|
312
|
+
interface StateTextFit {
|
|
313
|
+
state: string;
|
|
314
|
+
readings: readonly TextBoxReading[];
|
|
315
|
+
}
|
|
316
|
+
/** Every way one reading breaks the rule: content larger than its own box, or the box outside its parent's. */
|
|
317
|
+
declare function textFitFindings(r: TextBoxReading, tol?: number): TextFitFinding[];
|
|
318
|
+
/** Folds every UI state into one tally; a state that measured no text at all is a blind probe and counts as a problem. */
|
|
319
|
+
declare function summariseTextFit(states: readonly StateTextFit[], where: string, tol?: number): GateSummary;
|
|
320
|
+
|
|
321
|
+
declare const TEXT_FIT_SELECTOR = "body *";
|
|
322
|
+
/** A UI state to measure: `enter` puts the page into it (seed a save, open a screen, swap a label). */
|
|
323
|
+
interface TextFitState {
|
|
324
|
+
name: string;
|
|
325
|
+
enter: (page: Page) => Promise<void>;
|
|
326
|
+
}
|
|
327
|
+
interface TextFitOptions {
|
|
328
|
+
states?: readonly TextFitState[];
|
|
329
|
+
where?: string;
|
|
330
|
+
tolerancePx?: number;
|
|
331
|
+
}
|
|
332
|
+
/** Reads every visible element under `selector` that holds its own text, with the box of the block it sits in. */
|
|
333
|
+
declare function readTextBoxes(page: Page, selector?: string): Promise<TextBoxReading[]>;
|
|
334
|
+
/** Measures every given state (or the current page) and returns the per-state readings; asserts nothing. */
|
|
335
|
+
declare function measureTextFit(page: Page, selector?: string, states?: readonly TextFitState[]): Promise<StateTextFit[]>;
|
|
336
|
+
/** Fails when any visible text under `selector` is larger than its box or spills its parent, in any given UI state. */
|
|
337
|
+
declare function expectTextFits(page: Page, selector?: string, options?: TextFitOptions): Promise<StateTextFit[]>;
|
|
338
|
+
|
|
339
|
+
export { ANTI_ALIAS_TOLERANCE, type Band, type Box, CANVAS_TIMEOUT_MS, CONTROL_SELECTOR, type CanvasFrame, type CanvasOptions, type ControlIdentity, DEFAULT_CANVAS_SELECTOR, DESKTOP_DEVICE, DESKTOP_SIZE, type DiffOptions, type DiffResult, EXACT, FIT_TIMEOUT_MS, type FitOptions, GAME_SHELL_HEIGHT_VAR, type GameProject, type GameProjectsOptions, type GateSummary, HOOK_WALK_SIZES, type HookScreen, type HookWalkOptions, MAX_REPORTED, MIN_TARGET_PX, type OverflowMetrics, type OverflowReading, PHONE_DEVICE, PHONE_SIZE, type PadDriver, type PageFactory, RELAYOUT_TIMEOUT_MS, type Rect, type Region, type RegionInput, type RouteAudit, type RouteOverflow, STUB_FRAMES, type ShrinkOptions, type Size, type StateTextFit, TEXT_FIT_SELECTOR, TEXT_FIT_TOLERANCE_PX, type TargetAudit, type TargetFinding, type TargetProbeFunnel, type TextBoxReading, type TextFitFinding, type TextFitOptions, type TextFitState, WALK_INPUTS, type WalkInput, type WalkOptions, type WalkResult, type WalkScreen, armVisibleHeight, auditRoute, auditTouchTargets, canvasBoxToPage, controlName, countDiff, desktop, deviceDescriptor, diffPngs, domControls, expectCanvasHeight, expectCanvasInside, expectFitTo, expectHookMenuWalkable, expectMenuWalkable, expectNoHorizontalOverflow, expectNoHorizontalOverflowAcrossRoutes, expectTextFits, expectTouchTargets, expectTouchTargetsAcrossRoutes, findOverlaps, findOverlapsWithin, gameProjects, horizontalOverflowPx, measureHorizontalOverflow, measureTextFit, overlaps, phone, readHorizontalOverflow, readTextBoxes, regionDiff, renderFindings, renderOverflow, renderRouteAudit, renderWalk, routeProblems, shrinkVisibleHeight, stubGamepad, summariseOverflow, summariseTextFit, summariseTouchTargets, textFitFindings, toOverflowReading, walkFailed, walkHookMenus, walkMenus };
|
package/dist/index.js
CHANGED
|
@@ -470,14 +470,18 @@ async function expectNoHorizontalOverflow(page, where) {
|
|
|
470
470
|
// src/gamepad-stub.ts
|
|
471
471
|
var STUB_FRAMES = 1;
|
|
472
472
|
var PRESS_WAIT_FRAMES = 240;
|
|
473
|
+
var IDLE_RELEASE_FRAMES = 3;
|
|
473
474
|
var STANDARD_BUTTON_COUNT = 17;
|
|
474
475
|
var AXIS_COUNT = 4;
|
|
475
476
|
function installStub([buttons, axes]) {
|
|
476
477
|
const pad = { id: "nav-walk-stub", index: 0, connected: true, mapping: "standard", timestamp: 0, axes: new Array(axes).fill(0), buttons: Array.from({ length: buttons }, () => ({ pressed: false, touched: false, value: 0 })) };
|
|
477
|
-
const latch = { button: -1, frame: null, released: true };
|
|
478
|
+
const latch = { button: -1, frame: null, released: true, reads: 0 };
|
|
478
479
|
const sample = () => {
|
|
479
480
|
const now = document.timeline.currentTime;
|
|
480
481
|
const held = pad.buttons[latch.button];
|
|
482
|
+
if (held !== void 0) {
|
|
483
|
+
latch.reads += 1;
|
|
484
|
+
}
|
|
481
485
|
if (held !== void 0 && latch.frame === null) {
|
|
482
486
|
latch.frame = typeof now === "number" ? now : 0;
|
|
483
487
|
} else if (held !== void 0 && now !== latch.frame) {
|
|
@@ -492,7 +496,7 @@ function installStub([buttons, axes]) {
|
|
|
492
496
|
Object.defineProperty(navigator, "getGamepads", { configurable: true, value: sample });
|
|
493
497
|
window.addEventListener("load", () => window.dispatchEvent(Object.assign(new Event("gamepadconnected"), { gamepad: pad })));
|
|
494
498
|
}
|
|
495
|
-
async function pressInPage([button, maxFrames]) {
|
|
499
|
+
async function pressInPage([button, maxFrames, idleFrames]) {
|
|
496
500
|
const { __navPad: pad, __navPress: latch } = window;
|
|
497
501
|
const target = pad.buttons[button];
|
|
498
502
|
if (target === void 0) {
|
|
@@ -500,10 +504,14 @@ async function pressInPage([button, maxFrames]) {
|
|
|
500
504
|
}
|
|
501
505
|
target.pressed = true;
|
|
502
506
|
target.value = 1;
|
|
503
|
-
Object.assign(latch, { button, frame: null, released: false });
|
|
507
|
+
Object.assign(latch, { button, frame: null, released: false, reads: 0 });
|
|
504
508
|
await new Promise((resolve) => {
|
|
509
|
+
let seen = 0;
|
|
510
|
+
let idle = 0;
|
|
505
511
|
const step = (left) => {
|
|
506
|
-
|
|
512
|
+
idle = latch.reads === seen ? idle + 1 : 0;
|
|
513
|
+
seen = latch.reads;
|
|
514
|
+
if (latch.released || left === 0 || idle >= idleFrames) {
|
|
507
515
|
target.pressed = false;
|
|
508
516
|
target.value = 0;
|
|
509
517
|
Object.assign(latch, { button: -1, frame: null, released: true });
|
|
@@ -518,7 +526,7 @@ async function pressInPage([button, maxFrames]) {
|
|
|
518
526
|
async function stubGamepad(page) {
|
|
519
527
|
await page.addInitScript(installStub, [STANDARD_BUTTON_COUNT, AXIS_COUNT]);
|
|
520
528
|
return {
|
|
521
|
-
press: (button) => page.evaluate(pressInPage, [button, PRESS_WAIT_FRAMES]),
|
|
529
|
+
press: (button) => page.evaluate(pressInPage, [button, PRESS_WAIT_FRAMES, IDLE_RELEASE_FRAMES]),
|
|
522
530
|
hold: (axis, value) => page.evaluate(([a, v]) => {
|
|
523
531
|
window.__navPad.axes[a] = v;
|
|
524
532
|
}, [axis, value])
|
|
@@ -895,6 +903,118 @@ ${renderWalk(results)}`);
|
|
|
895
903
|
}
|
|
896
904
|
}
|
|
897
905
|
|
|
906
|
+
// src/text-fit-report.ts
|
|
907
|
+
var TEXT_FIT_TOLERANCE_PX = 1;
|
|
908
|
+
function ownOverflow(r, tol) {
|
|
909
|
+
if (r.inline) {
|
|
910
|
+
return null;
|
|
911
|
+
}
|
|
912
|
+
const wide = r.scrollWidth - r.clientWidth;
|
|
913
|
+
const tall = r.scrollHeight - r.clientHeight;
|
|
914
|
+
if (wide > tol) {
|
|
915
|
+
return { name: r.name, text: r.text, why: "text wider than its box", px: wide };
|
|
916
|
+
}
|
|
917
|
+
if (tall > tol) {
|
|
918
|
+
return { name: r.name, text: r.text, why: "text taller than its box", px: tall };
|
|
919
|
+
}
|
|
920
|
+
return null;
|
|
921
|
+
}
|
|
922
|
+
function spill(r, tol) {
|
|
923
|
+
const px = Math.max(r.parentLeft - r.left, r.parentTop - r.top, r.right - r.parentRight, r.bottom - r.parentBottom);
|
|
924
|
+
return px > tol ? { name: r.name, text: r.text, why: "spills out of its parent", px: Math.round(px) } : null;
|
|
925
|
+
}
|
|
926
|
+
function textFitFindings(r, tol = TEXT_FIT_TOLERANCE_PX) {
|
|
927
|
+
return [ownOverflow(r, tol), spill(r, tol)].filter((f) => f !== null);
|
|
928
|
+
}
|
|
929
|
+
var renderFinding = (f) => `
|
|
930
|
+
${f.name} "${f.text}": ${f.why} by ${String(f.px)}px`;
|
|
931
|
+
function summariseTextFit(states, where, tol = TEXT_FIT_TOLERANCE_PX) {
|
|
932
|
+
if (states.length === 0) {
|
|
933
|
+
return { problems: 1, message: `${where}: no UI state was measured at all` };
|
|
934
|
+
}
|
|
935
|
+
let problems = 0;
|
|
936
|
+
const lines = states.map((s) => {
|
|
937
|
+
if (s.readings.length === 0) {
|
|
938
|
+
problems += 1;
|
|
939
|
+
return `
|
|
940
|
+
${s.state}: BLIND - no visible text element matched`;
|
|
941
|
+
}
|
|
942
|
+
const found = s.readings.flatMap((r) => textFitFindings(r, tol));
|
|
943
|
+
problems += found.length;
|
|
944
|
+
const head = found.length > 0 ? `${String(found.length)} overflow(s)` : "ok";
|
|
945
|
+
return `
|
|
946
|
+
${s.state}: ${head} over ${String(s.readings.length)} text element(s)${found.map(renderFinding).join("")}`;
|
|
947
|
+
});
|
|
948
|
+
return { problems, message: `${where}: ${String(states.length)} state(s), ${String(problems)} problem(s)${lines.join("")}` };
|
|
949
|
+
}
|
|
950
|
+
var TEXT_FIT_SELECTOR = "body *";
|
|
951
|
+
async function readTextBoxes(page, selector = TEXT_FIT_SELECTOR) {
|
|
952
|
+
return page.evaluate((sel) => {
|
|
953
|
+
const display = (el) => getComputedStyle(el).display;
|
|
954
|
+
const ownText = (el) => [...el.childNodes].filter((n) => n.nodeType === Node.TEXT_NODE).map((n) => n.textContent ?? "").join("").trim();
|
|
955
|
+
const shown = (el) => {
|
|
956
|
+
const r = el.getBoundingClientRect();
|
|
957
|
+
return r.width > 0 && r.height > 0 && getComputedStyle(el).visibility !== "hidden" && el.closest('[aria-hidden="true"]') === null;
|
|
958
|
+
};
|
|
959
|
+
const scrolls = (el) => /auto|scroll/.test(getComputedStyle(el).overflowX + getComputedStyle(el).overflowY);
|
|
960
|
+
const container = (el) => {
|
|
961
|
+
let p = el.parentElement;
|
|
962
|
+
while (p && (display(p) === "inline" || display(p) === "contents")) {
|
|
963
|
+
p = p.parentElement;
|
|
964
|
+
}
|
|
965
|
+
return p;
|
|
966
|
+
};
|
|
967
|
+
const label = (el) => {
|
|
968
|
+
const id = el.id !== "" ? `#${el.id}` : "";
|
|
969
|
+
const cls = typeof el.className === "string" && el.className.trim() !== "" ? `.${el.className.trim().split(/\s+/).join(".")}` : "";
|
|
970
|
+
return `${el.tagName.toLowerCase()}${id}${cls}`;
|
|
971
|
+
};
|
|
972
|
+
const els = [...document.querySelectorAll(sel)].filter((el) => !(el instanceof SVGElement) && ownText(el) !== "" && shown(el));
|
|
973
|
+
return els.flatMap((el) => {
|
|
974
|
+
const parent = container(el);
|
|
975
|
+
if (!parent || parent === document.body || parent === document.documentElement || scrolls(parent)) {
|
|
976
|
+
return [];
|
|
977
|
+
}
|
|
978
|
+
const r = el.getBoundingClientRect();
|
|
979
|
+
const p = parent.getBoundingClientRect();
|
|
980
|
+
return [{
|
|
981
|
+
name: label(el),
|
|
982
|
+
text: ownText(el).slice(0, 40),
|
|
983
|
+
inline: display(el) === "inline",
|
|
984
|
+
clientWidth: el.clientWidth,
|
|
985
|
+
clientHeight: el.clientHeight,
|
|
986
|
+
scrollWidth: el.scrollWidth,
|
|
987
|
+
scrollHeight: el.scrollHeight,
|
|
988
|
+
left: r.left,
|
|
989
|
+
top: r.top,
|
|
990
|
+
right: r.right,
|
|
991
|
+
bottom: r.bottom,
|
|
992
|
+
parentLeft: p.left,
|
|
993
|
+
parentTop: p.top,
|
|
994
|
+
parentRight: p.right,
|
|
995
|
+
parentBottom: p.bottom
|
|
996
|
+
}];
|
|
997
|
+
});
|
|
998
|
+
}, selector);
|
|
999
|
+
}
|
|
1000
|
+
async function measureTextFit(page, selector = TEXT_FIT_SELECTOR, states) {
|
|
1001
|
+
if (!states || states.length === 0) {
|
|
1002
|
+
return [{ state: "current", readings: await readTextBoxes(page, selector) }];
|
|
1003
|
+
}
|
|
1004
|
+
const out = [];
|
|
1005
|
+
for (const s of states) {
|
|
1006
|
+
await s.enter(page);
|
|
1007
|
+
out.push({ state: s.name, readings: await readTextBoxes(page, selector) });
|
|
1008
|
+
}
|
|
1009
|
+
return out;
|
|
1010
|
+
}
|
|
1011
|
+
async function expectTextFits(page, selector = TEXT_FIT_SELECTOR, options = {}) {
|
|
1012
|
+
const measured = await measureTextFit(page, selector, options.states);
|
|
1013
|
+
const summary = summariseTextFit(measured, options.where ?? selector, options.tolerancePx ?? TEXT_FIT_TOLERANCE_PX);
|
|
1014
|
+
test.expect(summary.problems, summary.message).toBe(0);
|
|
1015
|
+
return measured;
|
|
1016
|
+
}
|
|
1017
|
+
|
|
898
1018
|
exports.ANTI_ALIAS_TOLERANCE = ANTI_ALIAS_TOLERANCE;
|
|
899
1019
|
exports.CANVAS_TIMEOUT_MS = CANVAS_TIMEOUT_MS;
|
|
900
1020
|
exports.CONTROL_SELECTOR = CONTROL_SELECTOR;
|
|
@@ -911,6 +1031,8 @@ exports.PHONE_DEVICE = PHONE_DEVICE;
|
|
|
911
1031
|
exports.PHONE_SIZE = PHONE_SIZE;
|
|
912
1032
|
exports.RELAYOUT_TIMEOUT_MS = RELAYOUT_TIMEOUT_MS;
|
|
913
1033
|
exports.STUB_FRAMES = STUB_FRAMES;
|
|
1034
|
+
exports.TEXT_FIT_SELECTOR = TEXT_FIT_SELECTOR;
|
|
1035
|
+
exports.TEXT_FIT_TOLERANCE_PX = TEXT_FIT_TOLERANCE_PX;
|
|
914
1036
|
exports.WALK_INPUTS = WALK_INPUTS;
|
|
915
1037
|
exports.armVisibleHeight = armVisibleHeight;
|
|
916
1038
|
exports.auditRoute = auditRoute;
|
|
@@ -929,6 +1051,7 @@ exports.expectHookMenuWalkable = expectHookMenuWalkable;
|
|
|
929
1051
|
exports.expectMenuWalkable = expectMenuWalkable;
|
|
930
1052
|
exports.expectNoHorizontalOverflow = expectNoHorizontalOverflow;
|
|
931
1053
|
exports.expectNoHorizontalOverflowAcrossRoutes = expectNoHorizontalOverflowAcrossRoutes;
|
|
1054
|
+
exports.expectTextFits = expectTextFits;
|
|
932
1055
|
exports.expectTouchTargets = expectTouchTargets;
|
|
933
1056
|
exports.expectTouchTargetsAcrossRoutes = expectTouchTargetsAcrossRoutes;
|
|
934
1057
|
exports.findOverlaps = findOverlaps;
|
|
@@ -936,9 +1059,11 @@ exports.findOverlapsWithin = findOverlapsWithin;
|
|
|
936
1059
|
exports.gameProjects = gameProjects;
|
|
937
1060
|
exports.horizontalOverflowPx = horizontalOverflowPx;
|
|
938
1061
|
exports.measureHorizontalOverflow = measureHorizontalOverflow;
|
|
1062
|
+
exports.measureTextFit = measureTextFit;
|
|
939
1063
|
exports.overlaps = overlaps;
|
|
940
1064
|
exports.phone = phone;
|
|
941
1065
|
exports.readHorizontalOverflow = readHorizontalOverflow;
|
|
1066
|
+
exports.readTextBoxes = readTextBoxes;
|
|
942
1067
|
exports.regionDiff = regionDiff;
|
|
943
1068
|
exports.renderFindings = renderFindings;
|
|
944
1069
|
exports.renderOverflow = renderOverflow;
|
|
@@ -948,7 +1073,9 @@ exports.routeProblems = routeProblems;
|
|
|
948
1073
|
exports.shrinkVisibleHeight = shrinkVisibleHeight;
|
|
949
1074
|
exports.stubGamepad = stubGamepad;
|
|
950
1075
|
exports.summariseOverflow = summariseOverflow;
|
|
1076
|
+
exports.summariseTextFit = summariseTextFit;
|
|
951
1077
|
exports.summariseTouchTargets = summariseTouchTargets;
|
|
1078
|
+
exports.textFitFindings = textFitFindings;
|
|
952
1079
|
exports.toOverflowReading = toOverflowReading;
|
|
953
1080
|
exports.walkFailed = walkFailed;
|
|
954
1081
|
exports.walkHookMenus = walkHookMenus;
|