@dloizides/game-e2e 1.4.1 → 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 +119 -0
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +113 -1
- 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
|
@@ -903,6 +903,118 @@ ${renderWalk(results)}`);
|
|
|
903
903
|
}
|
|
904
904
|
}
|
|
905
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
|
+
|
|
906
1018
|
exports.ANTI_ALIAS_TOLERANCE = ANTI_ALIAS_TOLERANCE;
|
|
907
1019
|
exports.CANVAS_TIMEOUT_MS = CANVAS_TIMEOUT_MS;
|
|
908
1020
|
exports.CONTROL_SELECTOR = CONTROL_SELECTOR;
|
|
@@ -919,6 +1031,8 @@ exports.PHONE_DEVICE = PHONE_DEVICE;
|
|
|
919
1031
|
exports.PHONE_SIZE = PHONE_SIZE;
|
|
920
1032
|
exports.RELAYOUT_TIMEOUT_MS = RELAYOUT_TIMEOUT_MS;
|
|
921
1033
|
exports.STUB_FRAMES = STUB_FRAMES;
|
|
1034
|
+
exports.TEXT_FIT_SELECTOR = TEXT_FIT_SELECTOR;
|
|
1035
|
+
exports.TEXT_FIT_TOLERANCE_PX = TEXT_FIT_TOLERANCE_PX;
|
|
922
1036
|
exports.WALK_INPUTS = WALK_INPUTS;
|
|
923
1037
|
exports.armVisibleHeight = armVisibleHeight;
|
|
924
1038
|
exports.auditRoute = auditRoute;
|
|
@@ -937,6 +1051,7 @@ exports.expectHookMenuWalkable = expectHookMenuWalkable;
|
|
|
937
1051
|
exports.expectMenuWalkable = expectMenuWalkable;
|
|
938
1052
|
exports.expectNoHorizontalOverflow = expectNoHorizontalOverflow;
|
|
939
1053
|
exports.expectNoHorizontalOverflowAcrossRoutes = expectNoHorizontalOverflowAcrossRoutes;
|
|
1054
|
+
exports.expectTextFits = expectTextFits;
|
|
940
1055
|
exports.expectTouchTargets = expectTouchTargets;
|
|
941
1056
|
exports.expectTouchTargetsAcrossRoutes = expectTouchTargetsAcrossRoutes;
|
|
942
1057
|
exports.findOverlaps = findOverlaps;
|
|
@@ -944,9 +1059,11 @@ exports.findOverlapsWithin = findOverlapsWithin;
|
|
|
944
1059
|
exports.gameProjects = gameProjects;
|
|
945
1060
|
exports.horizontalOverflowPx = horizontalOverflowPx;
|
|
946
1061
|
exports.measureHorizontalOverflow = measureHorizontalOverflow;
|
|
1062
|
+
exports.measureTextFit = measureTextFit;
|
|
947
1063
|
exports.overlaps = overlaps;
|
|
948
1064
|
exports.phone = phone;
|
|
949
1065
|
exports.readHorizontalOverflow = readHorizontalOverflow;
|
|
1066
|
+
exports.readTextBoxes = readTextBoxes;
|
|
950
1067
|
exports.regionDiff = regionDiff;
|
|
951
1068
|
exports.renderFindings = renderFindings;
|
|
952
1069
|
exports.renderOverflow = renderOverflow;
|
|
@@ -956,7 +1073,9 @@ exports.routeProblems = routeProblems;
|
|
|
956
1073
|
exports.shrinkVisibleHeight = shrinkVisibleHeight;
|
|
957
1074
|
exports.stubGamepad = stubGamepad;
|
|
958
1075
|
exports.summariseOverflow = summariseOverflow;
|
|
1076
|
+
exports.summariseTextFit = summariseTextFit;
|
|
959
1077
|
exports.summariseTouchTargets = summariseTouchTargets;
|
|
1078
|
+
exports.textFitFindings = textFitFindings;
|
|
960
1079
|
exports.toOverflowReading = toOverflowReading;
|
|
961
1080
|
exports.walkFailed = walkFailed;
|
|
962
1081
|
exports.walkHookMenus = walkHookMenus;
|