@piwitests/reporter 0.12.0 → 0.13.0

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

@@ -0,0 +1,50 @@
+import { TestInfo } from '@playwright/test';
+
+/**
+ * Shared gate for Piwi's failure-time overlay. Both `inspectOnFailure`
+ * (`PIWI_INSPECT_ON_FAIL`) and `pickLocatorOnFailure` (`PIWI_PICK_LOCATOR_ON_FAIL`)
+ * open Piwi's own in-page overlay (see `pick-on-failure.ts`) — never
+ * Playwright's native inspector — so the experience is fully ours and a
+ * confirmed pick flows back into the dashboard.
+ *
+ * Local-only by design: the overlay needs a human and a visible browser, so the
+ * gate requires a headed browser and refuses to run under CI regardless of the
+ * flag. It also waits for the final attempt when retries are configured — an
+ * attempt that is about to be retried closes without opening the overlay.
+ */
+/** Everything the gate reads, as plain values so it stays unit-testable. */
+interface InspectionGate {
+    /** Raw `PIWI_INSPECT_ON_FAIL` env value — only the string `'true'` enables. */
+    enabled: string | undefined;
+    /** Raw `CI` env value. Anything except unset/empty/`'false'` counts as CI. */
+    ci: string | undefined;
+    /** `testInfo.status` at teardown. */
+    status: string | undefined;
+    /** `testInfo.expectedStatus` — an expected failure (test.fail()) never pauses. */
+    expectedStatus: string | undefined;
+    /** `testInfo.project.use.headless` — must be explicitly `false` (headed). */
+    headless: unknown;
+    /** Zero-based attempt index (`testInfo.retry`). */
+    retry: number;
+    /** Configured retry count for the project (`testInfo.project.retries`). */
+    retries: number;
+}
+/** Decide whether the failing page should be handed to the Inspector. */
+declare function shouldInspectOnFailure(gate: InspectionGate): boolean;
+/**
+ * When a failure-time feature is *enabled* on a *real* failure but the gate
+ * still refused for an environmental reason (headless / CI), return a
+ * one-line human explanation so "nothing happened" is never a silent mystery.
+ * Returns null when the feature is off, the test didn't really fail, or the
+ * gate would actually pass (the feature ran, so there is nothing to explain).
+ */
+declare function environmentalSkipReason(gate: InspectionGate): string | null;
+/**
+ * Project the live TestInfo + process env into the plain gate shape. The gate
+ * conditions are shared by every failure-time affordance that needs a live
+ * headed page; `enabled` selects which opt-in flag arms this one (defaults to
+ * the Inspector's `PIWI_INSPECT_ON_FAIL`).
+ */
+declare function inspectionGateFromTestInfo(testInfo: TestInfo, enabled?: string | undefined): InspectionGate;
+
+export { type InspectionGate, environmentalSkipReason, inspectionGateFromTestInfo, shouldInspectOnFailure };

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

@@ -0,0 +1,66 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/internal/capture/inspect-on-failure.ts
+var inspect_on_failure_exports = {};
+__export(inspect_on_failure_exports, {
+  environmentalSkipReason: () => environmentalSkipReason,
+  inspectionGateFromTestInfo: () => inspectionGateFromTestInfo,
+  shouldInspectOnFailure: () => shouldInspectOnFailure
+});
+module.exports = __toCommonJS(inspect_on_failure_exports);
+function isCi(ci) {
+  return ci !== void 0 && ci !== "" && ci !== "false";
+}
+function shouldInspectOnFailure(gate) {
+  if (gate.enabled !== "true") return false;
+  if (isCi(gate.ci)) return false;
+  if (gate.headless !== false) return false;
+  if (gate.status !== "failed" && gate.status !== "timedOut") return false;
+  if (gate.status === gate.expectedStatus) return false;
+  return gate.retry >= gate.retries;
+}
+function environmentalSkipReason(gate) {
+  if (gate.enabled !== "true") return null;
+  if (gate.status !== "failed" && gate.status !== "timedOut") return null;
+  if (gate.status === gate.expectedStatus) return null;
+  if (isCi(gate.ci)) return "running under CI \u2014 this is a headed, local-only feature";
+  if (gate.headless !== false) {
+    return "the browser is headless \u2014 re-run with --headed (or set use: { headless: false })";
+  }
+  return null;
+}
+function inspectionGateFromTestInfo(testInfo, enabled = process.env.PIWI_INSPECT_ON_FAIL) {
+  const use = testInfo.project?.use ?? {};
+  return {
+    enabled,
+    ci: process.env.CI,
+    status: testInfo.status,
+    expectedStatus: testInfo.expectedStatus,
+    headless: use.headless,
+    retry: testInfo.retry,
+    retries: testInfo.project?.retries ?? 0
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  environmentalSkipReason,
+  inspectionGateFromTestInfo,
+  shouldInspectOnFailure
+});

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

