@piwitests/reporter 0.5.0 → 0.7.0

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

@@ -0,0 +1,562 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashboardFixtures = void 0;
+exports.ariaSnapshotBestEffort = ariaSnapshotBestEffort;
+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,
+                    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 () => {
+                    let deadline;
+                    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();
+                                // Uniqueness probe: how many elements each candidate selector
+                                // matches. A count > 1 marks the alternative as ambiguous
+                                // (strict-mode violation) so generateAlternatives drops it.
+                                // All DOM/CSS access goes through `el` (no DOM lib here).
+                                const selectorCounts = {};
+                                try {
+                                    const doc = el.ownerDocument;
+                                    const cssEsc = (s) => doc.defaultView.CSS.escape(s);
+                                    const count = (sel) => {
+                                        try {
+                                            return doc.querySelectorAll(sel).length;
+                                        }
+                                        catch {
+                                            return undefined;
+                                        }
+                                    };
+                                    if (attrMap['data-testid']) {
+                                        selectorCounts.testId = count(`[data-testid=${JSON.stringify(attrMap['data-testid'])}]`);
+                                    }
+                                    if (attrMap['id'])
+                                        selectorCounts.id = count(`#${cssEsc(attrMap['id'])}`);
+                                    if (attrMap['name'])
+                                        selectorCounts.name = count(`[name=${JSON.stringify(attrMap['name'])}]`);
+                                    const classList = (attrMap['class'] || '')
+                                        .split(/\s+/)
+                                        .filter((c) => c.length > 1)
+                                        .slice(0, 10);
+                                    if (classList.length > 0) {
+                                        const classCounts = {};
+                                        for (const cls of classList) {
+                                            const n = count(`.${cssEsc(cls)}`);
+                                            if (n !== undefined)
+                                                classCounts[cls] = n;
+                                        }
+                                        selectorCounts.classes = classCounts;
+                                    }
+                                }
+                                catch {
+                                    // Uniqueness probing is best-effort — never fail the capture.
+                                }
+                                return {
+                                    tagName: el.tagName?.toLowerCase?.() ?? 'unknown',
+                                    attributes: attrMap,
+                                    // Collapse whitespace so multi-line text can't produce a
+                                    // getByText suggestion with literal newlines in it.
+                                    textContent: (el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 80),
+                                    center: {
+                                        x: Math.round(r.x + r.width / 2),
+                                        y: Math.round(r.y + r.height / 2),
+                                    },
+                                    hasLabel: !!(el.labels && el.labels.length > 0),
+                                    selectorCounts,
+                                };
+                            }, CAPTURED_ATTRS_ARG),
+                            new Promise((_, reject) => {
+                                deadline = 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,
+                            used,
+                            // hasLabel/selectorCounts inform alternative generation only —
+                            // keep the stored element to the wire shape.
+                            element: {
+                                tagName: attrs.tagName,
+                                attributes: attrs.attributes,
+                                textContent: attrs.textContent,
+                                accessibleName,
+                                center: attrs.center,
+                            },
+                            alternatives: (0, locator_healing_js_1.generateAlternatives)({ ...attrs, accessibleName }),
+                        };
+                    }
+                    catch {
+                        // element detached or timeout — keep the placeholder
+                    }
+                    finally {
+                        clearTimeout(deadline);
+                    }
+                })();
+                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.
+    let drainDeadline;
+    await Promise.race([
+        Promise.allSettled(sink.capturePromises),
+        new Promise((resolve) => {
+            drainDeadline = setTimeout(resolve, 2000);
+        }),
+    ]);
+    clearTimeout(drainDeadline);
+    if (sink.capturedLocators.length > 0) {
+        await testInfo.attach(attachments_js_1.ATTACHMENT_NAMES.locators, {
+            contentType: 'application/json',
+            // Repeated call sites (loops) keep only their latest capture — the
+            // server stores one row per location anyway, so shipping every
+            // iteration is pure payload bloat.
+            body: Buffer.from(JSON.stringify((0, locator_healing_js_1.dedupeSnapshotsByLocation)(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/{locator-healing.d.ts → internal/capture/locator-healing.d.ts}

@@ -11,6 +11,18 @@ export interface RankedLocator {
     /** 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>;
+}
 export interface ElementAttributes {
     tagName: string;
     attributes: Record<string, string | null>;
@@ -20,10 +32,18 @@ export interface ElementAttributes {
         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;
 }
 export interface LocatorSnapshot {
     location: string | null;
-    stepIndex: number;
     used: {
         method: string;
         args: unknown[];
@@ -41,6 +61,15 @@ export interface LocatorSnapshot {
     } | 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
+ * the server keeps only the latest per location anyway. Keeps the last
+ * element-bearing snapshot per location — falling back to the last placeholder
+ * 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[];
 /**
  * Page-level locator-building methods wrapped by the capture proxy. Imported by
  * both `reporter/src/fixtures.ts` and the dogfooding `application/tests/fixtures.ts`
@@ -123,6 +152,23 @@ export interface LocatorSuggestion {
     /** 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;
+}>;
+/**
+ * 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;
 /**
  * Best-effort runtime suggestion for a locator that matched nothing: find the
  * element on the *current* page that the failed locator most likely targeted