@testivai/witness-playwright 1.7.1 → 1.9.0

package/README.md

@@ -25,7 +25,6 @@ npm install -D @testivai/witness-playwright
      reporter: [
        ['line'],
        ['@testivai/witness-playwright/reporter', {
-         // No API key needed for local mode!
        }]
      ],
    });
@@ -57,25 +56,8 @@ npm install -D @testivai/witness-playwright
 
 ## Configuration
 
-### Local Mode (Default)
-
-No configuration needed! Just run `npx testivai init` and select "Local Mode".
-
-### Cloud Mode
-
-For team dashboards and collaboration:
-
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  reporter: [
-    ['line'],
-    ['@testivai/witness-playwright/reporter', {
-      apiKey: process.env.TESTIVAI_API_KEY,
-    }]
-  ],
-});
-```
+No configuration needed — `npx testivai init` scaffolds `.testivai/config.json`,
+the baselines directory, and the `.gitignore` entries. Everything runs locally.
 
 ## API Reference
 

package/dist/capture/element-map.d.ts

@@ -1,37 +1,8 @@
 /**
- * Element-map capture — the layout + computed-style digest that powers
- * element attribution, shift classification, and the style fingerprint
- * on the comparison side (@testivai/witness).
- *
- * `collectElementMap` is a SELF-CONTAINED function (no imports, no
- * closures) so it can be serialized into the page with
- * `(${collectElementMap.toString()})(document, window, max)` — and unit
- * tested in Node against a duck-typed DOM. Keep it dependency-free.
+ * Re-export of the canonical element-map collector, which now lives in
+ * `@testivai/witness` so every adapter (Playwright, Selenium, WebdriverIO)
+ * injects the *same* page-side function. Keeping this shim means existing
+ * imports and unit tests continue to work unchanged.
  */
-export interface CollectedElement {
-    path: string;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    styleHash: string;
-}
-/**
- * Walk the document and produce [{path, rect, styleHash}] in document
- * coordinates (DPR-scaled to match full-page screenshot pixels).
- *
- * - `path` is deterministic: tag + first class + :nth-of-type when the
- *   element has same-tag element siblings.
- * - Elements smaller than 4×4 px and invisible elements are skipped.
- * - The walk is depth-first and capped at `maxElements`.
- * - `styleHash` digests a fixed, documented list of computed properties
- *   (FNV-1a 32-bit, hex) — deterministic for identical rendering.
- */
-export declare function collectElementMap(doc: Document, win: Window & typeof globalThis, maxElements: number, ignoreSelectors?: string[]): CollectedElement[];
-/** Default element cap — bounds capture time and elements.json size. */
-export declare const DEFAULT_MAX_ELEMENTS = 3000;
-/**
- * The page-side expression evaluated by the adapter. Serializes the
- * collector so page code and unit-tested code are the same function.
- */
-export declare function buildElementMapExpression(maxElements?: number, ignoreSelectors?: string[]): string;
+export { collectElementMap, buildElementMapExpression, DEFAULT_MAX_ELEMENTS, } from '@testivai/witness';
+export type { CollectedElement } from '@testivai/witness';

package/dist/capture/element-map.js

@@ -1,152 +1,13 @@
 "use strict";
-/**
- * Element-map capture — the layout + computed-style digest that powers
- * element attribution, shift classification, and the style fingerprint
- * on the comparison side (@testivai/witness).
- *
- * `collectElementMap` is a SELF-CONTAINED function (no imports, no
- * closures) so it can be serialized into the page with
- * `(${collectElementMap.toString()})(document, window, max)` — and unit
- * tested in Node against a duck-typed DOM. Keep it dependency-free.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_MAX_ELEMENTS = void 0;
-exports.collectElementMap = collectElementMap;
-exports.buildElementMapExpression = buildElementMapExpression;
-/**
- * Walk the document and produce [{path, rect, styleHash}] in document
- * coordinates (DPR-scaled to match full-page screenshot pixels).
- *
- * - `path` is deterministic: tag + first class + :nth-of-type when the
- *   element has same-tag element siblings.
- * - Elements smaller than 4×4 px and invisible elements are skipped.
- * - The walk is depth-first and capped at `maxElements`.
- * - `styleHash` digests a fixed, documented list of computed properties
- *   (FNV-1a 32-bit, hex) — deterministic for identical rendering.
- */
-function collectElementMap(doc, win, maxElements, ignoreSelectors = []) {
-    var STYLE_PROPS = [
-        'color', 'background-color', 'background-image',
-        'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color',
-        'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width',
-        'border-top-style', 'border-bottom-style', 'border-radius',
-        'font-family', 'font-size', 'font-weight', 'font-style', 'line-height',
-        'text-align', 'text-transform', 'letter-spacing',
-        'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
-        'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
-        'display', 'opacity', 'visibility', 'box-shadow',
-    ];
-    function fnv1a(str) {
-        var h = 0x811c9dc5;
-        for (var i = 0; i < str.length; i++) {
-            h ^= str.charCodeAt(i);
-            h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
-        }
-        return ('0000000' + h.toString(16)).slice(-8);
-    }
-    function segment(el) {
-        var tag = el.tagName.toLowerCase();
-        var cls = '';
-        if (el.classList && el.classList.length > 0) {
-            cls = '.' + el.classList[0];
-        }
-        var parent = el.parentElement;
-        if (!parent)
-            return tag + cls;
-        var sameTag = 0;
-        var index = 0;
-        for (var i = 0; i < parent.children.length; i++) {
-            var sib = parent.children[i];
-            if (sib.tagName === el.tagName) {
-                sameTag++;
-                if (sib === el)
-                    index = sameTag;
-            }
-        }
-        return sameTag > 1 ? tag + cls + ':nth-of-type(' + index + ')' : tag + cls;
-    }
-    function pathOf(el, stopAt) {
-        var parts = [];
-        var node = el;
-        while (node && node !== stopAt.parentElement) {
-            parts.unshift(segment(node));
-            node = node.parentElement;
-        }
-        return parts.join(' > ');
-    }
-    var dpr = win.devicePixelRatio || 1;
-    var scrollX = win.scrollX || 0;
-    var scrollY = win.scrollY || 0;
-    var out = [];
-    var body = doc.body;
-    if (!body)
-        return out;
-    var stack = [body];
-    while (stack.length > 0 && out.length < maxElements) {
-        var el = stack.pop();
-        // The consistency rule: elements covered by ignoreSelectors are
-        // excluded from pixels and the DOM snapshot — they must be excluded
-        // from the element map too (subtree included), or their dynamic
-        // styles would trip the style fingerprint they were meant to escape.
-        var ignored = false;
-        if (ignoreSelectors.length > 0 && typeof el.matches === 'function') {
-            for (var g = 0; g < ignoreSelectors.length; g++) {
-                try {
-                    if (el.matches(ignoreSelectors[g])) {
-                        ignored = true;
-                        break;
-                    }
-                }
-                catch (e) {
-                    // invalid selector — never breaks the walk
-                }
-            }
-        }
-        if (ignored)
-            continue; // skip element AND subtree
-        var rect = el.getBoundingClientRect();
-        if (rect.width >= 4 && rect.height >= 4) {
-            var styleParts = [];
-            var hidden = false;
-            try {
-                var cs = win.getComputedStyle(el);
-                for (var p = 0; p < STYLE_PROPS.length; p++) {
-                    var value = cs.getPropertyValue(STYLE_PROPS[p]);
-                    if (STYLE_PROPS[p] === 'visibility' && value === 'hidden')
-                        hidden = true;
-                    styleParts.push(STYLE_PROPS[p] + ':' + value);
-                }
-            }
-            catch (e) {
-                // styleHash stays a digest of the empty string — still deterministic
-            }
-            // visibility:hidden elements paint no pixels, so their style changes
-            // can never explain a pixel diff — keep them out of the map. Their
-            // CHILDREN may override visibility, so the subtree still walks.
-            if (!hidden) {
-                out.push({
-                    path: pathOf(el, body),
-                    x: Math.round((rect.x + scrollX) * dpr),
-                    y: Math.round((rect.y + scrollY) * dpr),
-                    width: Math.round(rect.width * dpr),
-                    height: Math.round(rect.height * dpr),
-                    styleHash: fnv1a(styleParts.join(';')),
-                });
-            }
-        }
-        // Push children in reverse so the walk stays document-ordered
-        for (var c = el.children.length - 1; c >= 0; c--) {
-            stack.push(el.children[c]);
-        }
-    }
-    return out;
-}
-/** Default element cap — bounds capture time and elements.json size. */
-exports.DEFAULT_MAX_ELEMENTS = 3000;
+exports.DEFAULT_MAX_ELEMENTS = exports.buildElementMapExpression = exports.collectElementMap = void 0;
 /**
- * The page-side expression evaluated by the adapter. Serializes the
- * collector so page code and unit-tested code are the same function.
+ * Re-export of the canonical element-map collector, which now lives in
+ * `@testivai/witness` so every adapter (Playwright, Selenium, WebdriverIO)
+ * injects the *same* page-side function. Keeping this shim means existing
+ * imports and unit tests continue to work unchanged.
  */
-function buildElementMapExpression(maxElements = exports.DEFAULT_MAX_ELEMENTS, ignoreSelectors = []) {
-    return `(${collectElementMap.toString()})(document, window, ${maxElements}, ${JSON.stringify(ignoreSelectors)})`;
-}
+var witness_1 = require("@testivai/witness");
+Object.defineProperty(exports, "collectElementMap", { enumerable: true, get: function () { return witness_1.collectElementMap; } });
+Object.defineProperty(exports, "buildElementMapExpression", { enumerable: true, get: function () { return witness_1.buildElementMapExpression; } });
+Object.defineProperty(exports, "DEFAULT_MAX_ELEMENTS", { enumerable: true, get: function () { return witness_1.DEFAULT_MAX_ELEMENTS; } });

package/dist/config/stabilize.d.ts

@@ -33,3 +33,21 @@ export declare function resolveStabilize(projectRoot: string, projectConfig: Tes
  * a missing FontFaceSet API just means no wait.
  */
 export declare function waitForFonts(page: Page): Promise<void>;
+/**
+ * Wait until the page has stopped changing: document complete, images
+ * finished, fonts loaded, and no DOM mutations for `quietMs`.
+ *
+ * Deliberately NOT `networkidle` — Playwright's own docs mark that DISCOURAGED
+ * for testing, and it is the wrong signal for a visual snapshot: a page with
+ * analytics beacons never goes quiet, while a network-idle page can still be
+ * animating. What matters is whether the rendered page settled.
+ *
+ * Always bounded; a page that never settles yields a capture, not a hang.
+ */
+export declare function waitForSettled(page: {
+    evaluate: (expr: string) => Promise<unknown>;
+}, quietMs?: number, timeoutMs?: number): Promise<void>;
+/** Detach the settle observer so it does not linger on the page under test. */
+export declare function stopSettleObserver(page: {
+    evaluate: (expr: string) => Promise<unknown>;
+}): Promise<void>;

package/dist/config/stabilize.js

@@ -52,6 +52,9 @@ exports.STABILIZE_CSS = void 0;
 exports.readWitnessConfigStabilize = readWitnessConfigStabilize;
 exports.resolveStabilize = resolveStabilize;
 exports.waitForFonts = waitForFonts;
+exports.waitForSettled = waitForSettled;
+exports.stopSettleObserver = stopSettleObserver;
+const witness_1 = require("@testivai/witness");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 /**
@@ -110,3 +113,49 @@ async function waitForFonts(page) {
         // Page navigated or evaluate failed — capture proceeds unstabilized fonts
     }
 }
+/**
+ * Wait until the page has stopped changing: document complete, images
+ * finished, fonts loaded, and no DOM mutations for `quietMs`.
+ *
+ * Deliberately NOT `networkidle` — Playwright's own docs mark that DISCOURAGED
+ * for testing, and it is the wrong signal for a visual snapshot: a page with
+ * analytics beacons never goes quiet, while a network-idle page can still be
+ * animating. What matters is whether the rendered page settled.
+ *
+ * Always bounded; a page that never settles yields a capture, not a hang.
+ */
+async function waitForSettled(page, quietMs = witness_1.DEFAULT_QUIET_MS, timeoutMs = witness_1.DEFAULT_SETTLE_TIMEOUT_MS) {
+    const expr = (0, witness_1.buildSettleProbeExpression)(quietMs);
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        let state;
+        try {
+            state = (await page.evaluate(expr));
+        }
+        catch {
+            return; // probe unavailable — never block the capture
+        }
+        // An unusable answer means we cannot probe; polling to the timeout would
+        // add the full wait to every capture.
+        if (!state || typeof state.settled !== 'boolean')
+            return;
+        if (state.settled)
+            return;
+        if (Date.now() >= deadline) {
+            if (process.env.TESTIVAI_DEBUG === 'true') {
+                console.log(`[TestivAI] page did not settle within ${timeoutMs}ms — capturing anyway`);
+            }
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+}
+/** Detach the settle observer so it does not linger on the page under test. */
+async function stopSettleObserver(page) {
+    try {
+        await page.evaluate(witness_1.SETTLE_STOP_EXPRESSION);
+    }
+    catch {
+        // best-effort cleanup
+    }
+}

package/dist/reporter.d.ts

@@ -5,6 +5,21 @@ interface TestivaiReporterOptions {
     apiKey?: string;
     compression?: CompressionOptions;
     debug?: boolean;
+    /**
+     * Capture only — write `.testivai/temp/` and skip comparison and report
+     * generation entirely.
+     *
+     * This is what a sharded run needs. Each shard only executes a slice of the
+     * suite, so comparing inside a shard reports every baseline the *other*
+     * shards own as missing coverage: measured on an 8-shard run, every shard
+     * exited 3 with ~90% of the suite listed as missing. Capture in the shards,
+     * merge the captures, compare once.
+     *
+     * Left unset this auto-enables when Playwright reports a sharded run
+     * (`--shard=i/N` with N > 1). Set it explicitly to `false` to force
+     * per-shard reports anyway.
+     */
+    captureOnly?: boolean;
 }
 export declare class TestivAIPlaywrightReporter implements Reporter {
     private options;
@@ -15,7 +30,16 @@ export declare class TestivAIPlaywrightReporter implements Reporter {
     private tempDir;
     private compressionHelper;
     private localMode;
+    private captureOnly;
+    private shard;
     constructor(options?: TestivaiReporterOptions);
+    /**
+     * Capture-only resolution, most explicit wins:
+     *   1. the reporter option (including an explicit `false` to opt out)
+     *   2. TESTIVAI_CAPTURE_ONLY — for CI that can't edit playwright.config
+     *   3. auto: Playwright says this is shard i/N with N > 1
+     */
+    private resolveCaptureOnly;
     onBegin(config: FullConfig, suite: Suite): Promise<void>;
     onEnd(result: FullResult): Promise<void>;
 }

package/dist/reporter.js

@@ -44,6 +44,7 @@ const axios_1 = __importDefault(require("axios"));
 const ci_1 = require("./ci");
 const common_1 = require("@testivai/common");
 const mode_1 = require("./mode");
+const witness_1 = require("@testivai/witness");
 class TestivAIPlaywrightReporter {
     constructor(options = {}) {
         this.gitInfo = null;
@@ -52,16 +53,32 @@ class TestivAIPlaywrightReporter {
         this.ciInfo = null;
         this.tempDir = path.join(process.cwd(), '.testivai', 'temp');
         this.localMode = false;
+        this.captureOnly = false;
+        this.shard = null;
         this.options = {
             apiUrl: options.apiUrl || process.env.TESTIVAI_API_URL || 'https://core-api.testiv.ai',
             apiKey: options.apiKey || process.env.TESTIVAI_API_KEY,
             compression: options.compression || {},
             debug: options.debug || process.env.TESTIVAI_DEBUG === 'true',
+            captureOnly: options.captureOnly,
         };
         // Initialize compression helper
         this.compressionHelper = new common_1.CompressionHelper(this.options.compression);
     }
+    /**
+     * Capture-only resolution, most explicit wins:
+     *   1. the reporter option (including an explicit `false` to opt out)
+     *   2. TESTIVAI_CAPTURE_ONLY — for CI that can't edit playwright.config
+     *   3. auto: Playwright says this is shard i/N with N > 1
+     */
+    resolveCaptureOnly(_config) {
+        return (0, witness_1.resolveCaptureOnly)(this.options.captureOnly, this.shard);
+    }
     async onBegin(config, suite) {
+        // Playwright's own --shard wins; TESTIVAI_SHARD covers CI that splits work
+        // some other way, and is the same contract the non-JS adapters honour.
+        this.shard = config.shard ?? (0, witness_1.parseShardEnv)(process.env.TESTIVAI_SHARD);
+        this.captureOnly = this.resolveCaptureOnly(config);
         // Resolve mode. Local-first is the default: with no API key we capture
         // and report locally rather than disabling the reporter. Cloud mode
         // activates only when a key is present (or config/env force it).
@@ -114,6 +131,29 @@ class TestivAIPlaywrightReporter {
     async onEnd(result) {
         // Wrap entire reporter logic in try-catch to prevent crashes
         try {
+            // ── Capture-only: leave the captures on disk and stop ─────────────────
+            //    Comparing here would be wrong for a shard (it can only see its own
+            //    slice) so we say what to do next instead of producing a misleading
+            //    report and exit code.
+            if (this.captureOnly) {
+                // Drop a manifest naming this shard, so the merge step can prove every
+                // shard reported. Written HERE rather than at onBegin on purpose: a
+                // shard killed mid-run (OOM, runner loss) never reaches onEnd and so
+                // leaves no manifest, which is precisely the case worth catching.
+                // Without this a crashed shard silently reduces coverage whenever
+                // failOnMissing is off.
+                if (this.shard) {
+                    (0, witness_1.writeShardManifest)(path.join(process.cwd(), '.testivai', 'temp'), this.shard, {
+                        complete: true,
+                        status: result.status,
+                    });
+                }
+                const where = this.shard ? `shard ${this.shard.current}/${this.shard.total}` : 'capture-only mode';
+                console.log(`\n  TestivAI: ${where} — captured to .testivai/temp/, comparison skipped.`);
+                console.log('  Collect every shard\'s .testivai/temp/, then compare once:');
+                console.log('    npx testivai merge-captures <dirs...> && npx testivai report --fail-on-diff');
+                return;
+            }
             // ── Local mode: generate HTML report instead of uploading ─────────────────
             if (this.localMode) {
                 if (this.options.debug) {
@@ -134,10 +174,20 @@ class TestivAIPlaywrightReporter {
                 });
                 // Print summary
                 const { summary } = reportData;
+                const missing = reportData.missingBaselines?.length ?? 0;
                 console.log(`\n  ═══ TestivAI Visual Report ═══`);
                 console.log(`  Total: ${summary.total}  |  Passed: ${summary.passed}  |  Changed: ${summary.changed}  |  New: ${summary.newSnapshots}`);
-                if (summary.changed > 0 || summary.newSnapshots > 0) {
-                    console.log(`\n  To approve: npx testivai approve --all`);
+                if (missing > 0) {
+                    console.log(`  Missing baselines (no capture this run): ${missing}`);
+                }
+                // A reporter cannot change the process exit code — Playwright owns it,
+                // and it reflects test results, not visual results. Saying nothing here
+                // meant a run could print "Changed: 3" and still exit 0, which reads
+                // like a check that passed. State it plainly and name the gate.
+                if (summary.changed > 0 || summary.newSnapshots > 0 || missing > 0) {
+                    console.log(`\n  ⚠  This did NOT fail the build — a reporter cannot set the exit code.`);
+                    console.log(`     Gate it in CI:  npx testivai report --fail-on-diff`);
+                    console.log(`     To approve:     npx testivai approve --all`);
                 }
                 if (this.options.debug) {
                     console.log(`Testivai Reporter: [DEBUG] Report generated at ${path.join(process.cwd(), localConfig.reportDir || 'visual-report')}`);

package/dist/snapshot.js

@@ -152,6 +152,10 @@ async function snapshot(page, testInfo, name, config) {
             // Style injection can fail on locked-down pages; capture proceeds
         }
         await (0, stabilize_1.waitForFonts)(page);
+        // Then wait for the page itself to stop changing — images finished, DOM
+        // quiet. This is the load question the DOM/style layer cannot answer:
+        // content that never arrived reads as a real change, not as noise.
+        await (0, stabilize_1.waitForSettled)(page);
     }
     // Check if scroll-and-stitch is explicitly requested (backup method)
     if (effectiveConfig.useBrowserCapture === false) {
@@ -378,6 +382,7 @@ async function snapshot(page, testInfo, name, config) {
     if (stabilizeStyleEl) {
         await stabilizeStyleEl.evaluate((el) => el.remove()).catch(() => { });
         stabilizeStyleEl = null;
+        await (0, stabilize_1.stopSettleObserver)(page);
     }
     // 1.5. Local mode: also place the screenshot in the layout expected by
     //      @testivai/witness/report (subdirectory keyed by snapshot name).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@testivai/witness-playwright",
-  "version": "1.7.1",
-  "description": "Playwright sensor for Testivai Visual Regression Test system",
+  "version": "1.9.0",
+  "description": "Playwright adapter for TestivAI Witness — local-first visual regression with pixel + DOM comparison",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -11,8 +11,12 @@
   "keywords": [
     "playwright",
     "visual-regression",
-    "testing",
-    "testivai"
+    "visual-testing",
+    "screenshot-testing",
+    "regression-testing",
+    "testivai",
+    "playwright-reporter",
+    "test-automation"
   ],
   "author": "TestivAI",
   "license": "MIT",
@@ -47,8 +51,8 @@
     "fs-extra": "^11.3.5",
     "sharp": "^0.34.5",
     "simple-git": "^3.21.0",
-    "@testivai/common": "0.2.2",
-    "@testivai/witness": "1.11.1"
+    "@testivai/common": "0.2.3",
+    "@testivai/witness": "1.13.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",