@@ -1,108 +1,22 @@
+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';
+
 /**
- * Reporter-local locator healing — pure functions for alternative generation,
- * stability scoring, and the Playwright method-surface constants shared with
- * the fixture proxy. No Playwright dependency — takes raw element attributes,
- * returns ranked locator suggestions.
- */
-export 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;
-}
-/**
- * Match counts for candidate selectors, probed with `querySelectorAll` against
- * the live page at capture time. A count > 1 means the selector is ambiguous
- * (would be a strict-mode violation) and the alternative is suppressed; a
- * missing count means the probe didn't run and the alternative is kept.
- */
-export interface SelectorCounts {
-    testId?: number;
-    id?: number;
-    name?: number;
-    classes?: Record<string, number>;
-}
-/**
- * The element's position among same-role elements in the document at capture
- * time — a name-independent structural identity. `levelCount` additionally
- * counts same-role elements sharing this element's heading level, so a lone
- * `h1` among many `h2`s still gets a name-free `getByRole('heading', { level: 1 })`.
- */
-export interface RolePosition {
-    role: string;
-    count: number;
-    index: number;
-    levelCount?: number;
-}
-/**
- * An anchor-worthy ancestor — one carrying a stable hook (test id, id,
- * explicit role, aria-label, or a landmark tag) that a scoped alternative can
- * chain from. Nearest ancestors first.
+ * Reporter-local locator healing.
+ *
+ * The pure surface — alternative generation, stability scoring, ARIA-role
+ * resolution, the role maps and the captured-attribute whitelist — lives in
+ * `@piwitests/core` (bundled into `dist/` at build time, so nothing
+ * monorepo-relative leaks into the published package). It is re-exported from
+ * here so existing importers (`capture-fixtures.ts`, `pick-on-failure.ts`, the
+ * unit tests) keep importing it from this module.
+ *
+ * This module keeps only the reporter-only runtime: call-site capture (needs the
+ * Node stack), snapshot dedupe, the fixture-proxy method surface, and the
+ * failure-time locator suggestion + rendering.
  */
-export interface AncestorAnchor {
-    tag: string;
-    /** Hops from the element (1 = direct parent). */
-    depth: number;
-    testId: string | null;
-    id: string | null;
-    role: string | null;
-    ariaLabel: string | null;
-    /** Same-role matches for the captured element within this ancestor. */
-    scopedRoleCount?: 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;
-}
-export interface ElementAttributes {
-    tagName: string;
-    attributes: Record<string, string | null>;
-    textContent: string | null;
-    accessibleName: string | null;
-    center: {
-        x: number;
-        y: number;
-    } | null;
-    /**
-     * True when the element has an associated `<label>` (`el.labels`). Gates the
-     * `getByLabel` alternative — an accessible name approximated from
-     * placeholder/title would produce a `getByLabel` that matches nothing.
-     * Undefined on payloads from older capture probes (legacy behavior applies).
-     */
-    hasLabel?: boolean;
-    /** 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[];
-}
-export interface LocatorSnapshot {
-    location: string | null;
-    used: {
-        method: string;
-        args: unknown[];
-        raw: string;
-    };
-    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. */
-        rolePosition?: RolePosition | null;
-        /** Anchor-worthy ancestors, nearest first. */
-        ancestors?: AncestorAnchor[];
-    } | null;
-    alternatives: RankedLocator[];
-}
+
 /**
  * Drop repeated captures of the same call site before attaching: a loop (or a
  * page-object method called repeatedly) produces one snapshot per action, but
@@ -111,78 +25,24 @@ export interface LocatorSnapshot {
  * when no capture resolved, so the location still counts as "seen this run"
  * for the server's stale-location purge. Entries with no location pass through.
  */
