@piwitests/reporter 0.4.4 → 0.6.0

package/dist/internal/capture/capture-fixtures.js

@@ -0,0 +1,495 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashboardFixtures = void 0;
+exports.extendDashboardFixtures = extendDashboardFixtures;
+const node_zlib_1 = require("node:zlib");
+const locator_healing_js_1 = require("./locator-healing.js");
+const attachments_js_1 = require("./attachments.js");
+function createSink() {
+    return {
+        networkRequests: [],
+        consoleEntries: [],
+        pendingHandlers: [],
+        capturedLocators: [],
+        capturePromises: [],
+        failedLocators: [],
+        lastActivePage: null,
+    };
+}
+/**
+ * The capture sink for the test currently running in this worker. Playwright
+ * runs a worker's tests sequentially, so a single "current" sink is unambiguous.
+ * It is null between tests and during `beforeAll`/`afterAll` — activity outside a
+ * test (auth setup, teardown) is intentionally not captured.
+ */
+let currentSink = null;
+// Idempotency guards: a page/context/browser can be reached through several
+// paths (browser patch, context patch, the `page` fixture, popup events), and
+// must be wrapped exactly once.
+const INSTRUMENTED_PAGES = new WeakSet();
+const INSTRUMENTED_CONTEXTS = new WeakSet();
+const PATCHED_BROWSERS = new WeakSet();
+// O(1) membership for the proxy `get` trap below, which runs on every property
+// access of every wrapped locator. The source arrays from locator-healing are
+// turned into Sets once here.
+const CHAIN_METHOD_SET = new Set(locator_healing_js_1.CHAIN_METHODS);
+const ACTION_METHOD_SET = new Set(locator_healing_js_1.ACTION_METHODS);
+const FORM_FIELD_TAGS = new Set(['input', 'select', 'textarea']);
+// CAPTURED_ATTRIBUTES is passed verbatim into evaluate() on every action — copy
+// it once instead of spreading a fresh array per call.
+const CAPTURED_ATTRS_ARG = [...locator_healing_js_1.CAPTURED_ATTRIBUTES];
+/**
+ * ARIA snapshot that tolerates every Playwright version the reporter supports,
+ * returning null instead of throwing so a capture can never fail the test. The
+ * options validator runs client-side in the user's installed Playwright, so an
+ * unsupported key surfaces as a rejected promise (not a synchronous throw):
+ *   - ≥ 1.59: `mode: 'ai'` yields the ref-annotated AI snapshot (the ideal);
+ *     `ref` is unknown and silently stripped.
+ *   - 1.52: `mode: 'ai'` fails validation (only 'raw'/'regex' are accepted) and
+ *     rejects; the `{ ref: true }` fallback then yields a ref-annotated snapshot.
+ *   - 1.53–1.58: neither `ref` nor `mode` exists — unknown keys are stripped
+ *     server-side, so the first call already returns a plain flat snapshot.
+ *   - < 1.49: `locator.ariaSnapshot` does not exist — returns null up front.
+ */
+async function ariaSnapshotBestEffort(target, timeout) {
+    // Playwright < 1.49 predates locator.ariaSnapshot entirely.
+    if (typeof target.ariaSnapshot !== 'function')
+        return null;
+    try {
+        return await target.ariaSnapshot({
+            ...(timeout != null ? { timeout } : {}),
+            mode: 'ai',
+        });
+    }
+    catch {
+        // 1.52 rejects `mode: 'ai'`; retry with the `ref` flag that release accepts.
+        try {
+            return await target.ariaSnapshot({
+                ...(timeout != null ? { timeout } : {}),
+                ref: true,
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+}
+// 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(page, locator, originMethod, originArgs) {
+    return new Proxy(locator, {
+        get(target, prop) {
+            const original = Reflect.get(target, prop);
+            if (typeof original !== 'function')
+                return original;
+            const fn = original;
+            if (CHAIN_METHOD_SET.has(prop)) {
+                return (...args) => {
+                    const next = fn.apply(target, args);
+                    if (locator_healing_js_1.LOCATOR_CREATING_CHAINS.has(prop)) {
+                        return wrapLocator(page, next, String(prop), args);
+                    }
+                    return wrapLocator(page, next, originMethod, originArgs);
+                };
+            }
+            if (!ACTION_METHOD_SET.has(prop))
+                return original;
+            return async (...callArgs) => {
+                // Bind to the sink active when the action starts so the async element
+                // capture below writes back to the right test even across a boundary.
+                const sink = currentSink;
+                // Action outside a tracked test (e.g. during beforeAll) — run untouched.
+                if (!sink)
+                    return fn.apply(target, callArgs);
+                sink.lastActivePage = page;
+                const seq = sink.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)();
+                // Built once, shared by the placeholder and the resolved snapshot below.
+                const used = {
+                    method: originMethod,
+                    args: originArgs,
+                    raw: `${originMethod}(${JSON.stringify(originArgs)})`,
+                };
+                // Push a placeholder immediately — DOM capture runs async below
+                sink.capturedLocators.push({
+                    location: callerLocation,
+                    stepIndex: seq,
+                    used,
+                    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 fn.apply(target, callArgs);
+                }
+                catch (error) {
+                    sink.failedLocators.push({ method: originMethod, args: originArgs });
+                    throw error;
+                }
+                // 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 {
+                        // `el` is browser-context (no DOM lib in this Node package), so it
+                        // stays `any`; the callback's return type pins `attrs` to CapturedAttrs.
+                        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),
+                                    },
+                                };
+                            }, CAPTURED_ATTRS_ARG),
+                            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)({ ...attrs, accessibleName: null });
+                        const isFormField = FORM_FIELD_TAGS.has(attrs.tagName);
+                        // Bound with a timeout: without it, ariaSnapshot waits up to the
+                        // test timeout when the page is mid-navigation, which hangs the
+                        // teardown that drains these capture promises.
+                        // ariaSnapshotBestEffort adapts the options to the installed
+                        // Playwright version and never throws (see its doc comment).
+                        const aria = role || isFormField ? await ariaSnapshotBestEffort(target, 500) : null;
+                        const accessibleName = (0, locator_healing_js_1.extractAccessibleName)(aria) || (0, locator_healing_js_1.approximateAccessibleName)({ ...attrs, accessibleName: null });
+                        sink.capturedLocators[seq] = {
+                            location: callerLocation,
+                            stepIndex: seq,
+                            used,
+                            element: { ...attrs, accessibleName },
+                            alternatives: (0, locator_healing_js_1.generateAlternatives)({ ...attrs, accessibleName }),
+                        };
+                    }
+                    catch {
+                        // element detached or timeout — keep the placeholder
+                    }
+                })();
+                sink.capturePromises.push(resolveAttrs);
+                return result;
+            };
+        },
+    });
+}
+/**
+ * Instrument a single page: wrap its locator-building methods for healing
+ * capture and attach console/network listeners. Idempotent — safe to call on a
+ * page already reached through another path (browser patch, `page` fixture).
+ */
+function instrumentPage(page) {
+    if (!page || INSTRUMENTED_PAGES.has(page))
+        return;
+    INSTRUMENTED_PAGES.add(page);
+    // 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';
+    if (captureLocators) {
+        // Locator factories are accessed by dynamic name, so a string-indexed view
+        // of the page is the cleanest local escape hatch from the static surface.
+        const factories = page;
+        for (const method of locator_healing_js_1.LOCATOR_METHODS) {
+            const original = factories[method].bind(page);
+            factories[method] = (...args) => {
+                // Touching a page's locator factory marks it the active page even for
+                // assertion-only tests that never call an action method.
+                if (currentSink)
+                    currentSink.lastActivePage = page;
+                return wrapLocator(page, original(...args), method, args);
+            };
+        }
+    }
+    page.on('console', (msg) => {
+        const sink = currentSink;
+        if (!sink)
+            return;
+        const type = msg.type();
+        if (['warning', 'error', 'assert'].includes(type)) {
+            const location = msg.location();
+            sink.consoleEntries.push({
+                type,
+                text: msg.text(),
+                timestamp: Date.now(),
+                location: location ? `${location.url}:${location.lineNumber}:${location.columnNumber}` : null,
+            });
+        }
+    });
+    page.on('requestfinished', (request) => {
+        const sink = currentSink;
+        if (!sink)
+            return;
+        sink.lastActivePage = page;
+        const p = (async () => {
+            try {
+                const url = request.url();
+                if (url.startsWith('data:') || url.startsWith('blob:'))
+                    return;
+                const timing = request.timing();
+                const response = await request.response();
+                const resourceType = request.resourceType();
+                // Only keep API/document requests; skip static assets (scripts, styles, fonts, images, media)
+                if (!['fetch', 'xhr', 'document', 'other'].includes(resourceType))
+                    return;
+                const entry = {
+                    method: request.method(),
+                    url,
+                    status: response ? response.status() : 0,
+                    duration: timing.responseEnd > 0 ? Math.round(timing.responseEnd - timing.requestStart) : 0,
+                    startTime: timing.startTime,
+                    resourceType,
+                };
+                if (response) {
+                    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, node_zlib_1.gunzipSync)(Buffer.from(logHeader, 'base64')).toString('utf-8'));
+                        }
+                        catch {
+                            /* ignore malformed header */
+                        }
+                    }
+                }
+                sink.networkRequests.push(entry);
+            }
+            catch {
+                /* ignore */
+            }
+        })();
+        sink.pendingHandlers.push(p);
+    });
+}
+/**
+ * Instrument a browser context so every page it opens — via `newPage()` or as a
+ * popup/`window.open` — is captured. Idempotent.
+ */
+function instrumentContext(context) {
+    if (!context || INSTRUMENTED_CONTEXTS.has(context))
+        return;
+    INSTRUMENTED_CONTEXTS.add(context);
+    const originalNewPage = context.newPage.bind(context);
+    context.newPage = async (...args) => {
+        const page = await originalNewPage(...args);
+        instrumentPage(page);
+        return page;
+    };
+    // Popups and pages the context opens on its own (idempotent with the above).
+    context.on('page', (page) => instrumentPage(page));
+}
+/**
+ * Patch a browser so any page or context created directly from it is
+ * instrumented. This is what makes capture work for suites that build their own
+ * pages from the worker-scoped `browser` (e.g. `browser.newPage()` /
+ * `browser.newContext().newPage()`) instead of using the `page` fixture.
+ * Idempotent.
+ */
+function patchBrowser(browser) {
+    if (!browser || PATCHED_BROWSERS.has(browser))
+        return;
+    PATCHED_BROWSERS.add(browser);
+    const originalNewPage = browser.newPage.bind(browser);
+    browser.newPage = async (...args) => {
+        const page = await originalNewPage(...args);
+        instrumentPage(page);
+        return page;
+    };
+    const originalNewContext = browser.newContext.bind(browser);
+    browser.newContext = async (...args) => {
+        const context = await originalNewContext(...args);
+        instrumentContext(context);
+        return context;
+    };
+}
+/**
+ * Drain in-flight capture work and attach the collected `piwi-*` data
+ * to the test. Mirrors the per-test teardown the `page` fixture used to do, but
+ * sourced from the sink so it works regardless of how the test's pages were made.
+ */
+async function flushSink(sink, testInfo) {
+    // Wait for all in-flight requestfinished handlers before snapshotting
+    // networkRequests — the last request (often the one that failed the test)
+    // races with teardown and its serverLogs would otherwise be lost.
+    await Promise.allSettled(sink.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(sink.capturePromises), new Promise((resolve) => setTimeout(resolve, 2000))]);
+    if (sink.capturedLocators.length > 0) {
+        await testInfo.attach(attachments_js_1.ATTACHMENT_NAMES.locators, {
+            contentType: 'application/json',
+            body: Buffer.from(JSON.stringify(sink.capturedLocators)),
+        });
+    }
+    const page = sink.lastActivePage;
+    if (page && testInfo.status !== 'passed' && testInfo.status !== 'skipped') {
+        try {
+            const snapshot = await ariaSnapshotBestEffort(page.locator(':root'));
+            if (snapshot) {
+                await testInfo.attach(attachments_js_1.ATTACHMENT_NAMES.ariaSnapshot, {
+                    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 = sink.failedLocators[sink.failedLocators.length - 1];
+                const suggestion = failed ? (0, locator_healing_js_1.suggestLocatorsFromAria)(failed, snapshot) : null;
+                if (suggestion) {
+                    testInfo.annotations.push({
+                        type: attachments_js_1.LOCATOR_SUGGESTION_ANNOTATION,
+                        description: `${suggestion.failing} matched nothing on the failing page — the element may have been renamed or moved. Suggested: ${suggestion.suggestions.join('  |  ')}`,
+                    });
+                    await testInfo.attach(attachments_js_1.ATTACHMENT_NAMES.locatorSuggestion, {
+                        contentType: 'application/json',
+                        body: Buffer.from(JSON.stringify(suggestion)),
+                    });
+                }
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (sink.consoleEntries.length > 0) {
+        await testInfo.attach(attachments_js_1.ATTACHMENT_NAMES.console, {
+            contentType: 'application/json',
+            body: Buffer.from(JSON.stringify(sink.consoleEntries)),
+        });
+    }
+    if (sink.networkRequests.length > 0) {
+        await testInfo.attach(attachments_js_1.ATTACHMENT_NAMES.network, {
+            contentType: 'application/json',
+            body: Buffer.from(JSON.stringify(sink.networkRequests)),
+        });
+    }
+    if (page) {
+        try {
+            // Runs in the browser, so the perf-entry reads stay `any` (no DOM lib);
+            // the callback return type pins `webVitals` to WebVitals.
+            const webVitals = await page.evaluate(() => {
+                const navEntries = performance.getEntriesByType('navigation');
+                const paintEntries = performance.getEntriesByType('paint');
+                const nav = navEntries[0];
+                const navigation = nav
+                    ? {
+                        url: nav.name,
+                        ttfb: Math.round(nav.responseStart - nav.fetchStart),
+                        domInteractive: Math.round(nav.domInteractive - nav.fetchStart),
+                        domContentLoaded: Math.round(nav.domContentLoadedEventEnd - nav.fetchStart),
+                        loadComplete: Math.round(nav.loadEventEnd - nav.fetchStart),
+                        transferSize: nav.transferSize || 0,
+                        encodedBodySize: nav.encodedBodySize || 0,
+                        decodedBodySize: nav.decodedBodySize || 0,
+                    }
+                    : null;
+                const paint = {};
+                for (const entry of paintEntries) {
+                    const key = entry.name.replace(/-([a-z])/g, (_, l) => l.toUpperCase());
+                    paint[key] = Math.round(entry.startTime);
+                }
+                if (!navigation && Object.keys(paint).length === 0)
+                    return null;
+                return { navigation, paint };
+            });
+            if (webVitals) {
+                await testInfo.attach(attachments_js_1.ATTACHMENT_NAMES.webVitals, {
+                    contentType: 'application/json',
+                    body: Buffer.from(JSON.stringify(webVitals)),
+                });
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/**
+ * Playwright fixtures that collect network requests, console entries,
+ * web vitals, ARIA snapshots, and locator interaction data during a test.
+ *
+ * Capture is wired at the `browser` level, so it works whether a test uses the
+ * standard `page` fixture or builds its own pages from `browser` /
+ * `browser.newContext()`. Collected data is attached as `piwi-*`
+ * test-info attachments which the Piwi Dashboard reporter parses on `onTestEnd`.
+ */
+exports.dashboardFixtures = {
+    // Worker-scoped: patch the shared browser so every page/context created from
+    // it — including by user fixtures that take `browser` directly — is captured.
+    browser: [
+        async ({ browser }, use) => {
+            patchBrowser(browser);
+            await use(browser);
+        },
+        { scope: 'worker' },
+    ],
+    // Safety net for the standard `page` fixture, in case its page is created
+    // through an internal path the browser patch doesn't see. Idempotent, so it
+    // never double-wraps a page the browser patch already instrumented.
+    page: async ({ page }, use) => {
+        instrumentPage(page);
+        await use(page);
+    },
+    // Auto, test-scoped: open a capture sink for the running test and flush it
+    // (attach the collected data) at teardown. Runs for every test without being
+    // requested, so suites that never destructure `page` are still captured.
+    piwiDashboardCapture: [
+        async ({}, use, testInfo) => {
+            const sink = createSink();
+            currentSink = sink;
+            try {
+                await use();
+            }
+            finally {
+                currentSink = null;
+                await flushSink(sink, testInfo);
+            }
+        },
+        { auto: true },
+    ],
+};
+/**
+ * Extend a Playwright `test` object with Piwi Dashboard fixtures.
+ *
+ * Use this instead of importing `@playwright/test` directly from this package
+ * to avoid the "Requiring @playwright/test second time" error caused by
+ * duplicate module resolution.
+ *
+ * @example
+ * ```ts
+ * import { test as base } from '@playwright/test';
+ * import { extendDashboardFixtures } from '@piwitests/reporter';
+ *
+ * export const test = extendDashboardFixtures(base);
+ * ```
+ */
+function extendDashboardFixtures(test) {
+    return test.extend(exports.dashboardFixtures);
+}

package/dist/internal/capture/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;