@testivai/witness-playwright 1.8.0 → 1.9.0

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.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;
@@ -70,16 +71,13 @@ class TestivAIPlaywrightReporter {
      *   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) {
-        if (typeof this.options.captureOnly === 'boolean')
-            return this.options.captureOnly;
-        const env = process.env.TESTIVAI_CAPTURE_ONLY;
-        if (env !== undefined && env !== '')
-            return env !== '0' && env.toLowerCase() !== 'false';
-        return !!(this.shard && this.shard.total > 1);
+    resolveCaptureOnly(_config) {
+        return (0, witness_1.resolveCaptureOnly)(this.options.captureOnly, this.shard);
     }
     async onBegin(config, suite) {
-        this.shard = config.shard ?? null;
+        // 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
@@ -145,24 +143,10 @@ class TestivAIPlaywrightReporter {
                 // Without this a crashed shard silently reduces coverage whenever
                 // failOnMissing is off.
                 if (this.shard) {
-                    try {
-                        const tempRoot = path.join(process.cwd(), '.testivai', 'temp');
-                        fs.ensureDirSync(tempRoot);
-                        const captures = fs
-                            .readdirSync(tempRoot, { withFileTypes: true })
-                            .filter((e) => e.isDirectory())
-                            .map((e) => e.name);
-                        fs.writeJsonSync(path.join(tempRoot, 'testivai-shard.json'), {
-                            shard: { current: this.shard.current, total: this.shard.total },
-                            captures,
-                            status: result.status,
-                            timestamp: new Date().toISOString(),
-                        });
-                    }
-                    catch {
-                        // A manifest we cannot write must not fail the test run; the merge
-                        // step degrades to "no completeness check" and says so.
-                    }
+                    (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.`);

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,6 +1,6 @@
 {
   "name": "@testivai/witness-playwright",
-  "version": "1.8.0",
+  "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",
@@ -52,7 +52,7 @@
     "sharp": "^0.34.5",
     "simple-git": "^3.21.0",
     "@testivai/common": "0.2.3",
-    "@testivai/witness": "1.12.0"
+    "@testivai/witness": "1.13.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",