-export declare function dedupeSnapshotsByLocation(snaps: LocatorSnapshot[]): LocatorSnapshot[];
+declare function dedupeSnapshotsByLocation(snaps: LocatorSnapshot[]): LocatorSnapshot[];
 /**
  * Page-level locator-building methods wrapped by the capture proxy. Imported by
  * both the capture fixtures (`capture-fixtures.ts`) and the dogfooding
  * `application/tests/fixtures.ts` so the two stay in sync (a prior drift missed
  * `scrollIntoViewIfNeeded`).
  */
-export declare const LOCATOR_METHODS: string[];
+declare const LOCATOR_METHODS: string[];
 /**
  * Methods that can be chained onto a wrapped locator. Locator-creating chains
  * (those also in `LOCATOR_METHODS`) update the origin; positional/filter chains
  * (`first`, `nth`, `filter`, …) narrow without changing locator identity.
  */
-export declare const CHAIN_METHODS: string[];
+declare const CHAIN_METHODS: string[];
 /** Locator action methods that trigger element capture. */
-export declare const ACTION_METHODS: string[];
+declare const ACTION_METHODS: string[];
 /** Chain methods that create a new locator scope (origin tracks the chain call). */
-export declare const LOCATOR_CREATING_CHAINS: ReadonlySet<string>;
-/**
- * Element attributes to capture after a successful action, passed into the
- * in-page `evaluate`. Shared so the reporter and dogfooding fixtures capture
- * the same attribute set.
- */
-export declare const CAPTURED_ATTRIBUTES: string[];
-/**
- * Implicit ARIA role for an HTML tag (when no explicit `role` is set). Exported
- * so the in-page probe (`capture-fixtures.ts#probeElementAttrs`) can receive
- * this same map as an `evaluate` argument instead of re-declaring it — the
- * probe is serialized into the browser and can't reference this module's
- * closure, but the map is pure data and rides in as an argument.
- */
-export declare const TAG_TO_ROLE: Record<string, string>;
-/** Implicit ARIA role for an `<input>` keyed by its `type` attribute. Exported for the probe (see {@link TAG_TO_ROLE}). */
-export declare const INPUT_TYPE_TO_ROLE: Record<string, string>;
-/**
- * Resolve the ARIA role for an element. An explicit `role` attribute wins;
- * otherwise the implicit role is derived from the tag name (and `type` for
- * `<input>`). Returns null when the element has no ARIA role (e.g. `<div>`,
- * `<span>`, `<a>` without `href`) — `getByRole` is not a valid locator for
- * such elements and other alternatives take over.
- */
-export declare function resolveAriaRole(attrs: ElementAttributes): string | null;
-/**
- * Heading level for a `heading`-role element: h1-h6 from the tag, else an
- * explicit `aria-level` attribute. Null when unknown (don't guess the ARIA
- * default) or when the element isn't a heading.
- */
-export declare function headingLevel(attrs: ElementAttributes, role: string | null): number | null;
-/**
- * Build a ranked list of alternative locators from the captured element
- * attributes. The list is sorted descending by stability score.
- *
- * Only generates alternatives that differ from each other — no duplicates
- * of the same locator expression.
- */
-export declare function generateAlternatives(attrs: ElementAttributes): RankedLocator[];
-/**
- * Score a CSS class name on a 0-40 stability scale.
- *
- * Heuristics (inherited from common CSS-naming conventions):
- * - Hash-like suffixes (≥4 hex chars) → 10 — auto-generated, fragile
- * - CSS-in-JS patterns (css-, sc-, emotion-, styled-, _) → 15
- * - Tailwind/utility classes → 25
- * - BEM-style semantic → 35
- * - Plain semantic → 40
- */
-export declare function classifyCssStability(className: string): number;
-/**
- * Detects GUID-like, auto-incremented, or hash-suffixed IDs that are
- * likely regenerated on each render and unstable for testing.
- */
-export declare function isAutoGenerated(value: string): boolean;
+declare const LOCATOR_CREATING_CHAINS: ReadonlySet<string>;
 /**
  * Extract the accessible name from a YAML-like ariaSnapshot() output.
  *
@@ -194,41 +54,22 @@ export declare function isAutoGenerated(value: string): boolean;
  *
  * Returns the first quoted string after the role, or null if none found.
  */
