@piwitests/reporter 0.62.0 → 0.64.0

package/dist/internal/capture/locator-healing.d.ts

@@ -1,6 +1,214 @@
-export { CAPTURED_ATTRIBUTES, INPUT_TYPE_TO_ROLE, TAG_TO_ROLE, approximateAccessibleName, classifyCssStability, generateAlternatives, headingLevel, isAutoGenerated, resolveAriaRole } from '@piwitests/core/locator-generation';
-import { LocatorSnapshot } from '@piwitests/core/locator-healing-types';
-export { AncestorAnchor, ElementAttributes, LocatorSnapshot, RankedLocator, RolePosition, SelectorCounts } from '@piwitests/core/locator-healing-types';
+/**
+ * Shared types for locator healing — the in-runtime capture + storage of
+ * alternative locators for every element interaction.
+ *
+ * The single source of truth: the dashboard app re-exports these via
+ * `#shared/locator-healing.types`, and the reporter bundles them at build time.
+ */
+/** A ranked alternative locator suggestion. */
+interface RankedLocator {
+    locator: string;
+    method: string;
+    args: Record<string, unknown>;
+    /** 0-100 stability score. data-testid=100, semantic CSS=35-40, hash-suffixed=10. */
+    score: number;
+    /**
+     * True when a human confirmed this alternative in the reporter's
+     * failure-time locator picker (`pickLocatorOnFailure`). A confirmed pick is
+     * surfaced distinctly and preferred as the recommended fix.
+     */
+    pickedByUser?: boolean;
+    /** When the pick was saved from the dashboard's snapshot picker, ISO 8601. */
+    pickedAt?: string;
+}
+/**
+ * Match counts for candidate selectors, probed against the live DOM at capture
+ * time. A count > 1 marks the selector ambiguous (strict-mode violation).
+ */
+interface SelectorCounts {
+    testId?: number;
+    id?: number;
+    name?: number;
+    classes?: Record<string, number>;
+    /** How many elements share this element's role *and* exact accessible name (`getByRole(role, { name })` without `exact` also matches names that contain it). Absent when unknown (an older capture, or a probe run without the structural pass). */
+    roleName?: number;
+    /** Of the `roleName` matches, how many are visible (a laid-out box, or an `offsetParent`) — what `getByRole(role, { name }).visible()` would match. Absent when unknown. */
+    visibleRoleName?: number;
+    /** How many elements `getByText` would match on this element's text, counted no further than 2. Absent when unknown. */
+    text?: number;
+    /** How many elements share this element's `placeholder` — what `getByPlaceholder` would really match. Absent when unknown. */
+    placeholder?: number;
+    /** How many elements share this element's `alt` — what `getByAltText` would really match. Absent when unknown. */
+    alt?: number;
+    /** How many elements share this element's `title` — what `getByTitle` would really match. Absent when unknown. */
+    title?: number;
+}
+/**
+ * The element's position among same-role elements in the document at capture
+ * time — a name-independent structural identity used to re-find a renamed
+ * element on the failing page.
+ */
+interface RolePosition {
+    role: string;
+    /** How many elements resolved to this role, document-wide. */
+    count: number;
+    /** The captured element's 0-based index among them, in document order. */
+    index: number;
+    /** For headings: how many same-role elements share this element's level. */
+    levelCount?: number;
+}
+/**
+ * An anchor-worthy ancestor of the captured element — one carrying a stable
+ * hook (test id, id, explicit role, aria-label, or a landmark tag) that a
+ * scoped alternative locator can chain from. Nearest ancestors first.
+ */
+interface AncestorAnchor {
+    tag: string;
+    /** Hops from the element (1 = direct parent). */
+    depth: number;
+    testId: string | null;
+    id: string | null;
+    /** Explicit role attribute, if any. */
+    role: string | null;
+    ariaLabel: string | null;
+    /** Same-role matches for the captured element within this ancestor. */
+    scopedRoleCount?: number;
+    /**
+     * Matches for the captured element's text within this ancestor. A role-less
+     * leaf (a price `<span>`, a status badge) has no role to scope, so this is
+     * what tells a chain that resolves to one element from one that does not.
+     */
+    scopedTextCount?: number;
+    /** Document-wide match count for this ancestor's own data-testid. */
+    testIdCount?: number;
+    /** Document-wide match count for this ancestor's own id. */
+    idCount?: number;
+    /** Document-wide count of elements resolving to this ancestor's landmark/explicit role. */
+    roleCount?: number;
+    /**
+     * A stable non-testid `data-*` hook on this ancestor (`data-product="43"`,
+     * `data-row-id="7"`). Many apps identify a repeated card or row this way and
+     * nothing else, so without it the only locator left is one that matches every
+     * card on the page.
+     */
+    dataAttr?: {
+        name: string;
+        value: string;
+    };
+    /** Document-wide match count for `dataAttr` as an attribute selector. */
+    dataAttrCount?: number;
+    /**
+     * Text inside this ancestor that tells it apart from its same-role siblings —
+     * the product name in a card, the customer name in a table row. A repeated
+     * container carries no unique hook of its own, so this is what makes
+     * `getByRole('listitem').filter({ hasText: 'Keyboard' })` land on one of them.
+     */
+    filterText?: string;
+    /** How many elements of this ancestor's role contain `filterText`. */
+    filterRoleCount?: number;
+}
+/** Raw element attributes captured after a successful action. */
+interface ElementAttributes {
+    tagName: string;
+    attributes: Record<string, string | null>;
+    /** Visible text, truncated to 80 chars. */
+    textContent: string | null;
+    /** Browser-computed accessible name from ariaSnapshot(). */
+    accessibleName: string | null;
+    /** Center point of the element's bounding box — spatial discriminator. */
+    center: {
+        x: number;
+        y: number;
+    } | null;
+    /** True when the element has an associated <label> — gates getByLabel. */
+    hasLabel?: boolean;
+    /** Text of the elements `aria-labelledby` points at, else of the first associated `<label>` — what names a form field. Absent when the probe did not read it. */
+    labelText?: string | null;
+    /** Live-page uniqueness probe results for candidate selectors. */
+    selectorCounts?: SelectorCounts;
+    /** Position among same-role elements — powers name-free and renamed-element healing. */
+    rolePosition?: RolePosition | null;
+    /** Anchor-worthy ancestors, nearest first — power ancestor-scoped alternatives. */
+    ancestors?: AncestorAnchor[];
+}
+/** One captured element interaction (per locator call site). */
+interface LocatorSnapshot {
+    /** The Playwright step location — unique, stable identity of this call site. */
+    location: string | null;
+    /** The locator the test code actually used. */
+    used: {
+        method: string;
+        /** All args passed to the locator method. */
+        args: unknown[];
+        /** Original step title, for round-tripping. */
+        raw: string;
+    };
+    /** Element attributes — null for gap entries (failed actions). */
+    element: {
+        tagName: string;
+        attributes: Record<string, string | null>;
+        textContent: string | null;
+        accessibleName: string | null;
+        center: {
+            x: number;
+            y: number;
+        } | null;
+        /** Position among same-role elements at capture time (newer reporters only). */
+        rolePosition?: RolePosition | null;
+        /** Anchor-worthy ancestors, nearest first (newer reporters only). */
+        ancestors?: AncestorAnchor[];
+    } | null;
+    /** Computed alternative locators, ranked by stability score (max 10). */
+    alternatives: RankedLocator[];
+}
+
+/**
+ * Locator generation — pure functions for building ranked alternative locators
+ * from element attributes. The single source of truth shared by the server, the
+ * dashboard SPA, the interactive DOM snapshot picker (which runs in the
+ * browser), and the Playwright reporter (which bundles this at build time).
+ */
+
+/** Implicit ARIA role for an HTML tag (when no explicit `role` is set). */
+declare const TAG_TO_ROLE: Record<string, string>;
+/** Implicit ARIA role for an `<input>` keyed by its `type` attribute. */
+declare const INPUT_TYPE_TO_ROLE: Record<string, string>;
+/** Element attributes captured by the probe. */
+declare const CAPTURED_ATTRIBUTES: string[];
+declare function resolveAriaRole(attrs: ElementAttributes): string | null;
+declare function headingLevel(attrs: ElementAttributes, role: string | null): number | null;
+declare function classifyCssStability(className: string): number;
+declare function isAutoGenerated(value: string): boolean;
+interface GenerateOptions {
+    /**
+     * The element's role from an accessibility model, for a caller that has one:
+     * every role candidate uses it instead of `resolveAriaRole(attrs)`, and null
+     * means the element has none. `rolePosition` and the anchors' scoped role
+     * counts must then describe this role.
+     */
+    role?: string | null;
+    /**
+     * The attribute `getByTestId` reads in the project (Playwright's
+     * `testIdAttribute`); `data-testid` when null or absent. The element's
+     * `getByTestId` candidate comes from it, and so do the anchors', whose
+     * `testId` and `testIdCount` the probe reads from the same attribute
+     * (`ProbeArg.testIdAttribute`). No `locator()` candidate selects on it, since
+     * `getByTestId` does; any other attribute, `data-testid` included, is an
+     * ordinary one.
+     */
+    testIdAttribute?: string | null;
+}
+declare function generateAlternatives(attrs: ElementAttributes, options?: GenerateOptions): RankedLocator[];
+/**
+ * Approximate the accessible name from probed attributes, in the order the
+ * accessible-name computation applies: `aria-labelledby` (resolved by the probe
+ * into `labelText`), `aria-label`, then — for a form field — its `<label>`, or —
+ * for anything else — its text, then `title` and `placeholder`.
+ *
+ * A form field is never named by its own text: a `<select>`'s text is its
+ * options and a `<textarea>`'s is its value.
+ */
+declare function approximateAccessibleName(attrs: ElementAttributes): string | null;
 
 /**
  * Reporter-local locator healing.
@@ -131,6 +339,16 @@ declare function renderFailing(failed: FailedLocatorInfo): string;
  * present (so the failure wasn't a rename), or when no candidate is confident.
  */
 declare function suggestLocatorsFromAria(failed: FailedLocatorInfo, ariaSnapshot: string | null): LocatorSuggestion | null;
