@dloizides/game-e2e 1.5.0 → 1.6.1

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 CHANGED
@@ -1,80 +1,97 @@
1
- # Changelog
2
-
3
- All notable changes to `@dloizides/game-e2e` are documented here.
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
-
13
- ## 1.4.0
14
-
15
- GAME-E2E-PRESS-1 "Faster pad presses in game-e2e walks":
16
-
17
- - `stubGamepad().press` holds the button for exactly one sampled frame and resolves once a reader has seen it
18
- released (`navigator.getGamepads()` calls latched to `document.timeline.currentTime`), instead of 3+3 fixed
19
- `requestAnimationFrame` ticks. Under CPU load the old hold outlasted the 380 ms pad repeat delay and moved focus
20
- twice, so the walk skipped rows. `STUB_FRAMES` is now 1; `PRESS_WAIT_FRAMES` (240) caps the wait when no reader polls.
21
-
22
- ## 1.3.0
23
-
24
- NAV-1 "Every game menu works with arrow keys and controller", phase 4 (canvas menus):
25
-
26
- - `expectHookMenuWalkable(page, { screens, open, via?, sizes? })` / `walkHookMenus`: walks menus drawn on a canvas
27
- (Phaser, Babylon GUI) through the `window.__menuWalk` hook (`MenuWalkHook` from `@dloizides/game-input` 1.6.0).
28
- Per screen, at phone (360x640) and desktop (1280x720) viewports, by arrow keys and the stubbed pad: learns every
29
- focus transition until no direction is left untried, fails naming each unreached item. `activates: { item, to }`
30
- checks Enter / A opens a screen; Escape / B must leave the screen unless `leaves: false`.
31
- - Arrow/pad driver moved to `menu-walk-driver.ts`, shared by the DOM and hook walkers (adds Enter / A `activate`).
32
-
33
- ## 1.2.1
34
-
35
- - Listener lookup is one `Runtime.evaluate` (DevTools `getEventListeners`) instead of two CDP calls per element. The
36
- per-element calls slowed the walk enough that a screen re-rendering on a late fetch (Surge `stagePreview`) went red.
37
-
38
- ## 1.2.0
39
-
40
- NAV-1 "Every game menu works with arrow keys and controller", walker gap:
41
-
42
- - The walker now finds pointer-only items whose click / pointerdown / pointerup handler is set as a property
43
- (`el.onclick = ...`) or added with `addEventListener`, not only the `[onclick]` attribute. A visible element
44
- with such a handler that is not focusable is reported `unreached`.
45
- - Listeners are read through CDP `DOMDebugger.getEventListeners` (Chromium). Without CDP (Firefox, WebKit) only
46
- the attribute and properties are checked, and each result carries a `notes` line saying so.
47
- - Delegation: an element that contains a walk control, or sits inside one, is never flagged, so a listener on a
48
- menu container does not flag the container or its children. When nested elements are both flagged, only the
49
- innermost is reported.
50
- - `WalkResult.notes` (new, printed as `note:` by `renderWalk`).
51
-
52
- ## 1.1.0
53
-
54
- NAV-1 "Every game menu works with arrow keys and controller", phase 1:
55
-
56
- - `walkMenus()` / `expectMenuWalkable()`: open each screen, walk every focusable control by arrow keys and
57
- by a stubbed gamepad (breadth-first from the focused control), report unreached controls, a dialog that
58
- opens without focus inside it, sliders that ignore Left/Right, and Escape / B that does not close a dialog.
59
- Exemptions take a selector and a printed reason.
60
- - `stubGamepad()`: a `navigator.getGamepads()` stand-in driven from the test (`PadDriver.press`).
61
- - `renderWalk()`, `walkFailed()`, `WALK_INPUTS`.
62
- - Depends on `@dloizides/game-input` ^1.5.1 for the shared focusable and dialog selectors.
63
-
64
- ## 1.0.0
65
-
66
- First release. Playwright helpers that Aurora, Surge and Morphe each carried a copy of, unified on the
67
- strictest behaviour of the three:
68
-
69
- - `phone()` / `desktop()` / `gameProjects()`: Galaxy S5 and Desktop Chrome device descriptors (touch,
70
- mobile UA, isMobile on the phone), resized; never a bare viewport.
71
- - `armVisibleHeight()` / `shrinkVisibleHeight()`: a simulated browser toolbar. `relayoutGlobal` waits for
72
- every active Phaser scene to re-create and throws when the global is missing.
73
- - `expectFitTo()`, `expectCanvasHeight()`, `expectCanvasInside()`: game-shell fit assertions with a
74
- configurable canvas selector.
75
- - `domControls()`, `overlaps()`, `findOverlaps()`, `findOverlapsWithin()`, `canvasBoxToPage()`.
76
- - `diffPngs()` / `regionDiff()` / `countDiff()`: exact by default (tolerance 0, sizes must match);
77
- `ANTI_ALIAS_TOLERANCE` (48) and `width`/`height` opt into Surge's tolerant, scaled comparison.
78
- - `auditTouchTargets()` + `expectTouchTargets(AcrossRoutes)()`: the 44x44 hit-box gate.
79
- - `readHorizontalOverflow()` + `expectNoHorizontalOverflow(AcrossRoutes)()`: the no-horizontal-scroll
80
- gate, measured against the narrower of visualViewport width and clientWidth.
1
+ # Changelog
2
+
3
+ All notable changes to `@dloizides/game-e2e` are documented here.
4
+
5
+ ## 1.6.1
6
+
7
+ GAME-INPUT-PROMPTS-1 "Every action bound, with device labels", D-GIP-9 "Widen AC-GIP-5":
8
+
9
+ - `actionBindingFindings` reports `prompt missing` when a bound action's binding carries a prompt label but no visible
10
+ `data-gi-prompt` shows it (absent, hidden or zero-size chip). Before, such a chip passed. On touch the caller passes
11
+ bindings with `prompt: null`, so hidden chips still pass (AC-GIP-9).
12
+
13
+ ## 1.6.0
14
+
15
+ GAME-INPUT-PROMPTS-1 "Every action bound, with device labels":
16
+
17
+ - `expectActionsBound(page, bindings, options?)`, `measureActionBinding`, `readActionElements`, `toActionReading`,
18
+ `summariseActionBinding`, `actionBindingFindings`: fails when a visible clickable has no `data-gi-action`, a tagged
19
+ action has no key or pad binding, a visible `data-gi-prompt` shows a label other than the current binding, or zero
20
+ elements were read. Bindings are an input (`ActionBindings`), so the gate does not depend on a game-input release.
21
+
22
+ ## 1.5.0
23
+
24
+ TEXT-FIT-1 "UI text never overflows its box at 360x640 or desktop, in every state":
25
+
26
+ - `expectTextFits(page, selector?, options?)`, `measureTextFit`, `readTextBoxes`, `summariseTextFit`, `textFitFindings`:
27
+ fails when visible text is wider/taller than its box or spills its parent, across named UI states. Trigger: Surge's
28
+ "Daily run" button with the "Completed today" badge ran past the button edge at 360x640 and 1280.
29
+
30
+ ## 1.4.0
31
+
32
+ GAME-E2E-PRESS-1 "Faster pad presses in game-e2e walks":
33
+
34
+ - `stubGamepad().press` holds the button for exactly one sampled frame and resolves once a reader has seen it
35
+ released (`navigator.getGamepads()` calls latched to `document.timeline.currentTime`), instead of 3+3 fixed
36
+ `requestAnimationFrame` ticks. Under CPU load the old hold outlasted the 380 ms pad repeat delay and moved focus
37
+ twice, so the walk skipped rows. `STUB_FRAMES` is now 1; `PRESS_WAIT_FRAMES` (240) caps the wait when no reader polls.
38
+
39
+ ## 1.3.0
40
+
41
+ NAV-1 "Every game menu works with arrow keys and controller", phase 4 (canvas menus):
42
+
43
+ - `expectHookMenuWalkable(page, { screens, open, via?, sizes? })` / `walkHookMenus`: walks menus drawn on a canvas
44
+ (Phaser, Babylon GUI) through the `window.__menuWalk` hook (`MenuWalkHook` from `@dloizides/game-input` 1.6.0).
45
+ Per screen, at phone (360x640) and desktop (1280x720) viewports, by arrow keys and the stubbed pad: learns every
46
+ focus transition until no direction is left untried, fails naming each unreached item. `activates: { item, to }`
47
+ checks Enter / A opens a screen; Escape / B must leave the screen unless `leaves: false`.
48
+ - Arrow/pad driver moved to `menu-walk-driver.ts`, shared by the DOM and hook walkers (adds Enter / A `activate`).
49
+
50
+ ## 1.2.1
51
+
52
+ - Listener lookup is one `Runtime.evaluate` (DevTools `getEventListeners`) instead of two CDP calls per element. The
53
+ per-element calls slowed the walk enough that a screen re-rendering on a late fetch (Surge `stagePreview`) went red.
54
+
55
+ ## 1.2.0
56
+
57
+ NAV-1 "Every game menu works with arrow keys and controller", walker gap:
58
+
59
+ - The walker now finds pointer-only items whose click / pointerdown / pointerup handler is set as a property
60
+ (`el.onclick = ...`) or added with `addEventListener`, not only the `[onclick]` attribute. A visible element
61
+ with such a handler that is not focusable is reported `unreached`.
62
+ - Listeners are read through CDP `DOMDebugger.getEventListeners` (Chromium). Without CDP (Firefox, WebKit) only
63
+ the attribute and properties are checked, and each result carries a `notes` line saying so.
64
+ - Delegation: an element that contains a walk control, or sits inside one, is never flagged, so a listener on a
65
+ menu container does not flag the container or its children. When nested elements are both flagged, only the
66
+ innermost is reported.
67
+ - `WalkResult.notes` (new, printed as `note:` by `renderWalk`).
68
+
69
+ ## 1.1.0
70
+
71
+ NAV-1 "Every game menu works with arrow keys and controller", phase 1:
72
+
73
+ - `walkMenus()` / `expectMenuWalkable()`: open each screen, walk every focusable control by arrow keys and
74
+ by a stubbed gamepad (breadth-first from the focused control), report unreached controls, a dialog that
75
+ opens without focus inside it, sliders that ignore Left/Right, and Escape / B that does not close a dialog.
76
+ Exemptions take a selector and a printed reason.
77
+ - `stubGamepad()`: a `navigator.getGamepads()` stand-in driven from the test (`PadDriver.press`).
78
+ - `renderWalk()`, `walkFailed()`, `WALK_INPUTS`.
79
+ - Depends on `@dloizides/game-input` ^1.5.1 for the shared focusable and dialog selectors.
80
+
81
+ ## 1.0.0
82
+
83
+ First release. Playwright helpers that Aurora, Surge and Morphe each carried a copy of, unified on the
84
+ strictest behaviour of the three:
85
+
86
+ - `phone()` / `desktop()` / `gameProjects()`: Galaxy S5 and Desktop Chrome device descriptors (touch,
87
+ mobile UA, isMobile on the phone), resized; never a bare viewport.
88
+ - `armVisibleHeight()` / `shrinkVisibleHeight()`: a simulated browser toolbar. `relayoutGlobal` waits for
89
+ every active Phaser scene to re-create and throws when the global is missing.
90
+ - `expectFitTo()`, `expectCanvasHeight()`, `expectCanvasInside()`: game-shell fit assertions with a
91
+ configurable canvas selector.
92
+ - `domControls()`, `overlaps()`, `findOverlaps()`, `findOverlapsWithin()`, `canvasBoxToPage()`.
93
+ - `diffPngs()` / `regionDiff()` / `countDiff()`: exact by default (tolerance 0, sizes must match);
94
+ `ANTI_ALIAS_TOLERANCE` (48) and `width`/`height` opt into Surge's tolerant, scaled comparison.
95
+ - `auditTouchTargets()` + `expectTouchTargets(AcrossRoutes)()`: the 44x44 hit-box gate.
96
+ - `readHorizontalOverflow()` + `expectNoHorizontalOverflow(AcrossRoutes)()`: the no-horizontal-scroll
97
+ gate, measured against the narrower of visualViewport width and clientWidth.
package/dist/index.d.mts CHANGED
@@ -336,4 +336,55 @@ declare function measureTextFit(page: Page, selector?: string, states?: readonly
336
336
  /** Fails when any visible text under `selector` is larger than its box or spills its parent, in any given UI state. */
337
337
  declare function expectTextFits(page: Page, selector?: string, options?: TextFitOptions): Promise<StateTextFit[]>;
338
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 };
339
+ /** One clickable in-play element: its tagged action, its bindings, and the prompt it shows. */
340
+ interface ActionReading {
341
+ name: string;
342
+ action: string | null;
343
+ hasPointerHandler: boolean;
344
+ key: string | null;
345
+ pad: number | null;
346
+ promptText: string | null;
347
+ expectedPromptText: string | null;
348
+ }
349
+ interface ActionBindingFinding {
350
+ name: string;
351
+ why: string;
352
+ }
353
+ /** Every way one element breaks "every action bound": untagged, no key, no pad button, stale or missing prompt. */
354
+ declare function actionBindingFindings(r: ActionReading): ActionBindingFinding[];
355
+ /** Folds every reading into one tally; zero readings is a blind probe and counts as a problem. */
356
+ declare function summariseActionBinding(readings: readonly ActionReading[], where: string): GateSummary;
357
+
358
+ declare const ACTION_ATTR = "data-gi-action";
359
+ declare const PROMPT_ATTR = "data-gi-prompt";
360
+ declare const POINTER_SELECTOR = "button, a[href], [role=\"button\"], [onclick]";
361
+ declare const ACTION_ROOT_SELECTOR = "body";
362
+ /** One action's current key, pad button and the prompt label the active device should show. */
363
+ interface ActionBinding {
364
+ key: string | null;
365
+ pad: number | null;
366
+ prompt?: string | null;
367
+ }
368
+ type ActionBindings = Readonly<Record<string, ActionBinding | undefined>>;
369
+ /** What the page shows for one element, before it is joined with the bindings. */
370
+ interface ActionElement {
371
+ name: string;
372
+ action: string | null;
373
+ hasPointerHandler: boolean;
374
+ promptText: string | null;
375
+ }
376
+ interface ActionBindingOptions {
377
+ root?: string;
378
+ pointerSelector?: string;
379
+ where?: string;
380
+ }
381
+ /** Joins one element with its action's binding; an action missing from `bindings` reads as unbound. */
382
+ declare function toActionReading(el: ActionElement, bindings: ActionBindings): ActionReading;
383
+ /** Reads every visible clickable or `data-gi-action` element under `root`, with its visible prompt text. */
384
+ declare function readActionElements(page: Page, root?: string, pointerSelector?: string): Promise<ActionElement[]>;
385
+ /** Reads the page and joins each element with `bindings`; asserts nothing. */
386
+ declare function measureActionBinding(page: Page, bindings: ActionBindings, options?: ActionBindingOptions): Promise<ActionReading[]>;
387
+ /** Fails on an untagged clickable, an action without key or pad, a stale prompt, or zero elements read. */
388
+ declare function expectActionsBound(page: Page, bindings: ActionBindings, options?: ActionBindingOptions): Promise<ActionReading[]>;
389
+
390
+ export { ACTION_ATTR, ACTION_ROOT_SELECTOR, ANTI_ALIAS_TOLERANCE, type ActionBinding, type ActionBindingFinding, type ActionBindingOptions, type ActionBindings, type ActionElement, type ActionReading, 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, POINTER_SELECTOR, PROMPT_ATTR, 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, actionBindingFindings, armVisibleHeight, auditRoute, auditTouchTargets, canvasBoxToPage, controlName, countDiff, desktop, deviceDescriptor, diffPngs, domControls, expectActionsBound, expectCanvasHeight, expectCanvasInside, expectFitTo, expectHookMenuWalkable, expectMenuWalkable, expectNoHorizontalOverflow, expectNoHorizontalOverflowAcrossRoutes, expectTextFits, expectTouchTargets, expectTouchTargetsAcrossRoutes, findOverlaps, findOverlapsWithin, gameProjects, horizontalOverflowPx, measureActionBinding, measureHorizontalOverflow, measureTextFit, overlaps, phone, readActionElements, readHorizontalOverflow, readTextBoxes, regionDiff, renderFindings, renderOverflow, renderRouteAudit, renderWalk, routeProblems, shrinkVisibleHeight, stubGamepad, summariseActionBinding, summariseOverflow, summariseTextFit, summariseTouchTargets, textFitFindings, toActionReading, toOverflowReading, walkFailed, walkHookMenus, walkMenus };
package/dist/index.d.ts CHANGED
@@ -336,4 +336,55 @@ declare function measureTextFit(page: Page, selector?: string, states?: readonly
336
336
  /** Fails when any visible text under `selector` is larger than its box or spills its parent, in any given UI state. */
337
337
  declare function expectTextFits(page: Page, selector?: string, options?: TextFitOptions): Promise<StateTextFit[]>;
338
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 };
339
+ /** One clickable in-play element: its tagged action, its bindings, and the prompt it shows. */
340
+ interface ActionReading {
341
+ name: string;
342
+ action: string | null;
343
+ hasPointerHandler: boolean;
344
+ key: string | null;
345
+ pad: number | null;
346
+ promptText: string | null;
347
+ expectedPromptText: string | null;
348
+ }
349
+ interface ActionBindingFinding {
350
+ name: string;
351
+ why: string;
352
+ }
353
+ /** Every way one element breaks "every action bound": untagged, no key, no pad button, stale or missing prompt. */
354
+ declare function actionBindingFindings(r: ActionReading): ActionBindingFinding[];
355
+ /** Folds every reading into one tally; zero readings is a blind probe and counts as a problem. */
356
+ declare function summariseActionBinding(readings: readonly ActionReading[], where: string): GateSummary;
357
+
358
+ declare const ACTION_ATTR = "data-gi-action";
359
+ declare const PROMPT_ATTR = "data-gi-prompt";
360
+ declare const POINTER_SELECTOR = "button, a[href], [role=\"button\"], [onclick]";
361
+ declare const ACTION_ROOT_SELECTOR = "body";
362
+ /** One action's current key, pad button and the prompt label the active device should show. */
363
+ interface ActionBinding {
364
+ key: string | null;
365
+ pad: number | null;
366
+ prompt?: string | null;
367
+ }
368
+ type ActionBindings = Readonly<Record<string, ActionBinding | undefined>>;
369
+ /** What the page shows for one element, before it is joined with the bindings. */
370
+ interface ActionElement {
371
+ name: string;
372
+ action: string | null;
373
+ hasPointerHandler: boolean;
374
+ promptText: string | null;
375
+ }
376
+ interface ActionBindingOptions {
377
+ root?: string;
378
+ pointerSelector?: string;
379
+ where?: string;
380
+ }
381
+ /** Joins one element with its action's binding; an action missing from `bindings` reads as unbound. */
382
+ declare function toActionReading(el: ActionElement, bindings: ActionBindings): ActionReading;
383
+ /** Reads every visible clickable or `data-gi-action` element under `root`, with its visible prompt text. */
384
+ declare function readActionElements(page: Page, root?: string, pointerSelector?: string): Promise<ActionElement[]>;
385
+ /** Reads the page and joins each element with `bindings`; asserts nothing. */
386
+ declare function measureActionBinding(page: Page, bindings: ActionBindings, options?: ActionBindingOptions): Promise<ActionReading[]>;
387
+ /** Fails on an untagged clickable, an action without key or pad, a stale prompt, or zero elements read. */
388
+ declare function expectActionsBound(page: Page, bindings: ActionBindings, options?: ActionBindingOptions): Promise<ActionReading[]>;
389
+
390
+ export { ACTION_ATTR, ACTION_ROOT_SELECTOR, ANTI_ALIAS_TOLERANCE, type ActionBinding, type ActionBindingFinding, type ActionBindingOptions, type ActionBindings, type ActionElement, type ActionReading, 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, POINTER_SELECTOR, PROMPT_ATTR, 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, actionBindingFindings, armVisibleHeight, auditRoute, auditTouchTargets, canvasBoxToPage, controlName, countDiff, desktop, deviceDescriptor, diffPngs, domControls, expectActionsBound, expectCanvasHeight, expectCanvasInside, expectFitTo, expectHookMenuWalkable, expectMenuWalkable, expectNoHorizontalOverflow, expectNoHorizontalOverflowAcrossRoutes, expectTextFits, expectTouchTargets, expectTouchTargetsAcrossRoutes, findOverlaps, findOverlapsWithin, gameProjects, horizontalOverflowPx, measureActionBinding, measureHorizontalOverflow, measureTextFit, overlaps, phone, readActionElements, readHorizontalOverflow, readTextBoxes, regionDiff, renderFindings, renderOverflow, renderRouteAudit, renderWalk, routeProblems, shrinkVisibleHeight, stubGamepad, summariseActionBinding, summariseOverflow, summariseTextFit, summariseTouchTargets, textFitFindings, toActionReading, toOverflowReading, walkFailed, walkHookMenus, walkMenus };
package/dist/index.js CHANGED
@@ -1015,6 +1015,91 @@ async function expectTextFits(page, selector = TEXT_FIT_SELECTOR, options = {})
1015
1015
  return measured;
