@piwitests/reporter 0.68.0 → 0.70.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.
@@ -1,272 +0,0 @@
1
- import { TestInfo, Page } from '@playwright/test';
2
- import { P as ProbeArg, a as ProbedAttrs } from '../../types-CGr9jJZ_.js';
3
- import { RankedLocator, LocatorSnapshot, FailedLocatorInfo } from './locator-healing.js';
4
-
5
- /** The overlay's texts a host may give in its own language; each one left out is the English default. */
6
- interface PickerOverlayStrings {
7
- /** The banner's heading for the `'global'` transport with no failing locator. */
8
- banner?: string;
9
- /** The banner's foot before an element is hovered: the keys, Enter picking the focused element. */
10
- keys?: string;
11
- /** The banner's foot while an element is hovered: a click or Enter picks it. */
12
- keysHovering?: string;
13
- /** The banner's foot once an element is picked. */
14
- analyzing?: string;
15
- }
16
- /** Configuration for `installPickerOverlay` — see the function doc for the transport split. */
17
- interface PickerOverlayArg {
18
- transport: 'global' | 'postMessage';
19
- /** Rendered failing locator for the banner heading (`'global'` transport only). */
20
- failing?: string | null;
21
- /** Probe arguments for the inline probe the `'postMessage'` transport performs on pick. */
22
- probeArg?: ProbeArg;
23
- /** The banner's texts, for a host that shows another language than English. */
24
- strings?: PickerOverlayStrings;
25
- /**
26
- * The attribute `getByTestId` reads in the project (Playwright's
27
- * `testIdAttribute`); `data-testid` when null or absent. The overlay's own
28
- * description of an element and its snapping to a test id read it.
29
- */
30
- testIdAttribute?: string | null;
31
- }
32
- /**
33
- * Runs inside the browser — installs the element-picking overlay: a hover
34
- * highlight, an instruction banner, and capture-phase listeners that suppress
35
- * the app's own handlers while picking. The hover target snaps to the nearest
36
- * actionable ancestor (button/link/field/role/test id) and up/down walk the
37
- * DOM chain before the click commits. The hover reaches into open shadow
38
- * roots, and the chain walks out of them through each host. Enter picks the
39
- * outlined element, or with none the focused one, so a control reached with
40
- * Tab is picked without the pointer.
41
- *
42
- * `transport` picks how a pick/skip is reported, since the two hosts cross
43
- * fundamentally different boundaries:
44
- * - `'global'` — the reporter drives a live page from Node over CDP. The
45
- * picked element is parked on `globalThis.__piwiPickedElement` and
46
- * `__piwiPickState` is set to `'picked'`/`'skipped'`, polled from Node;
47
- * probing happens later, from Node, against a live element handle.
48
- * - `'postMessage'` — the snapshot picker runs standalone inside a sandboxed
49
- * opaque-origin iframe with nothing outside able to reach in, so the pick
50
- * is probed and posted to `window.parent` in the same tick. The probe
51
- * itself can't be imported (a serialized function carries no imports), so
52
- * the embedding host installs it on `globalThis.__piwiProbe` before
53
- * invoking this function, and may install lifecycle hooks on
54
- * `globalThis.__piwiSnapshotExtras` (`onPick`/`onClose`) for its own
55
- * snapshot-only chrome (search, highlight hints, extended inertness).
56
- *
57
- * The banner is in English unless `arg.strings` gives its texts.
58
- *
59
- * The hovered element's locator is shown twice — in a chip pinned to the
60
- * element itself and on its own line in the banner. Both render whatever
61
- * `globalThis.__piwiDescribeElement(el)` returns when a host installs one (the
62
- * extension points it at the real ranked locator engine), falling back to this
63
- * function's own attribute-order approximation. A host whose answer improves
64
- * later (checked against the page once the pointer rests) calls
65
- * `globalThis.__piwiRedescribe()` to have the hovered element described again.
66
- *
67
- * Must stay fully self-contained (no module-closure references) — both hosts
68
- * re-serialize this function via `Function.prototype.toString()` (the
69
- * reporter through `page.evaluate`, the snapshot picker through `String()`
70
- * into a `<script>` tag).
71
- */
72
- declare function installPickerOverlay(arg: PickerOverlayArg): void;
73
-
74
- /** An ancestor the human blessed as an anchor, with its in-page uniqueness counts. */
75
- interface PickedAnchorInfo {
76
- tag: string;
77
- /** Hops from the picked element (1 = direct parent). */
78
- depth: number;
79
- testId: string | null;
80
- id: string | null;
81
- ariaLabel: string | null;
82
- /** Resolved anchor role (explicit attribute or tag-implied). */
83
- role: string | null;
84
- /** Document-wide match count for the anchor's own test id. */
85
- testIdCount?: number;
86
- /** Document-wide match count for the anchor's own id. */
87
- idCount?: number;
88
- /** Document-wide count of same-role elements carrying the same aria-label. */
89
- labeledRoleCount?: number;
90
- /** Document-wide count of elements resolving to the anchor's role. */
91
- roleCount?: number;
92
- /** Leaf matches (picked element's identity) within this anchor's subtree. */
93
- scopedLeafCount?: number;
94
- }
95
- /** The picked element's identity used for anchor-scoped candidates. */
96
- interface PickedLeafInfo {
97
- role: string | null;
98
- level: number | null;
99
- }
100
- /**
101
- * The anchors step's texts a host may give in its own language; each one left
102
- * out is the English default. `{count}` in a text stands for a number.
103
- */
104
- interface AnchorPickerStrings {
105
- title?: string;
106
- hint?: string;
107
- /** The footer with no parent selected. */
108
- noneSelected?: string;
109
- matchesOne?: string;
110
- /** `{count}` elements, any count but one. */
111
- matchesMany?: string;
112
- countUnavailable?: string;
113
- /** Under a parent: what it contains. */
114
- containsOne?: string;
115
- containsMany?: string;
116
- /** Under a parent that cannot be selected. */
117
- needsTestId?: string;
118
- /** A parent with no test id, id or role, in place of its hook. */
119
- noHook?: string;
120
- use?: string;
121
- skip?: string;
122
- }
123
- /** Arguments for `showAnchorPicker` — the role maps mirror the single source of truth in `@piwitests/core`. */
124
- interface AnchorPickerArg {
125
- tagRoles: Record<string, string>;
126
- inputRoles: Record<string, string>;
127
- roleSources: string;
128
- leafRole: string;
129
- leafLevel: number | null;
130
- leafTestId: string | null;
131
- /**
132
- * The attribute `getByTestId` reads in the project (Playwright's
133
- * `testIdAttribute`), which `leafTestId` and each parent's test id are read
134
- * from; `data-testid` when null or absent.
135
- */
136
- testIdAttribute?: string | null;
137
- /** The panel's texts, for a host that shows another language than English. */
138
- strings?: AnchorPickerStrings;
139
- }
140
- /**
141
- * Runs inside the browser via `evaluate()` — the anchor step: lists the picked
142
- * element's ancestors so the human can bless one or more stable parents to
143
- * scope the locator to. Each row shows the ancestor's strongest hook and how
144
- * many leaf matches it contains; the footer shows a live "matches N" count for
145
- * the combined selection, recomputed against the real page on every toggle
146
- * (exactly 1 = green). Hovering a row outlines that ancestor in the page and
147
- * names it in a chip pinned to it. Resolves through `__piwiAnchorState` ('done' | 'skipped'); selected anchors
148
- * land in `__piwiPickAnchors` (+ `__piwiPickChainCount`). While the step
149
- * shows, `__piwiAnchorCleanup` holds its teardown (see `removeAnchorPicker`).
150
- * Role resolution reuses the maps passed in `arg` (single source of truth in
151
- * `@piwitests/core`). The ancestors and every count reach through open shadow
152
- * roots, as Playwright's locators do. The panel is in English unless
153
- * `arg.strings` gives its texts. Must stay fully self-contained.
154
- */
155
- declare function showAnchorPicker(arg: AnchorPickerArg): void;
156
-
157
- /** Arguments for `showPickerChoices`. */
158
- interface PickerChoicesArg {
159
- failing: string | null;
160
- choices: Array<{
161
- locator: string;
162
- score: number;
163
- }>;
164
- }
165
- /**
166
- * Runs inside the browser via `evaluate()` — replaces the pick overlay with a
167
- * confirmation panel listing the ranked replacement locators. The chosen index
168
- * lands in `__piwiPickChoice` (-1 = skipped), polled from Node. While it shows,
169
- * `__piwiChoiceCleanup` takes it out of the page unanswered (a pick that ended
170
- * under it). Must stay fully self-contained.
171
- */
172
- declare function showPickerChoices(arg: PickerChoicesArg): void;
173
-
174
- /**
175
- * Build anchor-scoped candidates from the human-blessed parents. Shapes stay
176
- * consistent with the heuristic chains in `generateAlternatives` — leaf method
177
- * `getByRole` with flat anchor args, no leaf `name` key. Single-anchor
178
- * candidates require the leaf to be unique inside that anchor; with two or
179
- * more anchors a combined chain is added when the whole chain resolves to
180
- * exactly one element (`chainLeafCount`). Pure — exported for tests.
181
- */
182
- declare function generateAnchoredAlternatives(leaf: PickedLeafInfo, anchors: PickedAnchorInfo[], chainLeafCount?: number): RankedLocator[];
183
- /** Merge candidate lists, first list winning duplicates, sorted by score. Exported for tests. */
184
- declare function mergeCandidates(base: RankedLocator[], extra: RankedLocator[]): RankedLocator[];
185
-
186
- /**
187
- * The probe dependency, passed in by the capture fixture to avoid an import
188
- * cycle. `fn` is the fixture's in-page element probe (`probeElementAttrs`);
189
- * `el` is a browser-side element, hence `any` (no DOM lib in this package).
190
- */
191
- interface PickerProbe {
192
- fn: (el: any, arg: ProbeArg) => ProbedAttrs;
193
- arg: ProbeArg;
194
- }
195
- /** A confirmed pick — everything the fixture records about the human's choice. */
196
- interface UserPickResult {
197
- /**
198
- * The locator this pick replaces. Null when the overlay was opened purely to
199
- * inspect (`inspectOnFailure` with no identifiable failing locator) — the
200
- * pick still yields alternatives, but there is nothing to write back to.
201
- */
202
- failing: {
203
- method: string;
204
- args: unknown[];
205
- /** The failed locator rendered as source, e.g. `getByText('Pay now')`. */
206
- rendered: string;
207
- /** Test call site (`file:line:col`) of the failed action, when captured. */
208
- location: string | null;
209
- } | null;
210
- /** The alternative the human confirmed (also first in `alternatives`). */
211
- picked: RankedLocator;
212
- /** Full ranked list for the picked element, the confirmed pick first. */
213
- alternatives: RankedLocator[];
214
- /** Wire-shaped element snapshot of the picked element. */
215
- element: NonNullable<LocatorSnapshot['element']>;
216
- /** Stable parents the human blessed in the anchor step, when any. */
217
- anchors?: PickedAnchorInfo[];
218
- }
219
- /**
220
- * Parse a Playwright locator expression into `{ method, args }` for its leaf —
221
- * the last locating call, which identifies the resolved element, mirroring the
222
- * server's `extractLeafSelector`. Exported for tests.
223
- */
224
- declare function parseLeafLocatorExpression(rawExpr: string): {
225
- method: string;
226
- args: unknown[];
227
- } | null;
228
- /**
229
- * Derive the failing locator + call site from a test's error(s) when no locator
230
- * action was captured (an `expect(...)` assertion failure). Reads the
231
- * `Locator: …` line Playwright prints and the error's own call location,
232
- * normalized cwd-relative to match captured snapshot locations. Returns null
233
- * when no locator can be identified. Exported for tests.
234
- */
235
- declare function deriveFailedLocator(testInfo: TestInfo): FailedLocatorInfo | null;
236
- /** What the element → anchors → confirm flow yields: the confirmed locator, its alternatives and the element. */
237
- type PickedLocator = Omit<UserPickResult, 'failing'>;
238
- /** `run`, or undefined as soon as `ended` aborts; `run` itself is left to settle on its own. */
239
- declare function unlessEnded<T>(run: Promise<T>, ended: AbortSignal | undefined): Promise<T | undefined>;
240
- /**
241
- * Run the element → anchors → confirm flow on a live page: element pick (snap
242
- * + tree-walk), optional stable-parent anchoring with live match counts, ranked
243
- * candidates (standard generation merged with anchor-scoped chains), and a
244
- * final confirmation. `failing` is the locator the pick replaces, rendered, for
245
- * the overlay's headings; null to pick any element. Returns null when the
246
- * human skips, no locator could be generated or `ended` aborts, the overlay
247
- * then taken out of the page; throws when the page breaks.
248
- */
249
- declare function pickLocator(page: Page, probe: PickerProbe, failing: string | null, ended?: AbortSignal): Promise<PickedLocator | null>;
250
- /**
251
- * Drive the full pick flow on the failing page (`pickLocator`), the test
252
- * timeout lifted while waiting. Returns null when skipped or when anything
253
- * breaks — the picker must never mask the test's own failure.
254
- */
255
- declare function runLocatorPicker(page: Page, testInfo: TestInfo, failed: FailedLocatorInfo | null, probe: PickerProbe): Promise<UserPickResult | null>;
256
- /**
257
- * Fold a confirmed pick into the captured snapshots: the failed action's
258
- * placeholder (same call site, no element — capture never probes an action
259
- * that threw) is filled with the picked element and the confirmed-first
260
- * alternative list, so the pick rides the normal `piwi-locators` attachment
261
- * into the dashboard's `locator_snapshots` and healing panel.
262
- *
263
- * A failed locator *action* left a placeholder at its call site (same location,
264
- * no element) — that placeholder is filled in place. An assertion failure left
265
- * no placeholder (no action ran), so a fresh snapshot is appended under the
266
- * failing locator's location and signature instead, so the pick still reaches
267
- * `locator_snapshots`. No-op only when the failing locator has no location.
268
- * Exported for tests.
269
- */
270
- declare function applyPickToSnapshots(snapshots: LocatorSnapshot[], pick: UserPickResult): boolean;
271
-
272
- export { type PickedAnchorInfo, type PickedLeafInfo, type PickedLocator, type PickerProbe, type UserPickResult, applyPickToSnapshots, deriveFailedLocator, generateAnchoredAlternatives, installPickerOverlay, mergeCandidates, parseLeafLocatorExpression, pickLocator, runLocatorPicker, showAnchorPicker, showPickerChoices, unlessEnded };