@piwitests/reporter 0.6.0 → 0.9.0

package/dist/internal/capture/capture-fixtures.d.ts

@@ -1,4 +1,46 @@
-import type { Fixtures } from '@playwright/test';
+import type { Fixtures, Locator } from '@playwright/test';
+/** Shape returned by the in-page element probe (see `wrapLocator`). */
+interface CapturedAttrs {
+    tagName: string;
+    attributes: Record<string, string | null>;
+    textContent: string;
+    center: {
+        x: number;
+        y: number;
+    };
+    /** True when the element has an associated <label> — gates getByLabel. */
+    hasLabel: boolean;
+    /** querySelectorAll match counts for candidate selectors (uniqueness probe). */
+    selectorCounts: {
+        testId?: number;
+        id?: number;
+        name?: number;
+        classes?: Record<string, number>;
+    };
+}
+/**
+ * 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.
+ */
+export declare function ariaSnapshotBestEffort(target: Locator, timeout?: number): Promise<string | null>;
+/**
+ * Runs inside the browser via `evaluate()` — probes a captured element for its
+ * attributes, geometry, label association, and selector-uniqueness counts.
+ * Must stay a fully self-contained function (no references to this module's
+ * closure): Playwright serializes it and executes it in the page, browser-side.
+ * `el` is browser-context (no DOM lib in this Node package), hence `any`.
+ * Exported for unit testing; still passed directly to `evaluate()` below.
+ */
+export declare function probeElementAttrs(el: any, keep: string[]): CapturedAttrs;
 /**
  * Playwright fixtures that collect network requests, console entries,
  * web vitals, ARIA snapshots, and locator interaction data during a test.
@@ -25,3 +67,4 @@ export declare const dashboardFixtures: Fixtures;
  * ```
  */
 export declare function extendDashboardFixtures<T>(test: T): T;
+export {};

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

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dashboardFixtures = void 0;
+exports.ariaSnapshotBestEffort = ariaSnapshotBestEffort;
+exports.probeElementAttrs = probeElementAttrs;
 exports.extendDashboardFixtures = extendDashboardFixtures;
 const node_zlib_1 = require("node:zlib");
 const locator_healing_js_1 = require("./locator-healing.js");
@@ -74,6 +76,75 @@ async function ariaSnapshotBestEffort(target, timeout) {
         }
     }
 }
+/**
+ * Runs inside the browser via `evaluate()` — probes a captured element for its
+ * attributes, geometry, label association, and selector-uniqueness counts.
+ * Must stay a fully self-contained function (no references to this module's
+ * closure): Playwright serializes it and executes it in the page, browser-side.
+ * `el` is browser-context (no DOM lib in this Node package), hence `any`.
+ * Exported for unit testing; still passed directly to `evaluate()` below.
+ */
+function probeElementAttrs(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,
+    };
+}
 // 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.
