@dloizides/game-e2e 0.0.0-stage → 1.1.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 +33 -0
- package/LICENSE +21 -0
- package/README.md +115 -2
- package/dist/index.d.mts +258 -0
- package/dist/index.d.ts +258 -0
- package/dist/index.js +713 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +657 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +81 -4
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
import { Page, BrowserContextOptions } from '@playwright/test';
|
|
2
|
+
|
|
3
|
+
interface Box {
|
|
4
|
+
name: string;
|
|
5
|
+
left: number;
|
|
6
|
+
top: number;
|
|
7
|
+
right: number;
|
|
8
|
+
bottom: number;
|
|
9
|
+
}
|
|
10
|
+
interface Region {
|
|
11
|
+
readonly x: number;
|
|
12
|
+
readonly y: number;
|
|
13
|
+
readonly w: number;
|
|
14
|
+
readonly h: number;
|
|
15
|
+
}
|
|
16
|
+
interface Rect {
|
|
17
|
+
x: number;
|
|
18
|
+
y: number;
|
|
19
|
+
width: number;
|
|
20
|
+
height: number;
|
|
21
|
+
}
|
|
22
|
+
/** Anything that opens a scratch page: a `Browser` or a `BrowserContext` (e.g. `page.context()`). */
|
|
23
|
+
interface PageFactory {
|
|
24
|
+
newPage(): Promise<Page>;
|
|
25
|
+
}
|
|
26
|
+
/** The outcome of a whole-portal gate: zero problems passes, the message carries the per-route breakdown. */
|
|
27
|
+
interface GateSummary {
|
|
28
|
+
problems: number;
|
|
29
|
+
message: string;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
interface CanvasFrame {
|
|
33
|
+
left: number;
|
|
34
|
+
top: number;
|
|
35
|
+
width: number;
|
|
36
|
+
logicalWidth: number;
|
|
37
|
+
}
|
|
38
|
+
interface ControlIdentity {
|
|
39
|
+
tag: string;
|
|
40
|
+
id: string;
|
|
41
|
+
className: string;
|
|
42
|
+
text: string;
|
|
43
|
+
}
|
|
44
|
+
type Band = readonly [number, number];
|
|
45
|
+
declare function overlaps(a: Box, b: Box): boolean;
|
|
46
|
+
/** Every overlapping (a, b) pair across two lists; an element never overlaps itself. */
|
|
47
|
+
declare function findOverlaps(a: readonly Box[], b: readonly Box[]): Array<[Box, Box]>;
|
|
48
|
+
/** Every overlapping pair inside one list, each pair reported once. */
|
|
49
|
+
declare function findOverlapsWithin(boxes: readonly Box[]): Array<[Box, Box]>;
|
|
50
|
+
/** Maps a game-space rect onto the page in CSS px, clipped to a scroll band; null when nothing is left. */
|
|
51
|
+
declare function canvasBoxToPage(frame: CanvasFrame, bounds: Rect, name: string, band?: Band): Box | null;
|
|
52
|
+
declare function controlName(c: ControlIdentity): string;
|
|
53
|
+
|
|
54
|
+
interface Size {
|
|
55
|
+
width: number;
|
|
56
|
+
height: number;
|
|
57
|
+
}
|
|
58
|
+
interface GameProject {
|
|
59
|
+
name: string;
|
|
60
|
+
use: BrowserContextOptions;
|
|
61
|
+
}
|
|
62
|
+
interface GameProjectsOptions {
|
|
63
|
+
phone?: Size;
|
|
64
|
+
desktop?: Size;
|
|
65
|
+
phoneName?: string;
|
|
66
|
+
desktopName?: string;
|
|
67
|
+
}
|
|
68
|
+
declare const PHONE_DEVICE = "Galaxy S5";
|
|
69
|
+
declare const DESKTOP_DEVICE = "Desktop Chrome";
|
|
70
|
+
declare const PHONE_SIZE: Size;
|
|
71
|
+
declare const DESKTOP_SIZE: Size;
|
|
72
|
+
/** A Playwright device descriptor without `defaultBrowserType`, so it can sit inside any project's `use`. */
|
|
73
|
+
declare function deviceDescriptor(name: string): BrowserContextOptions;
|
|
74
|
+
/** A touch phone (Galaxy S5 descriptor: mobile UA, touch, isMobile) resized to width x height. */
|
|
75
|
+
declare function phone(width?: number, height?: number, deviceScaleFactor?: number): BrowserContextOptions;
|
|
76
|
+
/** A Desktop Chrome descriptor resized to width x height, scale factor 1 unless given. */
|
|
77
|
+
declare function desktop(width?: number, height?: number, deviceScaleFactor?: number): BrowserContextOptions;
|
|
78
|
+
/** The phone + desktop Playwright projects every game runs its specs under. */
|
|
79
|
+
declare function gameProjects(options?: GameProjectsOptions): GameProject[];
|
|
80
|
+
|
|
81
|
+
interface ShrinkOptions {
|
|
82
|
+
relayoutGlobal?: string;
|
|
83
|
+
timeout?: number;
|
|
84
|
+
}
|
|
85
|
+
declare const RELAYOUT_TIMEOUT_MS = 15000;
|
|
86
|
+
/** Replaces visualViewport.height before page scripts run: reads window.__gfVisibleHeight, else innerHeight. */
|
|
87
|
+
declare function armVisibleHeight(page: Page): Promise<void>;
|
|
88
|
+
/** Drops the visible height and fires visualViewport resize; with `relayoutGlobal`, waits for every active Phaser scene to re-create. */
|
|
89
|
+
declare function shrinkVisibleHeight(page: Page, height: number, options?: ShrinkOptions): Promise<void>;
|
|
90
|
+
|
|
91
|
+
interface FitOptions {
|
|
92
|
+
cssVar?: string;
|
|
93
|
+
timeout?: number;
|
|
94
|
+
}
|
|
95
|
+
interface CanvasOptions {
|
|
96
|
+
canvasSelector?: string;
|
|
97
|
+
timeout?: number;
|
|
98
|
+
}
|
|
99
|
+
declare const GAME_SHELL_HEIGHT_VAR = "--gs-vh";
|
|
100
|
+
declare const DEFAULT_CANVAS_SELECTOR = "canvas";
|
|
101
|
+
declare const FIT_TIMEOUT_MS = 10000;
|
|
102
|
+
declare const CANVAS_TIMEOUT_MS = 15000;
|
|
103
|
+
/** Waits until the game-shell height variable on :root equals `height` px. */
|
|
104
|
+
declare function expectFitTo(page: Page, height: number, options?: FitOptions): Promise<void>;
|
|
105
|
+
/** Waits for the canvas to follow its container to exactly `height` CSS px. */
|
|
106
|
+
declare function expectCanvasHeight(page: Page, height: number, options?: CanvasOptions): Promise<void>;
|
|
107
|
+
/** Waits until the canvas bottom sits inside the visible `height` (a FIT-scaled canvas may be shorter). */
|
|
108
|
+
declare function expectCanvasInside(page: Page, height: number, options?: CanvasOptions): Promise<void>;
|
|
109
|
+
|
|
110
|
+
declare const CONTROL_SELECTOR = "button, a[href], [role=\"button\"]";
|
|
111
|
+
/** Visible, interactive DOM controls as CSS-px boxes, named tag#id or tag.class plus their text. */
|
|
112
|
+
declare function domControls(page: Page, selector?: string): Promise<Box[]>;
|
|
113
|
+
|
|
114
|
+
declare const EXACT = 0;
|
|
115
|
+
declare const ANTI_ALIAS_TOLERANCE = 48;
|
|
116
|
+
interface DiffResult {
|
|
117
|
+
differing: number;
|
|
118
|
+
total: number;
|
|
119
|
+
ratio: number;
|
|
120
|
+
bbox: string;
|
|
121
|
+
}
|
|
122
|
+
/** Counts RGBA pixels whose largest RGB channel delta exceeds `tolerance` (0 = any change), with their bounding box. */
|
|
123
|
+
declare function countDiff(a: ArrayLike<number>, b: ArrayLike<number>, width: number, tolerance?: number): DiffResult;
|
|
124
|
+
|
|
125
|
+
interface DiffOptions {
|
|
126
|
+
tolerance?: number;
|
|
127
|
+
width?: number;
|
|
128
|
+
height?: number;
|
|
129
|
+
regionA?: Region | null;
|
|
130
|
+
regionB?: Region | null;
|
|
131
|
+
}
|
|
132
|
+
interface RegionInput {
|
|
133
|
+
png: Buffer;
|
|
134
|
+
region: Region | null;
|
|
135
|
+
}
|
|
136
|
+
/** Decodes two PNGs in a scratch page and counts differing pixels; exact and same-size unless options say otherwise. */
|
|
137
|
+
declare function diffPngs(factory: PageFactory, a: Buffer, b: Buffer, options?: DiffOptions): Promise<DiffResult>;
|
|
138
|
+
/** Diffs a region of PNG a against a region of PNG b (null = whole image), both drawn at the same size. */
|
|
139
|
+
declare function regionDiff(factory: PageFactory, a: RegionInput, b: RegionInput, options?: Omit<DiffOptions, 'regionA' | 'regionB'>): Promise<DiffResult>;
|
|
140
|
+
|
|
141
|
+
declare const MIN_TARGET_PX = 44;
|
|
142
|
+
declare const MAX_REPORTED = 12;
|
|
143
|
+
interface TargetFinding {
|
|
144
|
+
idx: number;
|
|
145
|
+
selector: string;
|
|
146
|
+
width: number;
|
|
147
|
+
height: number;
|
|
148
|
+
reason: string;
|
|
149
|
+
name: string;
|
|
150
|
+
}
|
|
151
|
+
interface TargetProbeFunnel {
|
|
152
|
+
raw: number;
|
|
153
|
+
afterWrapper: number;
|
|
154
|
+
kept: number;
|
|
155
|
+
}
|
|
156
|
+
/** One route's touch-target reading; `probe` makes a zero attributable (raw -> afterWrapper -> kept -> total). */
|
|
157
|
+
interface TargetAudit {
|
|
158
|
+
total: number;
|
|
159
|
+
undersized: TargetFinding[];
|
|
160
|
+
unlabelled: TargetFinding[];
|
|
161
|
+
probe: TargetProbeFunnel;
|
|
162
|
+
}
|
|
163
|
+
/** One route's reading. `total === 0` is a broken probe for that route, never a clean route. */
|
|
164
|
+
interface RouteAudit {
|
|
165
|
+
route: string;
|
|
166
|
+
audit: TargetAudit;
|
|
167
|
+
}
|
|
168
|
+
declare function renderFindings(findings: readonly TargetFinding[], alsoIn: ReadonlySet<number>, alsoLabel: string): string;
|
|
169
|
+
declare function renderRouteAudit({ route, audit }: RouteAudit, minPx: number): string;
|
|
170
|
+
declare function routeProblems({ audit }: RouteAudit): number;
|
|
171
|
+
/** Folds every route and both claims (size, label) into one tally; no routes at all is itself a problem. */
|
|
172
|
+
declare function summariseTouchTargets(readings: readonly RouteAudit[], portal: string, minPx?: number): GateSummary;
|
|
173
|
+
|
|
174
|
+
/** Measures every reachable pressable on the page (role OR handler OR own-origin pointer cursor, outermost wins) against `minPx`. */
|
|
175
|
+
declare function auditTouchTargets(page: Page, minPx?: number): Promise<TargetAudit>;
|
|
176
|
+
/** Measures one route and asserts nothing, so a route with findings cannot hide the routes after it. */
|
|
177
|
+
declare function auditRoute(page: Page, route: string, minPx?: number): Promise<RouteAudit>;
|
|
178
|
+
/** ONE assertion per portal over every route and both claims (undersized, unlabelled); a zero-target route fails. */
|
|
179
|
+
declare function expectTouchTargetsAcrossRoutes(readings: readonly RouteAudit[], portal: string, minPx?: number): void;
|
|
180
|
+
/** Single-route convenience over `expectTouchTargetsAcrossRoutes`. */
|
|
181
|
+
declare function expectTouchTargets(page: Page, where: string, minPx?: number): Promise<TargetAudit>;
|
|
182
|
+
|
|
183
|
+
interface OverflowMetrics {
|
|
184
|
+
scrollWidth: number;
|
|
185
|
+
visualViewportWidth: number;
|
|
186
|
+
innerWidth: number;
|
|
187
|
+
clientWidth: number;
|
|
188
|
+
}
|
|
189
|
+
/** `layoutViewportDrift` (innerWidth above visualViewport) is the signature of a widened layout viewport. */
|
|
190
|
+
interface OverflowReading extends OverflowMetrics {
|
|
191
|
+
overflowPx: number;
|
|
192
|
+
layoutViewportDrift: number;
|
|
193
|
+
}
|
|
194
|
+
interface RouteOverflow {
|
|
195
|
+
route: string;
|
|
196
|
+
reading: OverflowReading;
|
|
197
|
+
}
|
|
198
|
+
/** Overflow against the NARROWER of visualViewport width and clientWidth, never innerWidth (which widens with the defect). */
|
|
199
|
+
declare function toOverflowReading(m: OverflowMetrics): OverflowReading;
|
|
200
|
+
declare function renderOverflow({ route, reading: r }: RouteOverflow): string;
|
|
201
|
+
/** Folds every route into one tally of routes that scroll sideways; no routes at all is itself a problem. */
|
|
202
|
+
declare function summariseOverflow(readings: readonly RouteOverflow[], portal: string): GateSummary;
|
|
203
|
+
|
|
204
|
+
declare function readHorizontalOverflow(page: Page): Promise<OverflowReading>;
|
|
205
|
+
/** Measures one route and asserts nothing. */
|
|
206
|
+
declare function measureHorizontalOverflow(page: Page, route: string): Promise<RouteOverflow>;
|
|
207
|
+
/** Pixels the document scrolls sideways past the visible width (<= 0 means no horizontal scroll). */
|
|
208
|
+
declare function horizontalOverflowPx(page: Page): Promise<number>;
|
|
209
|
+
/** ONE assertion per portal over every route, so the first overflowing route cannot hide the rest. */
|
|
210
|
+
declare function expectNoHorizontalOverflowAcrossRoutes(readings: readonly RouteOverflow[], portal: string): void;
|
|
211
|
+
/** Single-route convenience over `expectNoHorizontalOverflowAcrossRoutes`. */
|
|
212
|
+
declare function expectNoHorizontalOverflow(page: Page, where: string): Promise<OverflowReading>;
|
|
213
|
+
|
|
214
|
+
declare const WALK_INPUTS: {
|
|
215
|
+
readonly keys: "keys";
|
|
216
|
+
readonly pad: "pad";
|
|
217
|
+
};
|
|
218
|
+
type WalkInput = (typeof WALK_INPUTS)[keyof typeof WALK_INPUTS];
|
|
219
|
+
interface WalkResult {
|
|
220
|
+
screen: string;
|
|
221
|
+
via: WalkInput;
|
|
222
|
+
reached: number;
|
|
223
|
+
total: number;
|
|
224
|
+
unreached: string[];
|
|
225
|
+
problems: string[];
|
|
226
|
+
exempt: string[];
|
|
227
|
+
}
|
|
228
|
+
declare const walkFailed: (r: WalkResult) => boolean;
|
|
229
|
+
/** One block per screen and input: reached/total, then every unreached control, problem and exemption. */
|
|
230
|
+
declare function renderWalk(results: readonly WalkResult[]): string;
|
|
231
|
+
|
|
232
|
+
interface WalkScreen {
|
|
233
|
+
name: string;
|
|
234
|
+
/** Opens the screen from a fresh page (clicks, a URL, a test hook). */
|
|
235
|
+
open: (page: Page) => Promise<void>;
|
|
236
|
+
/** Controls deliberately not walkable, each with a reason (printed in the report). */
|
|
237
|
+
exempt?: ReadonlyArray<{
|
|
238
|
+
selector: string;
|
|
239
|
+
reason: string;
|
|
240
|
+
}>;
|
|
241
|
+
}
|
|
242
|
+
interface WalkOptions {
|
|
243
|
+
via?: readonly WalkInput[];
|
|
244
|
+
}
|
|
245
|
+
/** Walks every screen by arrow keys and by a stubbed pad (default both) and returns one result per screen and input. */
|
|
246
|
+
declare function walkMenus(page: Page, screens: readonly WalkScreen[], options?: WalkOptions): Promise<WalkResult[]>;
|
|
247
|
+
/** NAV-1 gate: throws, listing every unreached control and problem, unless every screen walks by keys and pad. */
|
|
248
|
+
declare function expectMenuWalkable(page: Page, screens: readonly WalkScreen[], options?: WalkOptions): Promise<void>;
|
|
249
|
+
|
|
250
|
+
interface PadDriver {
|
|
251
|
+
press(button: number): Promise<void>;
|
|
252
|
+
hold(axis: number, value: number): Promise<void>;
|
|
253
|
+
}
|
|
254
|
+
declare const STUB_FRAMES = 3;
|
|
255
|
+
/** Replaces navigator.getGamepads with one standard pad (call before the page loads); returns its driver. */
|
|
256
|
+
declare function stubGamepad(page: Page): Promise<PadDriver>;
|
|
257
|
+
|
|
258
|
+
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, 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 TargetAudit, type TargetFinding, type TargetProbeFunnel, WALK_INPUTS, type WalkInput, type WalkOptions, type WalkResult, type WalkScreen, armVisibleHeight, auditRoute, auditTouchTargets, canvasBoxToPage, controlName, countDiff, desktop, deviceDescriptor, diffPngs, domControls, expectCanvasHeight, expectCanvasInside, expectFitTo, expectMenuWalkable, expectNoHorizontalOverflow, expectNoHorizontalOverflowAcrossRoutes, expectTouchTargets, expectTouchTargetsAcrossRoutes, findOverlaps, findOverlapsWithin, gameProjects, horizontalOverflowPx, measureHorizontalOverflow, overlaps, phone, readHorizontalOverflow, regionDiff, renderFindings, renderOverflow, renderRouteAudit, renderWalk, routeProblems, shrinkVisibleHeight, stubGamepad, summariseOverflow, summariseTouchTargets, toOverflowReading, walkFailed, walkMenus };
|