1016
1016
  }
1017
1017
 
1018
+ // src/action-binding-report.ts
1019
+ function bindingFindings(r, action) {
1020
+ const found = [];
1021
+ if (r.key === null) {
1022
+ found.push({ name: r.name, why: `action ${action} has no key binding` });
1023
+ }
1024
+ if (r.pad === null) {
1025
+ found.push({ name: r.name, why: `action ${action} has no pad binding` });
1026
+ }
1027
+ return found;
1028
+ }
1029
+ function promptFinding(r) {
1030
+ if (r.expectedPromptText === null || r.promptText === r.expectedPromptText) {
1031
+ return null;
1032
+ }
1033
+ if (r.promptText === null) {
1034
+ return { name: r.name, why: `prompt missing: the current binding is "${r.expectedPromptText}" but no visible data-gi-prompt shows it` };
1035
+ }
1036
+ return { name: r.name, why: `prompt shows "${String(r.promptText)}" but the current binding is "${String(r.expectedPromptText)}"` };
1037
+ }
1038
+ function actionBindingFindings(r) {
1039
+ if (r.action === null) {
1040
+ return r.hasPointerHandler ? [{ name: r.name, why: "pointer handler but no data-gi-action" }] : [];
1041
+ }
1042
+ const prompt = promptFinding(r);
1043
+ const bindings = bindingFindings(r, r.action);
1044
+ return prompt === null ? bindings : [...bindings, prompt];
1045
+ }
1046
+ var renderFinding2 = (f) => `
1047
+ ${f.name}: ${f.why}`;
1048
+ function summariseActionBinding(readings, where) {
1049
+ if (readings.length === 0) {
1050
+ return { problems: 1, message: `${where}: BLIND - no clickable or data-gi-action element was read` };
1051
+ }
1052
+ const found = readings.flatMap(actionBindingFindings);
1053
+ const head = `${where}: ${String(readings.length)} element(s), ${String(found.length)} problem(s)`;
1054
+ return { problems: found.length, message: `${head}${found.map(renderFinding2).join("")}` };
1055
+ }
1056
+ var ACTION_ATTR = "data-gi-action";
1057
+ var PROMPT_ATTR = "data-gi-prompt";
1058
+ var POINTER_SELECTOR = 'button, a[href], [role="button"], [onclick]';
1059
+ var ACTION_ROOT_SELECTOR = "body";
1060
+ function toActionReading(el, bindings) {
1061
+ const b = el.action === null ? void 0 : bindings[el.action];
1062
+ return { ...el, key: b?.key ?? null, pad: b?.pad ?? null, expectedPromptText: b?.prompt ?? null };
1063
+ }
1064
+ async function readActionElements(page, root = ACTION_ROOT_SELECTOR, pointerSelector = POINTER_SELECTOR) {
1065
+ return page.evaluate(({ rootSel, pointerSel, actionAttr, promptAttr }) => {
1066
+ const shown = (el) => {
1067
+ const r = el.getBoundingClientRect();
1068
+ return r.width > 0 && r.height > 0 && getComputedStyle(el).visibility !== "hidden" && el.closest('[aria-hidden="true"]') === null;
1069
+ };
1070
+ const label = (el) => {
1071
+ const id = el.id !== "" ? `#${el.id}` : "";
1072
+ const tag = el.getAttribute(actionAttr);
1073
+ const suffix = tag !== null && id === "" ? `[${actionAttr}=${tag}]` : "";
1074
+ return `${el.tagName.toLowerCase()}${id}${suffix}`;
1075
+ };
1076
+ const prompt = (el) => {
1077
+ const p = el.hasAttribute(promptAttr) ? el : el.querySelector(`[${promptAttr}]`);
1078
+ return p !== null && shown(p) ? (p.textContent ?? "").trim() : null;
1079
+ };
1080
+ const roots = [...document.querySelectorAll(rootSel)];
1081
+ const els = new Set(roots.flatMap((r) => [...r.querySelectorAll(`${pointerSel}, [${actionAttr}]`)]));
1082
+ return [...els].filter(shown).map((el) => ({
1083
+ name: label(el),
1084
+ action: el.getAttribute(actionAttr),
1085
+ hasPointerHandler: el.matches(pointerSel),
1086
+ promptText: prompt(el)
1087
+ }));
1088
+ }, { rootSel: root, pointerSel: pointerSelector, actionAttr: ACTION_ATTR, promptAttr: PROMPT_ATTR });
1089
+ }
1090
+ async function measureActionBinding(page, bindings, options = {}) {
1091
+ const els = await readActionElements(page, options.root, options.pointerSelector);
1092
+ return els.map((el) => toActionReading(el, bindings));
1093
+ }
1094
+ async function expectActionsBound(page, bindings, options = {}) {
1095
+ const readings = await measureActionBinding(page, bindings, options);
1096
+ const summary = summariseActionBinding(readings, options.where ?? options.root ?? ACTION_ROOT_SELECTOR);
1097
+ test.expect(summary.problems, summary.message).toBe(0);
1098
+ return readings;
1099
+ }
1100
+
1101
+ exports.ACTION_ATTR = ACTION_ATTR;
1102
+ exports.ACTION_ROOT_SELECTOR = ACTION_ROOT_SELECTOR;
1018
1103
  exports.ANTI_ALIAS_TOLERANCE = ANTI_ALIAS_TOLERANCE;
