@piwitests/reporter 0.7.0 → 0.9.1

package/README.md

@@ -200,7 +200,7 @@ When `collectCiInfo` is enabled (default), the reporter auto-detects:
 
 ## Requirements
 
-- Node.js 18 or higher
+- Node.js 18 or higher (the reporter runs inside your test project — the dashboard *server* itself targets Node 24+, or use its Docker image)
 - Playwright Test 1.40 or higher
 - Running Piwi Dashboard server
 
@@ -217,9 +217,9 @@ npm run reporter:dev     # watch mode — auto-recompile on changes
 
 ### Source layout
 
-The package keeps its **public API** (`src/index.ts`, `src/fixtures.ts`, `src/public/`) separate from internal plumbing (`src/internal/<domain>/`) and the type model (`src/types/`). See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full map — the public/internal split, the collect-and-submit data flow, the fallback ladder, and the conventions.
+The package keeps its **public API** (`src/index.ts`, `src/public/`) separate from internal plumbing (`src/internal/<domain>/`) and the type model (`src/types/`). See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full map — the public/internal split, the collect-and-submit data flow, the fallback ladder, and the conventions.
 
-The `package.json` `exports` field maps the main entry and `./fixtures` to their `dist/` counterparts.
+Everything public — the reporter, config helpers, and the capture fixtures — is exported from the package's single entry point (`@piwitests/reporter`).
 
 ## Troubleshooting
 

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

@@ -1,4 +1,23 @@
 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
@@ -13,6 +32,15 @@ import type { Fixtures, Locator } from '@playwright/test';
  *   - < 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.
@@ -39,3 +67,4 @@ export declare const dashboardFixtures: Fixtures;
  * ```
  */
 export declare function extendDashboardFixtures<T>(test: T): T;
+export {};

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

@@ -2,6 +2,7 @@
 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");
@@ -75,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.
@@ -140,70 +210,8 @@ function wrapLocator(page, locator, originMethod, originArgs) {
                 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),
+                            target.evaluate(probeElementAttrs, CAPTURED_ATTRS_ARG),
                             new Promise((_, reject) => {
                                 deadline = setTimeout(() => reject(new Error('locator capture timeout')), 500);
                             }),

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.7.0",
+  "version": "0.9.1",
   "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"
   },