@piwitests/reporter 0.4.3 → 0.5.0

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import type { PlaywrightTestConfig } from '@playwright/test';
+export type { PlaywrightTestConfig } from '@playwright/test';
 /** Playwright shard info — mirrors `config.shard` shape */
 export interface ShardInfo {
     current: number;
@@ -6,6 +7,8 @@ export interface ShardInfo {
 }
 /** Options for configuring the Piwi Dashboard reporter */
 export interface PiwiDashboardOptions extends PlaywrightTestConfig {
+    /** Explicitly enable or disable the reporter. Defaults to `true` when `serverUrl` is set. Set to `false` to disable even if `serverUrl` is provided. */
+    enabled?: boolean;
     /** URL of the Piwi Dashboard server */
     serverUrl?: string;
     /** Name of the project to report results under. Defaults to `'default-project'`. */
@@ -24,6 +27,14 @@ export interface PiwiDashboardOptions extends PlaywrightTestConfig {
     collectCiInfo?: boolean;
     /** Collect step timings, network requests and web vitals. Defaults to `true`. */
     collectPerformanceMetrics?: boolean;
+    /**
+     * Capture per-action locator snapshots that power failure-time healing
+     * suggestions. Adds a small per-action cost (one DOM read, sometimes an ARIA
+     * snapshot) in the test worker. Defaults to `true`; automatically disabled
+     * when `collectPerformanceMetrics` is `false` (the reporter discards the data
+     * in that case anyway). Can also be forced off with `PIWI_CAPTURE_LOCATORS=false`.
+     */
+    captureLocators?: boolean;
     /** Enable live streaming of results (falls back to batch if unsupported). Defaults to `true`. */
     streaming?: boolean;
     /** Number of test results to batch before sending during streaming. Defaults to `5`. */
@@ -81,6 +92,7 @@ export declare const PIWI_ENV_KEYS: {
     readonly liveFileUploads: "PIWI_LIVE_FILE_UPLOADS";
     readonly uploadTraces: "PIWI_UPLOAD_TRACES";
     readonly uploadReport: "PIWI_UPLOAD_REPORT";
+    readonly captureLocators: "PIWI_CAPTURE_LOCATORS";
 };
 /**
  * Merge raw user options with defaults, reading from `PIWI_*` env vars when

package/dist/config.js

@@ -11,6 +11,7 @@ const DEFAULTS = {
     collectScmInfo: true,
     collectCiInfo: true,
     collectPerformanceMetrics: true,
+    captureLocators: true,
     streaming: true,
     streamingBatchSize: 5,
     streamingBatchDelay: 2000,
@@ -41,6 +42,7 @@ exports.PIWI_ENV_KEYS = {
     liveFileUploads: 'PIWI_LIVE_FILE_UPLOADS',
     uploadTraces: 'PIWI_UPLOAD_TRACES',
     uploadReport: 'PIWI_UPLOAD_REPORT',
+    captureLocators: 'PIWI_CAPTURE_LOCATORS',
 };
 function readBool(val) {
     if (val === undefined)
@@ -92,6 +94,8 @@ function resolveOptions(raw) {
         mergedRaw.uploadTraces = readBool(env[exports.PIWI_ENV_KEYS.uploadTraces]);
     if (mergedRaw.uploadReport === undefined && env[exports.PIWI_ENV_KEYS.uploadReport] !== undefined)
         mergedRaw.uploadReport = readBool(env[exports.PIWI_ENV_KEYS.uploadReport]);
+    if (mergedRaw.captureLocators === undefined && env[exports.PIWI_ENV_KEYS.captureLocators] !== undefined)
+        mergedRaw.captureLocators = readBool(env[exports.PIWI_ENV_KEYS.captureLocators]);
     const opts = { ...DEFAULTS, ...mergedRaw };
     // Preserved quirk: PIWI_VERBOSE wins over both default and user option.
     if (env[exports.PIWI_ENV_KEYS.verbose] !== undefined)
@@ -124,4 +128,11 @@ function applyOptionsToEnv(options) {
         env[exports.PIWI_ENV_KEYS.label] = options.label;
     if (options.runLabel)
         env[exports.PIWI_ENV_KEYS.runLabel] = options.runLabel;
+    // Locator capture is part of performance-metric collection; switch it off in
+    // the worker when either flag is disabled so the fixture skips the per-action
+    // cost. Only an explicit `true` overrides the unset (default-on) state.
+    if (options.captureLocators === false || options.collectPerformanceMetrics === false)
+        env[exports.PIWI_ENV_KEYS.captureLocators] = 'false';
+    else if (options.captureLocators === true)
+        env[exports.PIWI_ENV_KEYS.captureLocators] = 'true';
 }

package/dist/fixtures.d.ts

@@ -1,7 +1,7 @@
 import type { Fixtures } from '@playwright/test';
 /**
  * Playwright fixtures that collect network requests, console entries,
- * web vitals, and ARIA snapshots during a test.
+ * web vitals, ARIA snapshots, and locator interaction data during a test.
  *
  * Attaches collected data as `piwi-dashboard-*` test-info attachments
  * which the Piwi Dashboard reporter parses on `onTestEnd`.

package/dist/fixtures.js

@@ -3,9 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.dashboardFixtures = void 0;
 exports.extendDashboardFixtures = extendDashboardFixtures;
 const zlib_1 = require("zlib");
+const locator_healing_js_1 = require("./locator-healing.js");
 /**
  * Playwright fixtures that collect network requests, console entries,
- * web vitals, and ARIA snapshots during a test.
+ * web vitals, ARIA snapshots, and locator interaction data during a test.
  *
  * Attaches collected data as `piwi-dashboard-*` test-info attachments
  * which the Piwi Dashboard reporter parses on `onTestEnd`.
@@ -15,6 +16,151 @@ exports.dashboardFixtures = {
         const networkRequests = [];
         const consoleEntries = [];
         const pendingHandlers = [];
+        // ── Locator interaction capture ──────────────────────────────────────
+        // Opt-out: skipped when PIWI_CAPTURE_LOCATORS=false (set automatically when
+        // the reporter's collectPerformanceMetrics / captureLocators is disabled),
+        // so the per-action DOM read + ARIA snapshot cost is never paid when unused.
+        const captureLocators = process.env.PIWI_CAPTURE_LOCATORS !== 'false';
+        const capturedLocators = [];
+        const capturePromises = [];
+        // Locator actions that threw — used at teardown to suggest a fresh locator
+        // from the current page when the element appears renamed/moved.
+        const failedLocators = [];
+        // Chain methods that take args and define a new locator scope (not just narrow).
+        // Origin method/args update to the chain call, e.g. .locator('.item') → locator('.item').
+        // Positional/filter chains that narrow but don't change locator identity.
+        // Origin stays from the page-level call, e.g. .first(), .nth(2), .filter(...).
+        function wrapLocator(locator, originMethod, originArgs) {
+            return new Proxy(locator, {
+                get(target, prop) {
+                    const original = target[prop];
+                    if (typeof original !== 'function')
+                        return original;
+                    if (locator_healing_js_1.CHAIN_METHODS.includes(prop)) {
+                        return (...args) => {
+                            const next = original.apply(target, args);
+                            if (locator_healing_js_1.LOCATOR_CREATING_CHAINS.has(prop)) {
+                                return wrapLocator(next, String(prop), args);
+                            }
+                            return wrapLocator(next, originMethod, originArgs);
+                        };
+                    }
+                    if (!locator_healing_js_1.ACTION_METHODS.includes(prop))
+                        return original;
+                    return async (...callArgs) => {
+                        const seq = capturedLocators.length;
+                        // Capture the test call-site now (sync) so the snapshot's location
+                        // matches the error stack's first user frame — independent of
+                        // pw:api step ordering, worker interleaving, or concurrent actions.
+                        const callerLocation = (0, locator_healing_js_1.captureCallerLocation)();
+                        // Push a placeholder immediately — DOM capture runs async below
+                        capturedLocators.push({
+                            location: callerLocation,
+                            stepIndex: seq,
+                            used: {
+                                method: originMethod,
+                                args: originArgs,
+                                raw: `${originMethod}(${JSON.stringify(originArgs)})`,
+                            },
+                            element: null,
+                            alternatives: [],
+                        });
+                        // The placeholder is already pushed. If the action throws, record
+                        // the failed locator (so teardown can suggest a fresh one for the
+                        // element's current identity) and re-throw so the test still fails.
+                        let result;
+                        try {
+                            result = await original.apply(target, callArgs);
+                        }
+                        catch (err) {
+                            failedLocators.push({ method: originMethod, args: originArgs });
+                            throw err;
+                        }
+                        // Fire-and-forget: capture element data without blocking the test.
+                        // evaluate() can hang when page navigates (element detaches), so
+                        // race it against a 500ms deadline and never throw.
+                        const resolveAttrs = (async () => {
+                            try {
+                                const attrs = (await Promise.race([
+                                    target.evaluate((el, keep) => {
+                                        const attrMap = {};
+                                        for (const key of keep) {
+                                            const v = el.getAttribute(key) ?? el[key];
+                                            attrMap[key] = typeof v === 'string' ? v.slice(0, 200) : v ? String(v).slice(0, 200) : null;
+                                        }
+                                        const r = el.getBoundingClientRect();
+                                        return {
+                                            tagName: el.tagName?.toLowerCase?.() ?? 'unknown',
+                                            attributes: attrMap,
+                                            textContent: (el.textContent || '').trim().slice(0, 80),
+                                            center: {
+                                                x: Math.round(r.x + r.width / 2),
+                                                y: Math.round(r.y + r.height / 2),
+                                            },
+                                        };
+                                    }, [...locator_healing_js_1.CAPTURED_ATTRIBUTES]),
+                                    new Promise((_, reject) => setTimeout(() => reject(new Error('locator capture timeout')), 500)),
+                                ]));
+                                // The browser-computed accessible name only feeds role-based and
+                                // form-field alternatives, so only pay for the extra ARIA
+                                // snapshot when the element actually has a role or is a field.
+                                const role = (0, locator_healing_js_1.resolveAriaRole)({
+                                    tagName: attrs.tagName,
+                                    attributes: attrs.attributes,
+                                    textContent: attrs.textContent,
+                                    accessibleName: null,
+                                    center: attrs.center,
+                                });
+                                const isFormField = ['input', 'select', 'textarea'].includes(attrs.tagName);
+                                // Bound with a timeout: without it, ariaSnapshot waits up to the
+                                // test timeout when the page is mid-navigation, which hangs the
+                                // fixture teardown that drains these capture promises.
+                                const aria = role || isFormField
+                                    ? (await target.ariaSnapshot({ ref: true, timeout: 500 }).catch(() => null))
+                                    : null;
+                                const accessibleName = (0, locator_healing_js_1.extractAccessibleName)(aria) ||
+                                    (0, locator_healing_js_1.approximateAccessibleName)({
+                                        tagName: attrs.tagName,
+                                        attributes: attrs.attributes,
+                                        textContent: attrs.textContent,
+                                        accessibleName: null,
+                                        center: attrs.center,
+                                    });
+                                capturedLocators[seq] = {
+                                    location: callerLocation,
+                                    stepIndex: seq,
+                                    used: {
+                                        method: originMethod,
+                                        args: originArgs,
+                                        raw: `${originMethod}(${JSON.stringify(originArgs)})`,
+                                    },
+                                    element: { ...attrs, accessibleName },
+                                    alternatives: (0, locator_healing_js_1.generateAlternatives)({
+                                        tagName: attrs.tagName,
+                                        attributes: attrs.attributes,
+                                        textContent: attrs.textContent,
+                                        accessibleName,
+                                        center: attrs.center,
+                                    }),
+                                };
+                            }
+                            catch {
+                                // element detached or timeout — keep the placeholder
+                            }
+                        })();
+                        capturePromises.push(resolveAttrs);
+                        return result;
+                    };
+                },
+            });
+        }
+        if (captureLocators) {
+            for (const method of locator_healing_js_1.LOCATOR_METHODS) {
+                const original = page[method].bind(page);
+                page[method] = (...args) => wrapLocator(original(...args), method, args);
+            }
+        }
+        // ── Existing event listeners ──────────────────────────────────────────
         page.on('console', (msg) => {
             const type = msg.type();
             if (['warning', 'error', 'assert'].includes(type)) {
@@ -49,7 +195,13 @@ exports.dashboardFixtures = {
                         resourceType,
                     };
                     if (response) {
-                        const logHeader = response.headers()['x-piwi-logs'];
+                        const headers = response.headers();
+                        // Response content type (without charset/boundary params) — relevant
+                        // per-request metadata for distinguishing API/JSON vs document/HTML calls.
+                        const contentType = headers['content-type'];
+                        if (contentType)
+                            entry.contentType = contentType.split(';')[0].trim();
+                        const logHeader = headers['x-piwi-logs'];
                         if (logHeader) {
                             try {
                                 entry.serverLogs = JSON.parse((0, zlib_1.gunzipSync)(Buffer.from(logHeader, 'base64')).toString('utf-8'));
@@ -72,6 +224,17 @@ exports.dashboardFixtures = {
         // networkRequests — the last request (often the one that failed the test)
         // races with fixture teardown and its serverLogs would otherwise be lost.
         await Promise.allSettled(pendingHandlers);
+        // ── Attach locator snapshots ──────────────────────────────────────────
+        // Cap the drain so a stuck capture (e.g. a navigation in flight) can never
+        // hang teardown past the test timeout; per-action evaluate/ariaSnapshot are
+        // already bounded, this is a backstop.
+        await Promise.race([Promise.allSettled(capturePromises), new Promise((resolve) => setTimeout(resolve, 2000))]);
+        if (capturedLocators.length > 0) {
+            await testInfo.attach('piwi-dashboard-locators', {
+                contentType: 'application/json',
+                body: Buffer.from(JSON.stringify(capturedLocators)),
+            });
+        }
         if (testInfo.status !== 'passed' && testInfo.status !== 'skipped') {
             try {
                 const snapshot = await page.locator(':root').ariaSnapshot();
@@ -80,6 +243,23 @@ exports.dashboardFixtures = {
                         contentType: 'text/plain',
                         body: snapshot,
                     });
+                    // Suggest a fresh locator for the failed action from the current page.
+                    // When the element was renamed/moved, the pre-captured alternatives
+                    // describe the old element, so this points at where it went now — as a
+                    // Playwright annotation (shown in the report + trace) and an attachment
+                    // (shown in the trace viewer). It does NOT change the locator.
+                    const failed = failedLocators[failedLocators.length - 1];
+                    const suggestion = failed ? (0, locator_healing_js_1.suggestLocatorsFromAria)(failed, snapshot) : null;
+                    if (suggestion) {
+                        testInfo.annotations.push({
+                            type: 'piwi-locator-suggestion',
+                            description: `${suggestion.failing} matched nothing on the failing page — the element may have been renamed or moved. Suggested: ${suggestion.suggestions.join('  |  ')}`,
+                        });
+                        await testInfo.attach('piwi-dashboard-locator-suggestion', {
+                            contentType: 'application/json',
+                            body: Buffer.from(JSON.stringify(suggestion)),
+                        });
+                    }
                 }
             }
             catch {

package/dist/helpers.js

@@ -224,28 +224,52 @@ function createLimiter(maxConcurrent) {
  */
 function createGlobalSetup(options, userSetup) {
     return async function globalSetupFn(config) {
-        const opts = (0, config_js_1.resolveOptions)((options ?? {}));
+        const piwiReporterPath = path.resolve(__dirname, 'index.js');
+        // Extract options from the Piwi reporter entry in the Playwright config so
+        // that serverUrl / projectName etc. set inline in the reporters array are
+        // visible here without requiring PIWI_* env vars or a separate wrapConfig call.
+        let inlineReporterOptions = {};
+        if (Array.isArray(config?.reporter)) {
+            for (const r of config.reporter) {
+                if (!Array.isArray(r) || typeof r[0] !== 'string')
+                    continue;
+                const isPiwi = r[0].toLowerCase().includes('piwi') ||
+                    (() => {
+                        try {
+                            return path.resolve(require.resolve(r[0])) === piwiReporterPath;
+                        }
+                        catch {
+                            return false;
+                        }
+                    })();
+                if (isPiwi && r[1] && typeof r[1] === 'object') {
+                    inlineReporterOptions = r[1];
+                    break;
+                }
+            }
+        }
+        const opts = (0, config_js_1.resolveOptions)({ ...inlineReporterOptions, ...(options ?? {}) });
         const logger = new logger_js_1.Logger(opts.verbose ?? false);
-        if (!opts.serverUrl) {
+        if (opts.enabled === false || !opts.serverUrl) {
             logger.info('Not enabled — set PIWI_DASHBOARD_URL or serverUrl to enable.');
             if (userSetup)
                 return userSetup(config);
             return;
         }
-        const piwiReporterPath = path.resolve(__dirname, 'index.js');
-        const hasPiwi = Array.isArray(config?.reporter) &&
-            config.reporter.some((r) => {
-                if (!Array.isArray(r) || typeof r[0] !== 'string')
-                    return false;
-                if (r[0].toLowerCase().includes('piwi'))
-                    return true;
-                try {
-                    return path.resolve(require.resolve(r[0])) === piwiReporterPath;
-                }
-                catch {
-                    return false;
-                }
-            });
+        const hasPiwi = Object.keys(inlineReporterOptions).length > 0 ||
+            (Array.isArray(config?.reporter) &&
+                config.reporter.some((r) => {
+                    if (!Array.isArray(r) || typeof r[0] !== 'string')
+                        return false;
+                    if (r[0].toLowerCase().includes('piwi'))
+                        return true;
+                    try {
+                        return path.resolve(require.resolve(r[0])) === piwiReporterPath;
+                    }
+                    catch {
+                        return false;
+                    }
+                }));
         if (!hasPiwi) {
             logger.debug('Not reporting — Piwi is not in the Playwright reporters list.');
             if (userSetup)

package/dist/index.d.ts

@@ -1,8 +1,6 @@
 import { PiwiDashboardReporter } from './reporter.js';
-import { wrapConfig } from './config-wrapper.js';
-import { createGlobalSetup } from './helpers.js';
-declare const _default: typeof PiwiDashboardReporter & {
-    wrapConfig: typeof wrapConfig;
-    createGlobalSetup: typeof createGlobalSetup;
-};
-export = _default;
+export default PiwiDashboardReporter;
+export { PiwiDashboardReporter };
+export { wrapConfig } from './config-wrapper.js';
+export { createGlobalSetup } from './helpers.js';
+export type { PiwiDashboardOptions, PlaywrightTestConfig } from './config.js';

package/dist/index.js

@@ -1,6 +1,10 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGlobalSetup = exports.wrapConfig = exports.PiwiDashboardReporter = void 0;
 const reporter_js_1 = require("./reporter.js");
-const config_wrapper_js_1 = require("./config-wrapper.js");
-const helpers_js_1 = require("./helpers.js");
-const _default = Object.assign(reporter_js_1.PiwiDashboardReporter, { wrapConfig: config_wrapper_js_1.wrapConfig, createGlobalSetup: helpers_js_1.createGlobalSetup });
-module.exports = _default;
+Object.defineProperty(exports, "PiwiDashboardReporter", { enumerable: true, get: function () { return reporter_js_1.PiwiDashboardReporter; } });
+exports.default = reporter_js_1.PiwiDashboardReporter;
+var config_wrapper_js_1 = require("./config-wrapper.js");
+Object.defineProperty(exports, "wrapConfig", { enumerable: true, get: function () { return config_wrapper_js_1.wrapConfig; } });
+var helpers_js_1 = require("./helpers.js");
+Object.defineProperty(exports, "createGlobalSetup", { enumerable: true, get: function () { return helpers_js_1.createGlobalSetup; } });

package/dist/locator-healing.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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;
+}
+export interface ElementAttributes {
+    tagName: string;
+    attributes: Record<string, string | null>;
+    textContent: string | null;
+    accessibleName: string | null;
+    center: {
+        x: number;
+        y: number;
+    } | null;
+}
+export interface LocatorSnapshot {
+    location: string | null;
+    stepIndex: number;
+    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;
+    } | null;
+    alternatives: RankedLocator[];
+}
+/**
+ * Page-level locator-building methods wrapped by the capture proxy. Imported by
+ * both `reporter/src/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[];
+/**
+ * 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[];
+/** Locator action methods that trigger element capture. */
+export 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[];
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * Extract the accessible name from a YAML-like ariaSnapshot() output.
+ *
+ * Format example:
+ *   - button "Submit order"
+ *   - heading "Welcome, Alice"
+ *   - textbox "Email" [ref=e12]
+ *   - generic
+ *
+ * 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;
+/** A failed locator action, used to suggest a fresh locator from the live page. */
+export interface FailedLocatorInfo {
+    method: string;
+    args: unknown[];
+}
+export 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[];
+}
+/**
+ * Best-effort runtime suggestion for a locator that matched nothing: find the
+ * element on the *current* page that the failed locator most likely targeted
+ * (by accessible name similarity, restricted to the failed role when given) and
+ * return fresh locators for it.
+ *
+ * Unlike the server lookup this has no pre-captured fingerprint — only the
+ * failed locator + the live page — so it's a hint, not a guarantee. Returns null
+ * 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;
+/**
+ * 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
+ * it matches the location format Playwright embeds in error messages — which is
+ * what the server's exact-match healing lookup (`extractErrorLocation`) parses.
+ *
+ * Stamping at action *call* time (rather than correlating with `pw:api` step
+ * indices at step *end* time) avoids three classes of misalignment: `pw:api`
+ * steps with no wrapped locator (e.g. `page.keyboard.press`), cross-worker step
+ * interleaving, and concurrent actions reordering by end time.
+ *
+ * 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(): string | null;