1019
1104
  exports.CANVAS_TIMEOUT_MS = CANVAS_TIMEOUT_MS;
1020
1105
  exports.CONTROL_SELECTOR = CONTROL_SELECTOR;
@@ -1029,11 +1114,14 @@ exports.MAX_REPORTED = MAX_REPORTED;
1029
1114
  exports.MIN_TARGET_PX = MIN_TARGET_PX;
1030
1115
  exports.PHONE_DEVICE = PHONE_DEVICE;
1031
1116
  exports.PHONE_SIZE = PHONE_SIZE;
1117
+ exports.POINTER_SELECTOR = POINTER_SELECTOR;
1118
+ exports.PROMPT_ATTR = PROMPT_ATTR;
1032
1119
  exports.RELAYOUT_TIMEOUT_MS = RELAYOUT_TIMEOUT_MS;
1033
1120
  exports.STUB_FRAMES = STUB_FRAMES;
1034
1121
  exports.TEXT_FIT_SELECTOR = TEXT_FIT_SELECTOR;
1035
1122
  exports.TEXT_FIT_TOLERANCE_PX = TEXT_FIT_TOLERANCE_PX;
1036
1123
  exports.WALK_INPUTS = WALK_INPUTS;
1124
+ exports.actionBindingFindings = actionBindingFindings;
1037
1125
  exports.armVisibleHeight = armVisibleHeight;
