@piwitests/reporter 0.6.0 → 0.7.0

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

@@ -1,4 +1,18 @@
-import type { Fixtures } from '@playwright/test';
+import type { Fixtures, Locator } from '@playwright/test';
+/**
+ * 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>;
 /**
  * Playwright fixtures that collect network requests, console entries,
  * web vitals, ARIA snapshots, and locator interaction data during a test.

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

@@ -1,6 +1,7 @@
 "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");
@@ -118,7 +119,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,6 +138,7 @@ 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.
@@ -149,17 +150,63 @@ function wrapLocator(page, locator, originMethod, originArgs) {
                                     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,
-                                    textContent: (el.textContent || '').trim().slice(0, 80),
+                                    // 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) => setTimeout(() => reject(new Error('locator capture timeout')), 500)),
+                            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 +222,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 +396,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piwitests/reporter",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Playwright reporter for sending test results to Piwi Dashboard",
   "url": "https://github.com/PiwiTests/platform",
   "homepage": "https://piwitests.github.io",