@piwitests/reporter 0.9.1 → 0.12.0

package/README.md

@@ -39,6 +39,19 @@ Run your tests — results are uploaded automatically:
 npx playwright test
 ```
 
+**Recommended: enable the [capture fixtures](#capture-fixtures)** — one small file unlocks the dashboard's richest features (locator healing, slow-endpoint analysis, Web Vitals, console capture, failure-time ARIA snapshots):
+
+```typescript
+// tests/fixtures.ts
+import { test as base, expect } from '@playwright/test'
+import { piwiFixtures } from '@piwitests/reporter'
+
+export const test = base.extend(piwiFixtures)
+export { expect }
+```
+
+Import `test` from this file in your specs instead of `@playwright/test` — see [Capture fixtures](#capture-fixtures) below.
+
 Prefer to wire it up by hand? Add the reporter to the `reporter` array instead:
 
 ```typescript
@@ -123,35 +136,42 @@ export default defineConfig({
 })
 ```
 
-## Performance Metrics & Web Vitals
+## Capture fixtures
 
-To capture network request timing and browser Web Vitals, use the provided fixtures:
+The reporter works without any test-code changes, but the **capture fixtures** observe your tests from the inside and unlock the dashboard's richest features. Extend your `test` with them:
 
 ```typescript
 // tests/fixtures.ts
 import { test as base, expect } from '@playwright/test'
-import { dashboardFixtures } from '@piwitests/reporter'
+import { piwiFixtures } from '@piwitests/reporter'
 
-export const test = base.extend(dashboardFixtures)
+export const test = base.extend(piwiFixtures)
 export { expect }
 ```
 
-Or extend the base `test` in one line with `extendDashboardFixtures`:
+Or extend the base `test` in one line with `extendPiwiFixtures`:
 
 ```typescript
 import { test as base } from '@playwright/test'
-import { extendDashboardFixtures } from '@piwitests/reporter'
+import { extendPiwiFixtures } from '@piwitests/reporter'
 