1038
1126
  exports.auditRoute = auditRoute;
1039
1127
  exports.auditTouchTargets = auditTouchTargets;
@@ -1044,6 +1132,7 @@ exports.desktop = desktop;
1044
1132
  exports.deviceDescriptor = deviceDescriptor;
1045
1133
  exports.diffPngs = diffPngs;
1046
1134
  exports.domControls = domControls;
1135
+ exports.expectActionsBound = expectActionsBound;
1047
1136
  exports.expectCanvasHeight = expectCanvasHeight;
1048
1137
  exports.expectCanvasInside = expectCanvasInside;
1049
1138
  exports.expectFitTo = expectFitTo;
@@ -1058,10 +1147,12 @@ exports.findOverlaps = findOverlaps;
1058
1147
  exports.findOverlapsWithin = findOverlapsWithin;
1059
1148
  exports.gameProjects = gameProjects;
1060
1149
  exports.horizontalOverflowPx = horizontalOverflowPx;
1150
+ exports.measureActionBinding = measureActionBinding;
1061
1151
  exports.measureHorizontalOverflow = measureHorizontalOverflow;
1062
1152
  exports.measureTextFit = measureTextFit;
1063
1153
  exports.overlaps = overlaps;
1064
1154
  exports.phone = phone;
1155
+ exports.readActionElements = readActionElements;
1065
1156
  exports.readHorizontalOverflow = readHorizontalOverflow;
1066
1157
  exports.readTextBoxes = readTextBoxes;
1067
1158
  exports.regionDiff = regionDiff;
@@ -1072,10 +1163,12 @@ exports.renderWalk = renderWalk;
1072
1163
  exports.routeProblems = routeProblems;
1073
1164
  exports.shrinkVisibleHeight = shrinkVisibleHeight;
1074
1165
  exports.stubGamepad = stubGamepad;
1166
+ exports.summariseActionBinding = summariseActionBinding;
1075
1167
  exports.summariseOverflow = summariseOverflow;
1076
1168
  exports.summariseTextFit = summariseTextFit;
1077
1169
  exports.summariseTouchTargets = summariseTouchTargets;
1078
1170
  exports.textFitFindings = textFitFindings;
1171
+ exports.toActionReading = toActionReading;
1079
1172
  exports.toOverflowReading = toOverflowReading;
1080
1173
  exports.walkFailed = walkFailed;
1081
1174
  exports.walkHookMenus = walkHookMenus;