@@ -118,7 +189,6 @@ function wrapLocator(page, locator, originMethod, originArgs) {
                 // Push a placeholder immediately — DOM capture runs async below
                 sink.capturedLocators.push({
                     location: callerLocation,
-                    stepIndex: seq,
                     used,
                     element: null,
                     alternatives: [],
@@ -138,28 +208,13 @@ function wrapLocator(page, locator, originMethod, originArgs) {
                 // 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();
-                                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)),
+                            target.evaluate(probeElementAttrs, 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
@@ -175,15 +230,25 @@ function wrapLocator(page, locator, originMethod, originArgs) {
                         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 },
+                            // 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;
@@ -339,11 +404,21 @@ async function flushSink(sink, testInfo) {
     // 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))]);
+    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',
-            body: Buffer.from(JSON.stringify(sink.capturedLocators)),
+            // 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;

package/dist/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

package/dist/internal/capture/locator-healing.js

@@ -34,15 +34,42 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CAPTURED_ATTRIBUTES = exports.LOCATOR_CREATING_CHAINS = exports.ACTION_METHODS = exports.CHAIN_METHODS = exports.LOCATOR_METHODS = void 0;
+exports.dedupeSnapshotsByLocation = dedupeSnapshotsByLocation;
 exports.resolveAriaRole = resolveAriaRole;
 exports.generateAlternatives = generateAlternatives;
 exports.classifyCssStability = classifyCssStability;
 exports.isAutoGenerated = isAutoGenerated;
 exports.extractAccessibleName = extractAccessibleName;
 exports.approximateAccessibleName = approximateAccessibleName;
+exports.parseAriaRoleName = parseAriaRoleName;
+exports.nameSimilarity = nameSimilarity;
 exports.suggestLocatorsFromAria = suggestLocatorsFromAria;
 exports.captureCallerLocation = captureCallerLocation;
 const path = __importStar(require("node:path"));
+/**
+ * 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.
+ */
+function dedupeSnapshotsByLocation(snaps) {
+    const lastWithElement = new Map();
+    const lastAny = new Map();
+    snaps.forEach((s, i) => {
+        if (!s.location)
+            return;
+        lastAny.set(s.location, i);
+        if (s.element)
+            lastWithElement.set(s.location, i);
+    });
+    return snaps.filter((s, i) => {
+        if (!s.location)
+            return true;
+        return (lastWithElement.get(s.location) ?? lastAny.get(s.location)) === i;
+    });
+}
 // ── Playwright method surface (shared with the fixture proxy) ────────────────
 /**
  * Page-level locator-building methods wrapped by the capture proxy. Imported by
@@ -92,12 +119,18 @@ exports.ACTION_METHODS = [
     'hover',
     'press',
     'type',
+    'pressSequentially',
     'clear',
     'setInputFiles',
     'dragTo',
     'focus',
     'blur',
     'scrollIntoViewIfNeeded',
+    'dispatchEvent',
+    'selectText',
+    // Not an action, but a successful waitFor proves the element resolved — the
+    // closest capture hook available for assertion-style usage of a locator.
+    'waitFor',
 ];
 /** Chain methods that create a new locator scope (origin tracks the chain call). */
 exports.LOCATOR_CREATING_CHAINS = new Set(exports.LOCATOR_METHODS);
@@ -118,7 +151,11 @@ exports.CAPTURED_ATTRIBUTES = [
     'role',
     'type',
     'href',
-    'value',
+    // `multiple` distinguishes listbox vs combobox for <select>. `value` is
+    // deliberately NOT captured: no alternative generator uses it, and reading
+    // the live value after fill() would leak user-typed secrets (passwords,
+    // tokens) into the snapshot payload and server storage.
+    'multiple',
 ];
 // ── ARIA role resolution ─────────────────────────────────────────────────────
 /** Implicit ARIA role for an HTML tag (when no explicit `role` is set). */
@@ -142,7 +179,6 @@ const TAG_TO_ROLE = {
     output: 'status',
     progress: 'progressbar',
     meter: 'meter',
-    select: 'listbox',
     textarea: 'textbox',
     h1: 'heading',
     h2: 'heading',
@@ -189,6 +225,11 @@ function resolveAriaRole(attrs) {
         const type = (attrs.attributes['type'] ?? 'text').toLowerCase();
         return INPUT_TYPE_TO_ROLE[type] ?? 'textbox';
     }
+    // A plain <select> is a combobox; only with `multiple` (or size > 1, not
+    // captured) does it become a listbox. Matches the server's implicitRoleForTag.
+    if (tag === 'select') {
+        return attrs.attributes['multiple'] != null ? 'listbox' : 'combobox';
+    }
     if (tag === 'a') {
         return attrs.attributes['href'] != null ? 'link' : null;
     }
@@ -197,6 +238,10 @@ function resolveAriaRole(attrs) {
 // ── Alternative generation ───────────────────────────────────────────────────
 const attr = (a, key) => a.attributes[key] || null;
 const esc = (s) => s.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+/** Escape a value for use inside a double-quoted CSS attribute selector. */
+const escCssAttrValue = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+/** An id usable as a bare `#id` CSS selector without escaping (framework ids like `:r3:` are not). */
+const isCssSafeId = (id) => /^[A-Za-z][A-Za-z0-9_-]*$/.test(id);
 /**
  * Build a ranked list of alternative locators from the captured element
  * attributes. The list is sorted descending by stability score.
@@ -216,9 +261,17 @@ function generateAlternatives(attrs) {
     const { accessibleName } = attrs;
     const tag = attrs.tagName;
     const role = resolveAriaRole(attrs);
+    // A probed count > 1 means the selector matches several elements on the
+    // captured page — a strict-mode violation, so the alternative is suppressed.
+    // Unknown counts (probe absent/failed) keep the alternative.
+    const counts = attrs.selectorCounts;
+    const isUnique = (n) => n == null || n <= 1;
+    // Collapse whitespace: multi-line/indented textContent would otherwise
+    // produce a getByText with literal newlines — invalid when pasted as code.
+    const text = attrs.textContent ? attrs.textContent.replace(/\s+/g, ' ').trim() : null;
     // 1. data-testid — highest stability (100)
     const testId = attr(attrs, 'data-testid');
-    if (testId) {
+    if (testId && isUnique(counts?.testId)) {
         add({
             locator: `getByTestId('${esc(testId)}')`,
             method: 'getByTestId',
@@ -245,14 +298,22 @@ function generateAlternatives(attrs) {
             score: 85,
         });
     }
-    // 4. getByLabel — for form fields with associated <label> (85)
+    // 4. getByLabel — for form fields (85). getByLabel only matches a real
+    // <label> association or aria-label — but the accessible name may have been
+    // computed (or approximated) from placeholder/title, where getByLabel would
+    // match nothing. Only emit when a label/aria-label actually backs the name;
+    // legacy payloads without the hasLabel probe keep the old permissive behavior.
     if (accessibleName && ['input', 'select', 'textarea'].includes(tag)) {
-        add({
-            locator: `getByLabel('${esc(accessibleName)}')`,
-            method: 'getByLabel',
-            args: { label: accessibleName },
-            score: 85,
-        });
+        const label = attr(attrs, 'aria-label');
+        const labelBacked = attrs.hasLabel === undefined ? true : attrs.hasLabel === true || label === accessibleName;
+        if (labelBacked) {
+            add({
+                locator: `getByLabel('${esc(accessibleName)}')`,
+                method: 'getByLabel',
+                args: { label: accessibleName },
+                score: 85,
+            });
+        }
     }
     // 5. getByPlaceholder — for inputs (80)
     const placeholder = attr(attrs, 'placeholder');
@@ -265,31 +326,35 @@ function generateAlternatives(attrs) {
         });
     }
     // 6. getByText — from visible text content (70-80)
-    if (attrs.textContent && attrs.textContent.length < 80) {
+    if (text && text.length < 80) {
         add({
-            locator: `getByText('${esc(attrs.textContent)}')`,
+            locator: `getByText('${esc(text)}')`,
             method: 'getByText',
-            args: { text: attrs.textContent },
+            args: { text },
             score: 75,
         });
     }
-    // 7. locator('#id') — if id exists and doesn't look auto-generated (50-70)
+    // 7. locator('#id') — if id exists and doesn't look auto-generated (50-70).
+    // Framework ids that aren't valid bare CSS identifiers (React useId's
+    // `:r3:`, ids with dots) fall back to an attribute selector.
     const id = attr(attrs, 'id');
-    if (id && !isAutoGenerated(id)) {
+    if (id && !isAutoGenerated(id) && isUnique(counts?.id)) {
+        const selector = isCssSafeId(id) ? `#${id}` : `[id="${escCssAttrValue(id)}"]`;
         add({
-            locator: `locator('#${esc(id)}')`,
+            locator: `locator('${esc(selector)}')`,
             method: 'locator',
-            args: { selector: `#${id}` },
+            args: { selector },
             score: 65,
         });
     }
     // 8. locator('[name="..."]') — for form elements (60)
     const name = attr(attrs, 'name');
-    if (name) {
+    if (name && isUnique(counts?.name)) {
+        const selector = `[name="${escCssAttrValue(name)}"]`;
         add({
-            locator: `locator('[name="${esc(name)}"]')`,
+            locator: `locator('${esc(selector)}')`,
             method: 'locator',
-            args: { selector: `[name="${name}"]` },
+            args: { selector },
             score: 60,
         });
     }
@@ -313,12 +378,15 @@ function generateAlternatives(attrs) {
             score: 50,
         });
     }
-    // 11. CSS class-based locators — capped at 3 most stable classes
+    // 11. CSS class-based locators — capped at 3 most stable classes; classes
+    // the uniqueness probe saw on more than one element are dropped outright.
     const clsStr = attr(attrs, 'class');
     if (clsStr) {
         const classes = clsStr
             .split(/\s+/)
-            .filter((c) => c.length > 1)
+            // Only classes valid as a bare `.cls` selector — Tailwind variants
+            // (`hover:bg-red-500`) and arbitrary values (`w-[10px]`) are not.
+            .filter((c) => c.length > 1 && /^[A-Za-z_-][A-Za-z0-9_-]*$/.test(c) && isUnique(counts?.classes?.[c]))
             .map((cls) => ({
             cls,
             score: classifyCssStability(cls),
@@ -395,6 +463,12 @@ function isAutoGenerated(value) {
     // Angular-style generated IDs (ng-xxx-N)
     if (value.startsWith('ng-'))
         return true;
+    // Component-library generated ids (Radix, Headless UI, MUI, Mantine, Chakra)
+    if (/^(radix-|headlessui-|mui-|mantine-|chakra-)/i.test(value))
+        return true;
+    // React useId format — `:r1:` (18) / `«r1»` (19)
+    if (/^:r[0-9a-z]+:$/i.test(value) || /^«r[0-9a-z]+»$/i.test(value))
+        return true;
     return false;
 }
 // ── Accessible name extraction ───────────────────────────────────────────────
@@ -448,7 +522,11 @@ const NAME_BASED_METHODS = new Set([
     'getByAltText',
 ]);
 const escAttr = (s) => s.replaceAll('\\', '\\\\').replaceAll("'", "\\'");
-/** Parse `ariaSnapshot()` lines into role/name pairs (mirrors the server-side matcher). */
+/**
+ * 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.
+ */
 function parseAriaRoleName(ariaSnapshot) {
     const out = [];
     for (const line of ariaSnapshot.split('\n')) {
@@ -467,7 +545,8 @@ function parseAriaRoleName(ariaSnapshot) {
  * 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.
+ * shared/ code, so keep the two implementations in sync by hand. Exported so
+ * the dashboard's drift-guard unit test can compare the two.
  */
 function nameSimilarity(a, b) {
     const tok = (s) => new Set((s ?? '')

package/dist/internal/streaming/stream-manager.d.ts

@@ -66,7 +66,7 @@ export declare class StreamManager {
      */
     constructor(httpClient: HttpClient, streamBuffer: StreamBuffer, recovery: CrashRecovery, uploader: Uploader, fileHandler: FileHandler, options: PiwiDashboardOptions, logger?: Logger);
     /** Begin the streaming session after `onBegin` fires. Non-blocking — the actual handshake runs asynchronously. */
-    start(startTime: string, metadata: Record<string, any>, instanceId: string, playwrightVersion?: string | null, shardInfo?: ShardInfo | null, isFullRun?: boolean, filterDetails?: FilterDetails | null): void;
+    start(startTime: string, metadata: Record<string, any>, instanceId: string, playwrightVersion?: string | null, reporterVersion?: string | null, shardInfo?: ShardInfo | null, isFullRun?: boolean, filterDetails?: FilterDetails | null): void;
     private _doStart;
     /** Queue a test-case `begin` event. Held in a pre-start buffer if the stream is not yet open, then prepended so it arrives before the matching `complete` event. */
     queueBeginEvent(event: StreamEvent): void;

package/dist/internal/streaming/stream-manager.js

@@ -111,10 +111,10 @@ class StreamManager {
         this._startPromise = null;
     }
     /** Begin the streaming session after `onBegin` fires. Non-blocking — the actual handshake runs asynchronously. */
-    start(startTime, metadata, instanceId, playwrightVersion, shardInfo, isFullRun, filterDetails) {
-        this._startPromise = this._doStart(startTime, metadata, instanceId, playwrightVersion, shardInfo, isFullRun, filterDetails);
+    start(startTime, metadata, instanceId, playwrightVersion, reporterVersion, shardInfo, isFullRun, filterDetails) {
+        this._startPromise = this._doStart(startTime, metadata, instanceId, playwrightVersion, reporterVersion, shardInfo, isFullRun, filterDetails);
     }
-    async _doStart(startTime, metadata, instanceId, playwrightVersion, shardInfo, isFullRun, filterDetails) {
+    async _doStart(startTime, metadata, instanceId, playwrightVersion, reporterVersion, shardInfo, isFullRun, filterDetails) {
         const setupInfo = (0, setup_file_js_1.readSetupInfo)(this.options.projectName);
         try {
             this._auth = await this.httpClient.resolveAuth(this.options);
@@ -129,6 +129,7 @@ class StreamManager {
                         totalTests: 0,
                         metadata,
                         playwrightVersion,
+                        reporterVersion,
                         shardIndex,
                         shardTotal,
                         isFullRun,
@@ -150,6 +151,7 @@ class StreamManager {
                         metadata,
                         instanceId,
                         playwrightVersion,
+                        reporterVersion,
                         shardIndex,
                         shardTotal,
                         isFullRun,
@@ -167,6 +169,7 @@ class StreamManager {
                     metadata,
                     instanceId,
                     playwrightVersion,
+                    reporterVersion,
                     shardIndex,
                     shardTotal,
                     isFullRun,

package/dist/internal/submit/run-submitter.d.ts

@@ -16,6 +16,7 @@ export interface CollectedRun {
     testCases: CollectedTestCase[];
     startTime: string | null;
     playwrightVersion: string | null;
+    reporterVersion: string | null;
     totalTests: number;
     passedTests: number;
     failedTests: number;

package/dist/internal/submit/run-submitter.js

@@ -97,6 +97,7 @@ class RunSubmitter {
             metadata: run.metadata,
             instanceId: run.instanceId,
             playwrightVersion: run.playwrightVersion ?? undefined,
+            reporterVersion: run.reporterVersion ?? undefined,
             testCases: run.testCases,
             shardIndex: run.shardInfo?.current,
             shardTotal: run.shardInfo?.total,
@@ -126,6 +127,7 @@ class RunSubmitter {
                 metadata: run.metadata,
                 hasPendingUploads: this.hasReports(run),
                 playwrightVersion: run.playwrightVersion ?? undefined,
+                reporterVersion: run.reporterVersion ?? undefined,
                 setupSteps: run.setupSteps.length > 0 ? run.setupSteps : undefined,
                 isFullRun: run.isFullRun,
                 filterDetails: run.filterDetails ?? null,

package/dist/internal/submit/serializer.js

@@ -94,6 +94,7 @@ function serializeRun(payload, opts) {
         metadata: payload.metadata,
         instanceId: payload.instanceId,
         playwrightVersion: payload.playwrightVersion,
+        reporterVersion: payload.reporterVersion,
         shardIndex: payload.shardIndex,
         shardTotal: payload.shardTotal,
         isFullRun: payload.isFullRun ?? true,

package/dist/internal/submit/uploader.d.ts

@@ -33,6 +33,8 @@ export interface RunPayload {
     testCases: CollectedTestCase[];
     /** Playwright framework version used for this run */
     playwrightVersion?: string;
+    /** Piwi reporter package version that produced this run */
+    reporterVersion?: string;
     /** 1-based shard index (e.g. 1, 2, 3) */
     shardIndex?: number;
     /** Total number of shards (e.g. 3) */

package/dist/internal/support/reporter-version.d.ts

@@ -0,0 +1,2 @@
+/** Read the reporter package's own version from `package.json`, memoized. Falls back to `'unknown'` if it can't be read (e.g. an unusual install layout). */
+export declare function getReporterVersion(): string;

package/dist/internal/support/reporter-version.js

@@ -0,0 +1,54 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getReporterVersion = getReporterVersion;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+let cachedVersion = null;
+/** Read the reporter package's own version from `package.json`, memoized. Falls back to `'unknown'` if it can't be read (e.g. an unusual install layout). */
+function getReporterVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    try {
+        const pkgPath = path.resolve(__dirname, '../../../package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        const version = pkg.version;
+        cachedVersion = typeof version === 'string' ? version : 'unknown';
+    }
+    catch {
+        cachedVersion = 'unknown';
+    }
+    return cachedVersion;
+}

package/dist/public/reporter.d.ts

@@ -14,6 +14,7 @@ export declare class PiwiDashboardReporter {
     private testCases;
     private startTime;
     private playwrightVersion;
+    private readonly reporterVersion;
     private totalTests;
     private passedTests;
     private failedTests;

package/dist/public/reporter.js

@@ -46,6 +46,7 @@ const metadata_collector_js_1 = require("../internal/collect/metadata-collector.
 const stream_manager_js_1 = require("../internal/streaming/stream-manager.js");
 const step_analyzer_js_1 = require("../internal/collect/step-analyzer.js");
 const instance_id_js_1 = require("../internal/support/instance-id.js");
+const reporter_version_js_1 = require("../internal/support/reporter-version.js");
 const source_snippet_js_1 = require("../internal/support/source-snippet.js");
 const ci_js_1 = require("../internal/support/ci.js");
 const worker_index_js_1 = require("../internal/support/worker-index.js");
@@ -79,6 +80,7 @@ class PiwiDashboardReporter {
         this.testCases = [];
         this.startTime = null;
         this.playwrightVersion = null;
+        this.reporterVersion = (0, reporter_version_js_1.getReporterVersion)();
         this.totalTests = 0;
         this.passedTests = 0;
         this.failedTests = 0;
@@ -154,7 +156,7 @@ class PiwiDashboardReporter {
             this.shardInfo = { current: pwShard.current, total: pwShard.total };
             this.logger.info(`Shard ${this.shardInfo.current}/${this.shardInfo.total} detected`);
         }
-        this.streamManager?.start(this.startTime, this.metadata, this.instanceId, this.playwrightVersion, this.shardInfo, this.isFullRun, this.filterDetails);
+        this.streamManager?.start(this.startTime, this.metadata, this.instanceId, this.playwrightVersion, this.reporterVersion, this.shardInfo, this.isFullRun, this.filterDetails);
     }
     /** Playwright reporter hook: called when an individual test begins */
     onTestBegin(test, result) {
@@ -353,6 +355,7 @@ class PiwiDashboardReporter {
             testCases: this.testCases,
             startTime: this.startTime,
             playwrightVersion: this.playwrightVersion,
+            reporterVersion: this.reporterVersion,
             totalTests: this.totalTests,
             passedTests: this.passedTests,
             failedTests: this.failedTests,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piwitests/reporter",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "Playwright reporter for sending test results to Piwi Dashboard",
   "url": "https://github.com/PiwiTests/platform",
   "homepage": "https://piwitests.github.io",
@@ -41,7 +41,9 @@
     "reporter:lint": "oxlint --config oxlint.config.mts .",
     "reporter:lint:fix": "oxlint --config oxlint.config.mts . --fix",
     "reporter:test": "vitest run",
+    "reporter:test:coverage": "vitest run --coverage",
     "reporter:test:watch": "vitest",
+    "reporter:test:integration": "npm run reporter:build && playwright test --config=tests/integration/playwright.config.ts",
     "test": "npm run reporter:test",
     "prepublishOnly": "npm run reporter:build"
   },