-export declare function extractAccessibleName(ariaSnapshot: string | null): string | null;
-/**
- * Approximate the accessible name from HTML attributes when ariaSnapshot()
- * is unavailable. Priority: aria-label > text content > title > placeholder.
- */
-export declare function approximateAccessibleName(attrs: ElementAttributes): string | null;
+declare function extractAccessibleName(ariaSnapshot: string | null): string | null;
 /** A failed locator action, used to suggest a fresh locator from the live page. */
-export interface FailedLocatorInfo {
+interface FailedLocatorInfo {
     method: string;
     args: unknown[];
+    /** Test call site (`file:line:col`) of the failed action, when captured. */
+    location?: string | null;
 }
-export interface LocatorSuggestion {
+interface LocatorSuggestion {
     /** The failed locator rendered as source, e.g. `getByText('Go to page')`. */
     failing: string;
     /** Fresh locator suggestions for the element's current identity, best first. */
     suggestions: string[];
 }
-/**
- * Parse `ariaSnapshot()` lines into role/name pairs (mirrors the server-side
- * `parseAriaCandidates` in application/shared/locator-fingerprint.ts).
- * Exported so the dashboard's drift-guard unit test can compare the two.
- */
-export declare function parseAriaRoleName(ariaSnapshot: string): Array<{
-    role: string;
-    name: string | null;
-    level: number | null;
-}>;
-/**
- * Token-set (Dice) similarity, 0-1, case- and punctuation-insensitive.
- * Duplicated from `textSimilarity` in application/shared/locator-fingerprint.ts —
- * this package publishes standalone to npm and can't import monorepo-relative
- * shared/ code, so keep the two implementations in sync by hand. Exported so
- * the dashboard's drift-guard unit test can compare the two.
- */
-export declare function nameSimilarity(a: string | null, b: string | null): number;
+/** Render the failed locator back to source for annotation/picker messages. */
+declare function renderFailing(failed: FailedLocatorInfo): string;
 /**
  * Best-effort runtime suggestion for a locator that matched nothing: find the
  * element on the *current* page that the failed locator most likely targeted
@@ -240,7 +81,7 @@ export declare function nameSimilarity(a: string | null, b: string | null): numb
  * for non-name-based locators (testid/CSS), when the targeted name is still
  * present (so the failure wasn't a rename), or when no candidate is confident.
  */
-export declare function suggestLocatorsFromAria(failed: FailedLocatorInfo, ariaSnapshot: string | null): LocatorSuggestion | null;
+declare function suggestLocatorsFromAria(failed: FailedLocatorInfo, ariaSnapshot: string | null): LocatorSuggestion | 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
@@ -255,4 +96,6 @@ export declare function suggestLocatorsFromAria(failed: FailedLocatorInfo, ariaS
  * Returns null when no user frame can be identified — the snapshot keeps
  * `location: null` and the server falls back to fingerprint / ARIA lookup.
  */
-export declare function captureCallerLocation(stack?: string): string | null;
+declare function captureCallerLocation(stack?: string): string | null;
+
+export { ACTION_METHODS, CHAIN_METHODS, type FailedLocatorInfo, LOCATOR_CREATING_CHAINS, LOCATOR_METHODS, type LocatorSuggestion, captureCallerLocation, dedupeSnapshotsByLocation, extractAccessibleName, renderFailing, suggestLocatorsFromAria };