@piwitests/reporter 0.12.0 → 0.13.0

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

@@ -0,0 +1,198 @@
+import { TestInfo, Page } from '@playwright/test';
+import { FailedLocatorInfo } from './locator-healing.js';
+import { SelectorCounts, RolePosition, AncestorAnchor, RankedLocator, LocatorSnapshot } from '@piwitests/core/locator-healing-types';
+import '@piwitests/core/locator-generation';
+
+/**
+ * Failure-time locator picker: when enabled (opt-in via the
+ * `pickLocatorOnFailure` reporter option / `PIWI_PICK_LOCATOR_ON_FAIL`), a
+ * test whose locator action failed gets a picker overlay injected into the
+ * still-open page. The flow is guided:
+ *
+ *  1. **Element** — hover highlights, a click picks. The pick snaps to the
+ *     nearest actionable ancestor (a click on the `<span>` inside a button
+ *     picks the button), and ↑/↓ walk the DOM tree before the click commits.
+ *  2. **Anchors** — the element's ancestors are listed; the human can bless
+ *     one or more *stable parents* to scope the locator to, with a live
+ *     "matches N" count for the current selection against the failing page.
+ *  3. **Confirm** — ranked replacement locators (standard generation merged
+ *     with the anchor-scoped candidates) are listed; the human confirms one.
+ *
+ * The confirmed pick is folded into the failing call site's locator snapshot
+ * (so it rides the normal `piwi-locators` wire into the dashboard's healing
+ * panel) and attached as `piwi-user-pick` plus a report annotation.
+ *
+ * Gated exactly like failure-time inspection (`inspect-on-failure.ts`):
+ * headed browser, never CI, final attempt only.
+ */
+/** Element shape the in-page probe returns — structural view of what the picker needs. */
+interface ProbedAttrs {
+    tagName: string;
+    attributes: Record<string, string | null>;
+    textContent: string | null;
+    center: {
+        x: number;
+        y: number;
+    } | null;
+    hasLabel?: boolean;
+    selectorCounts?: SelectorCounts;
+    rolePosition?: RolePosition | null;
+    ancestors?: AncestorAnchor[];
+}
+/**
+ * The probe dependency, passed in by the capture fixture to avoid an import
+ * cycle. `fn` is the fixture's in-page element probe (`probeElementAttrs`);
+ * `el` is a browser-side element, hence `any` (no DOM lib in this package).
+ * `arg` is the fixture's `CAPTURED_ATTRS_ARG` — its role maps also drive the
+ * anchor step's in-page role resolution.
+ */
+interface PickerProbe {
+    fn: (el: any, arg: any) => ProbedAttrs;
+    arg: unknown;
+}
+/** 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 data-testid. */
+    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;
+}
+/** A confirmed pick — everything the fixture records about the human's choice. */
+interface UserPickResult {
+    /**
+     * The locator this pick replaces. Null when the overlay was opened purely to
+     * inspect (`inspectOnFailure` with no identifiable failing locator) — the
+     * pick still yields alternatives, but there is nothing to write back to.
+     */
+    failing: {
+        method: string;
+        args: unknown[];
+        /** The failed locator rendered as source, e.g. `getByText('Pay now')`. */
+        rendered: string;
+        /** Test call site (`file:line:col`) of the failed action, when captured. */
+        location: string | null;
+    } | null;
+    /** The alternative the human confirmed (also first in `alternatives`). */
+    picked: RankedLocator;
+    /** Full ranked list for the picked element, the confirmed pick first. */
+    alternatives: RankedLocator[];
+    /** Wire-shaped element snapshot of the picked element. */
+    element: NonNullable<LocatorSnapshot['element']>;
+    /** Stable parents the human blessed in the anchor step, when any. */
+    anchors?: PickedAnchorInfo[];
+}
+/** Parse a Playwright locator expression into `{ method, args }` (leaf of any chain). Exported for tests. */
+declare function parseLeafLocatorExpression(rawExpr: string): {
+    method: string;
+    args: unknown[];
+} | null;
+/**
+ * Derive the failing locator + call site from a test's error(s) when no locator
+ * action was captured (an `expect(...)` assertion failure). Reads the
+ * `Locator: …` line Playwright prints and the error's own call location,
+ * normalized cwd-relative to match captured snapshot locations. Returns null
+ * when no locator can be identified. Exported for tests.
+ */
+declare function deriveFailedLocator(testInfo: TestInfo): FailedLocatorInfo | null;
+/**
+ * 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[];
+/**
+ * Runs inside the browser via `evaluate()` — 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/
+ * testid) and ↑/↓ walk the DOM chain before the click commits. Resolves
+ * through `__piwiPickState` ('picked' | 'skipped') polled from Node; the
+ * picked element is parked in `__piwiPickedElement` for an `evaluateHandle`
+ * read. Must stay fully self-contained (no module-closure references).
+ */
+declare function installPickerOverlay(arg: {
+    failing: string | null;
+}): void;
+/**
+ * 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 failing page on every
+ * toggle (exactly 1 = green). Hovering a row outlines that ancestor in the
+ * page. Resolves through `__piwiAnchorState` ('done' | 'skipped'); selected
+ * anchors land in `__piwiPickAnchors` (+ `__piwiPickChainCount`). Role
+ * resolution reuses the maps passed in `arg` (single source of truth in
+ * locator-healing.ts). Must stay fully self-contained.
+ */
+declare function showAnchorPicker(arg: {
+    tagRoles: Record<string, string>;
+    inputRoles: Record<string, string>;
+    roleSources: string;
+    leafRole: string;
+    leafLevel: number | null;
+    leafTestId: string | null;
+}): void;
+/**
+ * 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. Must stay
+ * fully self-contained.
+ */
+declare function showPickerChoices(arg: {
+    failing: string | null;
+    choices: Array<{
+        locator: string;
+        score: number;
+    }>;
+}): void;
+/**
+ * Drive the full pick flow on the failing page: element pick (snap +
+ * tree-walk), optional stable-parent anchoring with live match counts, ranked
+ * candidates (standard generation merged with anchor-scoped chains), and a
+ * final confirmation. The test timeout is lifted while waiting. Returns null
+ * when skipped or when anything breaks — the picker must never mask the
+ * test's own failure.
+ */
+declare function runLocatorPicker(page: Page, testInfo: TestInfo, failed: FailedLocatorInfo | null, probe: PickerProbe): Promise<UserPickResult | null>;
+/**
+ * Fold a confirmed pick into the captured snapshots: the failed action's
+ * placeholder (same call site, no element — capture never probes an action
+ * that threw) is filled with the picked element and the confirmed-first
+ * alternative list, so the pick rides the normal `piwi-locators` attachment
+ * into the dashboard's `locator_snapshots` and healing panel.
+ *
+ * A failed locator *action* left a placeholder at its call site (same location,
+ * no element) — that placeholder is filled in place. An assertion failure left
+ * no placeholder (no action ran), so a fresh snapshot is appended under the
+ * failing locator's location and signature instead, so the pick still reaches
+ * `locator_snapshots`. No-op only when the failing locator has no location.
+ * Exported for tests.
+ */
+declare function applyPickToSnapshots(snapshots: LocatorSnapshot[], pick: UserPickResult): boolean;
+
+export { type PickedAnchorInfo, type PickedLeafInfo, type PickerProbe, type UserPickResult, applyPickToSnapshots, deriveFailedLocator, generateAnchoredAlternatives, installPickerOverlay, mergeCandidates, parseLeafLocatorExpression, runLocatorPicker, showAnchorPicker, showPickerChoices };