-export const test = extendDashboardFixtures(base)
+export const test = extendPiwiFixtures(base)
 export { expect } from '@playwright/test'
 ```
 
+Then import `test` from your fixtures file in every spec — a spec that imports `test` from `@playwright/test` directly still runs and reports fine, it just isn't captured.
+
 ### What gets captured
 
-- **Network requests** — method, URL, status, duration, resource type. Aggregated on the dashboard into a *Slow API Endpoints* table grouped by `METHOD + normalized route`.
+- **Network requests** — method, URL, status, duration, resource type (API/document traffic only). Aggregated on the dashboard into a *Slow API Endpoints* table grouped by `METHOD + normalized route`.
+- **Console entries** — `warning`, `error`, and `assert` messages with their source location.
 - **Browser Web Vitals** — TTFB, DOM Interactive, DOMContentLoaded, Load Complete, First Paint, First Contentful Paint — displayed with color-coded thresholds.
+- **ARIA snapshot** — captured automatically when a test fails, shown as failure evidence and fed to the AI diagnosis.
+- **Locator snapshots** — for each acted-on element, its attributes plus ranked alternative locators, stamped with the call site. These power locator healing; when a failing locator matches nothing, a fresh suggestion is attached as a Playwright annotation.
+
+Capture works for the `page` fixture, `browser.newPage()`, `browser.newContext().newPage()`, and popups. Everything is only collected when `collectPerformanceMetrics` is `true` (the default); locator snapshots can be disabled separately with `captureLocators: false`.
 
-Both are only collected when `collectPerformanceMetrics` is `true` (the default).
+Without the fixtures you still get full run history, statuses, errors, traces, reports, streaming, and clustering — the fixtures add the slow-endpoint, Web Vitals, console, ARIA, and locator-healing layers. See the [capture fixtures guide](https://piwitests.github.io/capture-fixtures) for the full feature matrix and composition patterns.
 
 ## Authentication
 
@@ -195,7 +215,7 @@ When `collectCiInfo` is enabled (default), the reporter auto-detects:
 2. As tests complete, results are streamed in batches to the server
 3. After all tests finish, HTML reports are compressed and uploaded
 4. Trace files from test attachments are uploaded
-5. Network request and web vitals data (from fixtures) are included per test case
+5. Data from the capture fixtures (network requests, console entries, web vitals, ARIA snapshots, locator snapshots) is included per test case
 6. The server stores everything and makes it available in the dashboard UI
 
 ## Requirements
@@ -229,10 +249,10 @@ Everything public — the reporter, config helpers, and the capture fixtures —
 - Ensure traces are enabled: `use: { trace: 'retain-on-failure' }`
 - Check the dashboard server is running and accessible at `serverUrl`
 
-### Network/Web Vitals not appearing
+### Fixture data not appearing (network, Web Vitals, console, ARIA, locator healing)
 
-- Extend your `test` with `dashboardFixtures` / `extendDashboardFixtures` from `@piwitests/reporter`
-- Verify `collectPerformanceMetrics` is not set to `false`
+- Extend your `test` with `piwiFixtures` / `extendPiwiFixtures` from `@piwitests/reporter`, and import `test` from your fixtures file in every spec — not from `@playwright/test` directly
+- Verify `collectPerformanceMetrics` is not set to `false` (and `captureLocators` for locator healing)
 - Ensure tests navigate to at least one page (`await page.goto(...)`)
 
 ### Connection errors

package/dist/index.d.ts

@@ -11,5 +11,6 @@ export default PiwiDashboardReporter;
 export { PiwiDashboardReporter };
 export { wrapConfig } from './public/config-wrapper.js';
 export { createGlobalSetup } from './public/global-setup.js';
-export { dashboardFixtures, extendDashboardFixtures } from './internal/capture/capture-fixtures.js';
+export { piwiFixtures, extendPiwiFixtures } from './internal/capture/capture-fixtures.js';
+export type { PiwiFixtures } from './internal/capture/capture-fixtures.js';
 export type { PiwiDashboardOptions, PlaywrightTestConfig } from './public/options.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extendDashboardFixtures = exports.dashboardFixtures = exports.createGlobalSetup = exports.wrapConfig = exports.PiwiDashboardReporter = void 0;
+exports.extendPiwiFixtures = exports.piwiFixtures = exports.createGlobalSetup = exports.wrapConfig = exports.PiwiDashboardReporter = void 0;
 /**
  * Public API of `@piwitests/reporter`.
  *
@@ -20,5 +20,5 @@ var global_setup_js_1 = require("./public/global-setup.js");
 Object.defineProperty(exports, "createGlobalSetup", { enumerable: true, get: function () { return global_setup_js_1.createGlobalSetup; } });
 // ── Capture fixtures ─────────────────────────────────────────────────────────
 var capture_fixtures_js_1 = require("./internal/capture/capture-fixtures.js");
-Object.defineProperty(exports, "dashboardFixtures", { enumerable: true, get: function () { return capture_fixtures_js_1.dashboardFixtures; } });
-Object.defineProperty(exports, "extendDashboardFixtures", { enumerable: true, get: function () { return capture_fixtures_js_1.extendDashboardFixtures; } });
+Object.defineProperty(exports, "piwiFixtures", { enumerable: true, get: function () { return capture_fixtures_js_1.piwiFixtures; } });
+Object.defineProperty(exports, "extendPiwiFixtures", { enumerable: true, get: function () { return capture_fixtures_js_1.extendPiwiFixtures; } });

package/dist/internal/capture/attachments.d.ts

@@ -1,8 +1,8 @@
 /**
  * Names of the `testInfo` attachments the dashboard fixtures produce and the
  * reporter parses. Single source of truth — imported by the producer
- * (`fixtures.ts`), the consumers (`reporter.ts` / `file-handler.ts`), and the
- * dogfooding `application/tests/fixtures.ts`, so producer and consumer can
+ * (`capture-fixtures.ts`), the consumers (`reporter.ts` / `file-handler.ts`), and
+ * the dogfooding `application/tests/fixtures.ts`, so producer and consumer can
  * never drift on a name.
  */
 export declare const ATTACHMENT_NAMES: {
@@ -12,6 +12,7 @@ export declare const ATTACHMENT_NAMES: {
     readonly network: "piwi-network";
     readonly webVitals: "piwi-web-vitals";
     readonly locatorSuggestion: "piwi-locator-suggestion";
+    readonly pageState: "piwi-page-state";
 };
 /** Set of every internal attachment name — used to skip them when collecting user attachments. */
 export declare const INTERNAL_ATTACHMENT_NAMES: ReadonlySet<string>;

package/dist/internal/capture/attachments.js

@@ -4,8 +4,8 @@ exports.LOCATOR_SUGGESTION_ANNOTATION = exports.INTERNAL_ATTACHMENT_NAMES = expo
 /**
  * Names of the `testInfo` attachments the dashboard fixtures produce and the
  * reporter parses. Single source of truth — imported by the producer
- * (`fixtures.ts`), the consumers (`reporter.ts` / `file-handler.ts`), and the
- * dogfooding `application/tests/fixtures.ts`, so producer and consumer can
+ * (`capture-fixtures.ts`), the consumers (`reporter.ts` / `file-handler.ts`), and
+ * the dogfooding `application/tests/fixtures.ts`, so producer and consumer can
  * never drift on a name.
  */
 exports.ATTACHMENT_NAMES = {
@@ -15,6 +15,7 @@ exports.ATTACHMENT_NAMES = {
     network: 'piwi-network',
     webVitals: 'piwi-web-vitals',
     locatorSuggestion: 'piwi-locator-suggestion',
+    pageState: 'piwi-page-state',
 };
 /** Set of every internal attachment name — used to skip them when collecting user attachments. */
 exports.INTERNAL_ATTACHMENT_NAMES = new Set(Object.values(exports.ATTACHMENT_NAMES));

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

@@ -1,4 +1,7 @@
-import type { Fixtures, Locator } from '@playwright/test';
+import type { Fixtures, Locator, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, TestType } from '@playwright/test';
+type FixtureArgs = {
+    [key: string]: any;
+};
 /** Shape returned by the in-page element probe (see `wrapLocator`). */
 interface CapturedAttrs {
     tagName: string;
@@ -17,7 +20,108 @@ interface CapturedAttrs {
         name?: number;
         classes?: Record<string, number>;
     };
+    /** Position among same-role elements, document-wide (null when the element has no role). */
+    rolePosition: {
+        role: string;
+        count: number;
+        index: number;
+        levelCount?: number;
+    } | null;
+    /** Anchor-worthy ancestors, nearest first (empty when none found or probing failed). */
+    ancestors: Array<{
+        tag: string;
+        depth: number;
+        testId: string | null;
+        id: string | null;
+        role: string | null;
+        ariaLabel: string | null;
+        scopedRoleCount?: number;
+        testIdCount?: number;
+        idCount?: number;
+        roleCount?: number;
+    }>;
 }
+/** Plain-object projection of a performance entry, shipped out of the page. */
+export interface RawVitalEntry {
+    startTime?: number;
+    value?: number;
+    hadRecentInput?: boolean;
+    interactionId?: number;
+    duration?: number;
+}
+/**
+ * Aggregate buffered performance entries into LCP/CLS/INP. Pure and Node-side
+ * so it is unit-testable; the in-page evaluate only ships raw entry projections.
+ * A null entry list means the entry type is unsupported (non-Chromium) — the
+ * metric is null rather than 0 so absence is distinguishable from "no shifts".
+ */
+export declare function computeCoreVitals(lcpEntries: RawVitalEntry[] | null, shiftEntries: RawVitalEntry[] | null, eventEntries: RawVitalEntry[] | null): {
+    lcp: number | null;
+    cls: number | null;
+    inp: number | null;
+} | null;
+/** Page state captured at test end. Storage values and cookie values are NEVER included. */
+export interface PageState {
+    url: string;
+    hash: string | null;
+    /** `history.state` as JSON, capped and token-masked. */
+    historyState: string | null;
+    /** Key names + value lengths only. */
+    localStorage: Array<{
+        key: string;
+        length: number;
+    }>;
+    sessionStorage: Array<{
+        key: string;
+        length: number;
+    }>;
+    /** Cookie names + flags only (values are never read). */
+    cookies: Array<{
+        name: string;
+        domain: string;
+        path: string;
+        httpOnly: boolean;
+        secure: boolean;
+        sameSite?: string;
+        expires?: number;
+    }>;
+}
+/** Raw in-page reads shipped out of the evaluate (see `readPageState`). */
+export interface RawPageState {
+    url: string;
+    hash: string | null;
+    historyState: string | null;
+    localStorage: Array<{
+        key: string;
+        length: number;
+    }>;
+    sessionStorage: Array<{
+        key: string;
+        length: number;
+    }>;
+}
+/**
+ * Assemble the wire page-state from the in-page reads and the context cookies.
+ * Pure and Node-side so the sanitization (token masking, caps, value-free
+ * cookies) is unit-testable.
+ */
+export declare function buildPageState(raw: RawPageState, cookies: Array<Record<string, unknown>> | null): PageState;
+/**
+ * Everything the in-page probe needs, serialized into the browser on every
+ * action. `tagRoles`/`inputRoles` are the shared role maps (single source of
+ * truth in `locator-healing.ts`), and `roleSources` is the CSS selector for
+ * every element the probe can resolve a role for — all derived from the map so
+ * nothing is hand-maintained twice. Exported so the dogfood mirror
+ * (`application/tests/fixtures.ts`) reuses the same assembled object.
+ */
+export interface ProbeArg {
+    keep: string[];
+    tagRoles: Record<string, string>;
+    inputRoles: Record<string, string>;
+    roleSources: string;
+}
+/** Built once — passed verbatim into evaluate() on every action. */
+export declare const CAPTURED_ATTRS_ARG: ProbeArg;
 /**
  * ARIA snapshot that tolerates every Playwright version the reporter supports,
  * returning null instead of throwing so a capture can never fail the test. The
@@ -40,7 +144,18 @@ export declare function ariaSnapshotBestEffort(target: Locator, timeout?: number
  * `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;