+/**
+ * The local path a stack frame's file names: a `file://` URL (an ES-module suite's frames) through `fileURLToPath`,
+ * any other path as it is. `windows` reads the URL as Windows does. Null for a URL that names no local file.
+ */
+declare function framePath(file: string, windows?: boolean): string | null;
+/**
+ * A stack frame's file relative to `cwd`, with forward slashes: the form Playwright writes a location in its error
+ * messages. A file on another drive stays absolute. Null for a URL that names no local file.
+ */
+declare function callSitePath(file: string, cwd?: string, windows?: boolean): string | null;
 /**
  * Capture the calling test's source location (`file:line:col`) from the current
  * stack, for stamping onto a locator snapshot. The path is made cwd-relative so
@@ -147,4 +365,4 @@ declare function suggestLocatorsFromAria(failed: FailedLocatorInfo, ariaSnapshot
  */
 declare function captureCallerLocation(stack?: string): string | null;
 
-export { ACTION_METHODS, CHAIN_METHODS, EXPECT_CAPTURE_EXPRESSIONS, EXPECT_METHOD, FORM_FIELD_TAGS, type FailedLocatorInfo, LOCATOR_CREATING_CHAINS, LOCATOR_METHODS, type LocatorSuggestion, type NameSource, captureCallerLocation, dedupeSnapshotsByLocation, exactAccessibleName, extractAccessibleName, renderFailing, suggestLocatorsFromAria };
+export { ACTION_METHODS, type AncestorAnchor, CAPTURED_ATTRIBUTES, CHAIN_METHODS, EXPECT_CAPTURE_EXPRESSIONS, EXPECT_METHOD, type ElementAttributes, FORM_FIELD_TAGS, type FailedLocatorInfo, INPUT_TYPE_TO_ROLE, LOCATOR_CREATING_CHAINS, LOCATOR_METHODS, type LocatorSnapshot, type LocatorSuggestion, type NameSource, type RankedLocator, type RolePosition, type SelectorCounts, TAG_TO_ROLE, approximateAccessibleName, callSitePath, captureCallerLocation, classifyCssStability, dedupeSnapshotsByLocation, exactAccessibleName, extractAccessibleName, framePath, generateAlternatives, headingLevel, isAutoGenerated, renderFailing, resolveAriaRole, suggestLocatorsFromAria };

