@testivai/witness-selenium 0.2.0 → 0.3.0

package/dist/types.d.ts

@@ -44,6 +44,13 @@ export interface WitnessOptions {
      * leaves the pixel and DOM layers intact.
      */
     skipElementMap?: boolean;
+    /**
+     * Milliseconds the DOM must be free of mutations before capturing
+     * (default 150). Raise it for pages that stream content in.
+     */
+    settleQuietMs?: number;
+    /** Ceiling on waiting for the page to settle (default 5000ms). */
+    settleTimeoutMs?: number;
     /**
      * Cap on elements walked for the map (default 3000). Lower it on very
      * large pages where the single executeScript round trip is costly.

package/dist/witness.js

@@ -96,6 +96,47 @@ async function removeCaptureCss(driver) {
  * Wait (bounded at 10s) for web fonts to finish loading so the capture
  * never shows a fallback font — a fallback-font capture diffs 30%+.
  */
+/**
+ * Wait until the page has stopped changing: document complete, images finished,
+ * fonts loaded, and no DOM mutations for `quietMs`.
+ *
+ * Deliberately NOT network idle — Playwright's own docs mark that DISCOURAGED
+ * for testing, and it is the wrong signal anyway: a page with analytics beacons
+ * never goes quiet, while a network-idle page can still be animating.
+ *
+ * Always bounded. A page that never settles yields a capture with a debug note
+ * rather than a hung suite.
+ */
+async function waitForSettled(driver, quietMs, timeoutMs) {
+    const expr = (0, witness_1.buildSettleProbeExpression)(quietMs);
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const state = await driver.executeScript(`return ${expr}`);
+            // A driver that cannot evaluate the probe returns nothing. Polling that
+            // to the timeout would add the full wait to EVERY capture, so treat an
+            // unusable answer as "cannot probe" and proceed immediately.
+            if (!state || typeof state.settled !== 'boolean')
+                return;
+            if (state.settled)
+                return;
+            if (Date.now() >= deadline)
+                return;
+        }
+        catch {
+            return; // probe unavailable — never block the capture
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+}
+async function stopSettleObserver(driver) {
+    try {
+        await driver.executeScript(witness_1.SETTLE_STOP_EXPRESSION);
+    }
+    catch {
+        // best-effort cleanup
+    }
+}
 async function waitForFonts(driver) {
     const deadline = Date.now() + 10000;
     for (;;) {
@@ -173,8 +214,10 @@ async function witness(driver, name, options = {}) {
     let injected = false;
     if (cssParts.length > 0 && typeof driver.executeScript === 'function') {
         injected = await injectCaptureCss(driver, cssParts.join('\n'));
-        if (stabilize)
+        if (stabilize) {
             await waitForFonts(driver);
+            await waitForSettled(driver, options.settleQuietMs ?? witness_1.DEFAULT_QUIET_MS, options.settleTimeoutMs ?? witness_1.DEFAULT_SETTLE_TIMEOUT_MS);
+        }
     }
     // 1. Capture screenshot (full-page on Chromium, viewport elsewhere)
     let screenshot;
@@ -184,6 +227,8 @@ async function witness(driver, name, options = {}) {
     finally {
         if (injected)
             await removeCaptureCss(driver);
+        if (stabilize)
+            await stopSettleObserver(driver);
     }
     // 2. Capture DOM (best-effort — never break the screenshot path)
     let dom;
@@ -230,6 +275,14 @@ async function witness(driver, name, options = {}) {
     // 4. Write to .testivai/temp/<name>/
     const store = new witness_1.BaselineStore(process.cwd());
     store.writeTemp(name, screenshot, dom);
+    // 5. Shard manifest. A Selenium script has no end-of-run hook to attach to,
+    //    so it is refreshed on every capture — which is exactly what lets a
+    //    Selenium suite join the same sharded CI flow as Playwright. `complete`
+    //    stays false because this adapter cannot know the run finished.
+    const shard = (0, witness_1.parseShardEnv)(process.env.TESTIVAI_SHARD);
+    if (shard) {
+        (0, witness_1.writeShardManifest)(path.join(process.cwd(), '.testivai', 'temp'), shard);
+    }
     if (elementMap !== undefined) {
         const tempDir = path.join(process.cwd(), '.testivai', 'temp', name);
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testivai/witness-selenium",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Selenium WebDriver adapter for TestivAI Witness — local-first visual regression with pixel + DOM comparison",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -49,7 +49,7 @@
     }
   },
   "dependencies": {
-    "@testivai/witness": "1.12.0"
+    "@testivai/witness": "1.13.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",