+export declare function probeElementAttrs(el: any, arg: ProbeArg): CapturedAttrs;
+/**
+ * The fixtures `piwiFixtures` / `extendPiwiFixtures` contribute. The single
+ * added fixture is `piwiCapture`: an auto, test-scoped teardown hook that
+ * attaches the collected `piwi-*` data. Its name is **reserved** — a user
+ * fixture of the same name replaces the capture teardown and silently disables
+ * all capture. Exported so `piwiFixtures` and the extended `test` carry it in
+ * their types (and a collision surfaces to the type checker).
+ */
+export interface PiwiFixtures {
+    piwiCapture: void;
+}
 /**
  * Playwright fixtures that collect network requests, console entries,
  * web vitals, ARIA snapshots, and locator interaction data during a test.
@@ -50,9 +165,10 @@ export declare function probeElementAttrs(el: any, keep: string[]): CapturedAttr
  * `browser.newContext()`. Collected data is attached as `piwi-*`
  * test-info attachments which the Piwi Dashboard reporter parses on `onTestEnd`.
  */
-export declare const dashboardFixtures: Fixtures;
+export declare const piwiFixtures: Fixtures<PiwiFixtures, {}, PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
 /**
- * Extend a Playwright `test` object with Piwi Dashboard fixtures.
+ * Extend a Playwright `test` object with the Piwi capture fixtures. The
+ * returned `test` carries the existing fixtures plus {@link PiwiFixtures}.
  *
  * Use this instead of importing `@playwright/test` directly from this package
  * to avoid the "Requiring @playwright/test second time" error caused by
@@ -61,10 +177,10 @@ export declare const dashboardFixtures: Fixtures;
  * @example
  * ```ts
  * import { test as base } from '@playwright/test';
- * import { extendDashboardFixtures } from '@piwitests/reporter';
+ * import { extendPiwiFixtures } from '@piwitests/reporter';
  *
- * export const test = extendDashboardFixtures(base);
+ * export const test = extendPiwiFixtures(base);
  * ```
  */
-export declare function extendDashboardFixtures<T>(test: T): T;
+export declare function extendPiwiFixtures<TestArgs extends FixtureArgs, WorkerArgs extends FixtureArgs>(test: TestType<TestArgs, WorkerArgs>): TestType<TestArgs & PiwiFixtures, WorkerArgs>;
 export {};