package/dist/internal/capture/locator-healing.js

@@ -41,11 +41,13 @@ __export(locator_healing_exports, {
   LOCATOR_METHODS: () => LOCATOR_METHODS,
   TAG_TO_ROLE: () => TAG_TO_ROLE,
   approximateAccessibleName: () => approximateAccessibleName,
+  callSitePath: () => callSitePath,
   captureCallerLocation: () => captureCallerLocation,
   classifyCssStability: () => classifyCssStability,
   dedupeSnapshotsByLocation: () => dedupeSnapshotsByLocation,
   exactAccessibleName: () => exactAccessibleName,
   extractAccessibleName: () => extractAccessibleName,
+  framePath: () => framePath,
   generateAlternatives: () => generateAlternatives,
   headingLevel: () => headingLevel,
   isAutoGenerated: () => isAutoGenerated,
@@ -55,6 +57,7 @@ __export(locator_healing_exports, {
 });
 module.exports = __toCommonJS(locator_healing_exports);
 var path = __toESM(require("path"));
+var import_node_url = require("url");
 
 // ../core/src/locator-chain.ts
 var LOCATING_METHODS = /* @__PURE__ */ new Set([
@@ -744,6 +747,20 @@ function suggestLocatorsFromAria(failed, ariaSnapshot) {
   if (suggestions.length === 0) return null;
   return { failing: renderFailing(failed), suggestions };
 }
+function framePath(file, windows = process.platform === "win32") {
+  if (!file.startsWith("file://")) return file;
+  try {
+    return (0, import_node_url.fileURLToPath)(file, { windows });
+  } catch {
+    return null;
+  }
+}
+function callSitePath(file, cwd = process.cwd(), windows = process.platform === "win32") {
+  const local = framePath(file, windows);
+  if (local === null) return null;
+  const paths = windows ? path.win32 : path.posix;
+  return paths.relative(cwd, local).split(paths.sep).join("/");
+}
 function captureCallerLocation(stack = new Error().stack ?? "") {
   const lines = stack.split("\n");
   let prevWasCaptureModule = false;
@@ -756,13 +773,8 @@ function captureCallerLocation(stack = new Error().stack ?? "") {
       prevWasCaptureModule = false;
       continue;
     }
-    let file = m[2];
-    if (!file || file.startsWith("node:")) {
-      prevWasCaptureModule = false;
-      continue;
-    }
-    file = file.replace(/^file:\/\/\/?/, "");
-    if (!/\.[a-z]+$/i.test(file)) {
+    const file = m[2] ? framePath(m[2]) : null;
+    if (!file || file.startsWith("node:") || !/\.[a-z]+$/i.test(file)) {
       prevWasCaptureModule = false;
       continue;
     }
@@ -785,11 +797,9 @@ function captureCallerLocation(stack = new Error().stack ?? "") {
     }
     let rel = file;
     try {
-      rel = path.relative(process.cwd(), file);
+      rel = callSitePath(file) ?? file;
     } catch {
     }
-    rel = rel.split(path.sep).join("/");
-    if (rel.startsWith("./")) rel = rel.slice(2);
     return `${rel}:${m[3]}:${m[4]}`;
   }
   return null;
@@ -807,11 +817,13 @@ function captureCallerLocation(stack = new Error().stack ?? "") {
   LOCATOR_METHODS,
   TAG_TO_ROLE,
   approximateAccessibleName,
+  callSitePath,
   captureCallerLocation,
   classifyCssStability,
   dedupeSnapshotsByLocation,
   exactAccessibleName,
   extractAccessibleName,
+  framePath,
   generateAlternatives,
   headingLevel,
   isAutoGenerated,

package/dist/internal/capture/pick-on-failure.d.ts

@@ -1,9 +1,187 @@
 import { TestInfo, Page } from '@playwright/test';
-import { PickedAnchorInfo, ProbeArg, ProbedAttrs } from '@piwitests/picker-dom';
-export { PickedAnchorInfo, PickedLeafInfo, generateAnchoredAlternatives, installPickerOverlay, mergeCandidates, showAnchorPicker, showPickerChoices } from '@piwitests/picker-dom';
-import { FailedLocatorInfo } from './locator-healing.js';
-import { RankedLocator, LocatorSnapshot } from '@piwitests/core/locator-healing-types';
-import '@piwitests/core/locator-generation';
+import { P as ProbeArg, a as ProbedAttrs } from '../../types-CGr9jJZ_.js';
+import { RankedLocator, LocatorSnapshot, FailedLocatorInfo } from './locator-healing.js';
+
+/** The overlay's texts a host may give in its own language; each one left out is the English default. */
+interface PickerOverlayStrings {
+    /** The banner's heading for the `'global'` transport with no failing locator. */
+    banner?: string;
+    /** The banner's foot before an element is hovered: the keys, Enter picking the focused element. */
+    keys?: string;
+    /** The banner's foot while an element is hovered: a click or Enter picks it. */
+    keysHovering?: string;
+    /** The banner's foot once an element is picked. */
+    analyzing?: string;
+}
+/** Configuration for `installPickerOverlay` — see the function doc for the transport split. */
+interface PickerOverlayArg {
+    transport: 'global' | 'postMessage';
+    /** Rendered failing locator for the banner heading (`'global'` transport only). */
+    failing?: string | null;
+    /** Probe arguments for the inline probe the `'postMessage'` transport performs on pick. */
+    probeArg?: ProbeArg;
+    /** The banner's texts, for a host that shows another language than English. */
+    strings?: PickerOverlayStrings;
+    /**
+     * The attribute `getByTestId` reads in the project (Playwright's
+     * `testIdAttribute`); `data-testid` when null or absent. The overlay's own
+     * description of an element and its snapping to a test id read it.
+     */
+    testIdAttribute?: string | null;
+}
+/**
+ * Runs inside the browser — installs the element-picking overlay: a hover
+ * highlight, an instruction banner, and capture-phase listeners that suppress
+ * the app's own handlers while picking. The hover target snaps to the nearest
+ * actionable ancestor (button/link/field/role/test id) and up/down walk the
+ * DOM chain before the click commits. The hover reaches into open shadow
+ * roots, and the chain walks out of them through each host. Enter picks the
+ * outlined element, or with none the focused one, so a control reached with
+ * Tab is picked without the pointer.
+ *
+ * `transport` picks how a pick/skip is reported, since the two hosts cross
+ * fundamentally different boundaries:
+ *  - `'global'` — the reporter drives a live page from Node over CDP. The
+ *    picked element is parked on `globalThis.__piwiPickedElement` and
+ *    `__piwiPickState` is set to `'picked'`/`'skipped'`, polled from Node;
+ *    probing happens later, from Node, against a live element handle.
+ *  - `'postMessage'` — the snapshot picker runs standalone inside a sandboxed
+ *    opaque-origin iframe with nothing outside able to reach in, so the pick
+ *    is probed and posted to `window.parent` in the same tick. The probe
+ *    itself can't be imported (a serialized function carries no imports), so
+ *    the embedding host installs it on `globalThis.__piwiProbe` before
+ *    invoking this function, and may install lifecycle hooks on
+ *    `globalThis.__piwiSnapshotExtras` (`onPick`/`onClose`) for its own
+ *    snapshot-only chrome (search, highlight hints, extended inertness).
+ *
+ * The banner is in English unless `arg.strings` gives its texts.
+ *
+ * The hovered element's locator is shown twice — in a chip pinned to the
+ * element itself and on its own line in the banner. Both render whatever
+ * `globalThis.__piwiDescribeElement(el)` returns when a host installs one (the
+ * extension points it at the real ranked locator engine), falling back to this
+ * function's own attribute-order approximation. A host whose answer improves
+ * later (checked against the page once the pointer rests) calls
+ * `globalThis.__piwiRedescribe()` to have the hovered element described again.
+ *
+ * Must stay fully self-contained (no module-closure references) — both hosts
+ * re-serialize this function via `Function.prototype.toString()` (the
+ * reporter through `page.evaluate`, the snapshot picker through `String()`
+ * into a `<script>` tag).
+ */
+declare function installPickerOverlay(arg: PickerOverlayArg): void;
+
+/** An ancestor the human blessed as an anchor, with its in-page uniqueness counts. */
+interface PickedAnchorInfo {
+    tag: string;
+    /** Hops from the picked element (1 = direct parent). */
+    depth: number;
+    testId: string | null;
+    id: string | null;
+    ariaLabel: string | null;
+    /** Resolved anchor role (explicit attribute or tag-implied). */
+    role: string | null;
+    /** Document-wide match count for the anchor's own test id. */
+    testIdCount?: number;
+    /** Document-wide match count for the anchor's own id. */
+    idCount?: number;
+    /** Document-wide count of same-role elements carrying the same aria-label. */
+    labeledRoleCount?: number;
+    /** Document-wide count of elements resolving to the anchor's role. */
+    roleCount?: number;
+    /** Leaf matches (picked element's identity) within this anchor's subtree. */
+    scopedLeafCount?: number;
+}
+/** The picked element's identity used for anchor-scoped candidates. */
+interface PickedLeafInfo {
+    role: string | null;
+    level: number | null;
+}
+/**
+ * The anchors step's texts a host may give in its own language; each one left
+ * out is the English default. `{count}` in a text stands for a number.
+ */
+interface AnchorPickerStrings {
+    title?: string;
+    hint?: string;
+    /** The footer with no parent selected. */
+    noneSelected?: string;
+    matchesOne?: string;
+    /** `{count}` elements, any count but one. */
+    matchesMany?: string;
+    countUnavailable?: string;
+    /** Under a parent: what it contains. */
+    containsOne?: string;
+    containsMany?: string;
+    /** Under a parent that cannot be selected. */
+    needsTestId?: string;
+    /** A parent with no test id, id or role, in place of its hook. */
+    noHook?: string;
+    use?: string;
+    skip?: string;
+}
+/** Arguments for `showAnchorPicker` — the role maps mirror the single source of truth in `@piwitests/core`. */
+interface AnchorPickerArg {
+    tagRoles: Record<string, string>;
+    inputRoles: Record<string, string>;
+    roleSources: string;
+    leafRole: string;
+    leafLevel: number | null;
+    leafTestId: string | null;
+    /**
+     * The attribute `getByTestId` reads in the project (Playwright's
+     * `testIdAttribute`), which `leafTestId` and each parent's test id are read
+     * from; `data-testid` when null or absent.
+     */
+    testIdAttribute?: string | null;
+    /** The panel's texts, for a host that shows another language than English. */
+    strings?: AnchorPickerStrings;
+}
+/**
+ * Runs inside the browser via `evaluate()` — the anchor step: lists the picked
+ * element's ancestors so the human can bless one or more stable parents to
+ * scope the locator to. Each row shows the ancestor's strongest hook and how
+ * many leaf matches it contains; the footer shows a live "matches N" count for
+ * the combined selection, recomputed against the real page on every toggle
+ * (exactly 1 = green). Hovering a row outlines that ancestor in the page and
+ * names it in a chip pinned to it. Resolves through `__piwiAnchorState` ('done' | 'skipped'); selected anchors
+ * land in `__piwiPickAnchors` (+ `__piwiPickChainCount`). While the step
+ * shows, `__piwiAnchorCleanup` holds its teardown (see `removeAnchorPicker`).
+ * Role resolution reuses the maps passed in `arg` (single source of truth in
+ * `@piwitests/core`). The ancestors and every count reach through open shadow
+ * roots, as Playwright's locators do. The panel is in English unless
+ * `arg.strings` gives its texts. Must stay fully self-contained.
+ */
+declare function showAnchorPicker(arg: AnchorPickerArg): void;
+
+/** Arguments for `showPickerChoices`. */
+interface PickerChoicesArg {
+    failing: string | null;
+    choices: Array<{
+        locator: string;
+        score: number;
+    }>;
+}
+/**
+ * Runs inside the browser via `evaluate()` — replaces the pick overlay with a
+ * confirmation panel listing the ranked replacement locators. The chosen index
+ * lands in `__piwiPickChoice` (-1 = skipped), polled from Node. While it shows,
+ * `__piwiChoiceCleanup` takes it out of the page unanswered (a pick that ended
+ * under it). Must stay fully self-contained.
+ */
+declare function showPickerChoices(arg: PickerChoicesArg): void;
+
+/**
+ * Build anchor-scoped candidates from the human-blessed parents. Shapes stay
+ * consistent with the heuristic chains in `generateAlternatives` — leaf method
+ * `getByRole` with flat anchor args, no leaf `name` key. Single-anchor
+ * candidates require the leaf to be unique inside that anchor; with two or
+ * more anchors a combined chain is added when the whole chain resolves to
+ * exactly one element (`chainLeafCount`). Pure — exported for tests.
+ */
+declare function generateAnchoredAlternatives(leaf: PickedLeafInfo, anchors: PickedAnchorInfo[], chainLeafCount?: number): RankedLocator[];
+/** Merge candidate lists, first list winning duplicates, sorted by score. Exported for tests. */
+declare function mergeCandidates(base: RankedLocator[], extra: RankedLocator[]): RankedLocator[];
 
 /**
  * The probe dependency, passed in by the capture fixture to avoid an import
@@ -91,4 +269,4 @@ declare function runLocatorPicker(page: Page, testInfo: TestInfo, failed: Failed
  */
 declare function applyPickToSnapshots(snapshots: LocatorSnapshot[], pick: UserPickResult): boolean;
 
-export { type PickedLocator, type PickerProbe, type UserPickResult, applyPickToSnapshots, deriveFailedLocator, parseLeafLocatorExpression, pickLocator, runLocatorPicker, unlessEnded };
+export { type PickedAnchorInfo, type PickedLeafInfo, type PickedLocator, type PickerProbe, type UserPickResult, applyPickToSnapshots, deriveFailedLocator, generateAnchoredAlternatives, installPickerOverlay, mergeCandidates, parseLeafLocatorExpression, pickLocator, runLocatorPicker, showAnchorPicker, showPickerChoices, unlessEnded };

package/dist/internal/capture/pick-on-failure.js

@@ -880,13 +880,17 @@ function showAnchorPicker(arg) {
   }
   const MONO = "ui-monospace,SFMono-Regular,Menlo,Consolas,monospace";
   const outline = doc.createElement("div");
+  outline.id = "__piwi_anchor_outline";
   outline.style.cssText = `position:fixed;pointer-events:none;z-index:${Z};box-sizing:border-box;border:2px solid #22c55e;background:rgba(34,197,94,.10);border-radius:4px;display:none;box-shadow:0 0 0 1px rgba(255,255,255,.9),0 0 0 3px rgba(5,46,22,.5);`;
   const outlineLabel = doc.createElement("div");
+  outlineLabel.id = "__piwi_anchor_label";
   outlineLabel.style.cssText = `position:fixed;pointer-events:none;z-index:${Z + 1};display:none;box-sizing:border-box;max-width:min(420px,90vw);background:#0b1120;color:#f9fafb;border:1px solid #22c55e;border-radius:6px;padding:3px 7px;font:12px/1.45 ${MONO};white-space:nowrap;overflow:hidden;text-overflow:ellipsis;box-shadow:0 4px 18px rgba(0,0,0,.5);`;
   const pickedOutline = doc.createElement("div");
+  pickedOutline.id = "__piwi_anchor_picked";
   const pr = el.getBoundingClientRect();
   pickedOutline.style.cssText = `position:fixed;pointer-events:none;z-index:${Z};box-sizing:border-box;border:2px solid #a855f7;background:rgba(168,85,247,.14);border-radius:4px;box-shadow:0 0 0 1px rgba(255,255,255,.9),0 0 0 3px rgba(59,7,100,.55);left:${pr.left}px;top:${pr.top}px;width:${pr.width}px;height:${pr.height}px;`;
   const panel = doc.createElement("div");
+  panel.id = "__piwi_anchor_panel";
   panel.style.cssText = `position:fixed;top:12px;right:12px;z-index:${Z + 3};width:min(340px,calc(100vw - 56px));max-height:82vh;overflow:auto;background:#111827;color:#f9fafb;border-radius:10px;padding:16px;font:12px/1.5 system-ui,sans-serif;box-shadow:0 8px 40px rgba(0,0,0,.5);`;
   const title = doc.createElement("div");
   title.style.cssText = "font-weight:600;font-size:13px;margin-bottom:2px;";
@@ -1075,6 +1079,7 @@ function showPickerChoices(arg) {
   }
   const Z = 2147483600;
   const wrap = doc.createElement("div");
+  wrap.id = "__piwi_picker_choices";
   wrap.style.cssText = `position:fixed;inset:0;z-index:${Z + 3};background:rgba(0,0,0,.45);display:flex;align-items:center;justify-content:center;font:13px/1.5 system-ui,sans-serif;`;
   const panel = doc.createElement("div");
   panel.style.cssText = "background:#111827;color:#f9fafb;border-radius:10px;padding:20px;max-width:640px;width:90vw;max-height:70vh;overflow:auto;box-shadow:0 8px 40px rgba(0,0,0,.5);";
@@ -1105,10 +1110,14 @@ function showPickerChoices(arg) {
   }
   panel.appendChild(title);
   panel.appendChild(sub);
-  const done = (choice) => {
-    g.__piwiPickChoice = choice;
+  const cleanup = () => {
     doc.removeEventListener("keydown", onKey, true);
     wrap.remove();
+    if (g.__piwiChoiceCleanup === cleanup) delete g.__piwiChoiceCleanup;
+  };
+  const done = (choice) => {
+    g.__piwiPickChoice = choice;
+    cleanup();
   };
   const onKey = (e) => {
     if (e.key !== "Escape") return;
@@ -1144,6 +1153,7 @@ function showPickerChoices(arg) {
   });
   panel.appendChild(skip);
   doc.addEventListener("keydown", onKey, true);
+  g.__piwiChoiceCleanup = cleanup;
   wrap.appendChild(panel);
   doc.body.appendChild(wrap);
 }
@@ -1569,6 +1579,7 @@ function mergeCandidates(base, extra) {
 
 // src/internal/capture/locator-healing.ts
 var path = __toESM(require("path"));
+var import_node_url = require("url");
 
 // ../core/src/locator-fingerprint.ts
 var FUNCTION_WORDS = new Set(
@@ -1625,8 +1636,10 @@ async function cleanupPicker(page, ended = false) {
         const g = globalThis;
         if (typeof g.__piwiPickCleanup === "function") g.__piwiPickCleanup();
         if (typeof g.__piwiAnchorCleanup === "function") g.__piwiAnchorCleanup();
+        if (typeof g.__piwiChoiceCleanup === "function") g.__piwiChoiceCleanup();
         delete g.__piwiPickCleanup;
         delete g.__piwiAnchorCleanup;
+        delete g.__piwiChoiceCleanup;
         delete g.__piwiPickState;
         delete g.__piwiPickChoice;
         delete g.__piwiPickedElement;
@@ -1652,13 +1665,24 @@ function unlessEnded(run, ended) {
   ]);
 }
 async function pickLocator(page, probe, failing, ended) {
+  let polling = false;
   const answered = async (name) => {
     const wait = page.waitForFunction(
-      ([key, endedKey]) => globalThis[key] !== void 0 || globalThis[endedKey] === true,
+      ([key, endedKey]) => {
+        const g = globalThis;
+        if (g[endedKey] !== true) return g[key] !== void 0;
+        delete g[endedKey];
+        return true;
+      },
       [name, PICK_ENDED],
       { timeout: 0, polling: 250 }
     );
-    await unlessEnded(wait, ended);
+    polling = true;
+    const done = await unlessEnded(
+      wait.then(() => true),
+      ended
+    );
+    if (done) polling = false;
     return !ended?.aborted;
   };
   try {
@@ -1727,7 +1751,7 @@ async function pickLocator(page, probe, failing, ended) {
       ...anchors.length > 0 ? { anchors } : {}
     };
   } finally {
-    await cleanupPicker(page, ended?.aborted);
+    await cleanupPicker(page, polling);
   }
 }
 async function runLocatorPicker(page, testInfo, failed, probe) {