@testivai/witness-selenium 0.1.10 → 0.3.0

package/dist/types.d.ts

@@ -38,6 +38,24 @@ export interface WitnessOptions {
      * known to be expensive or unstable.
      */
     skipDom?: boolean;
+    /**
+     * Skip element-map capture. The map powers region→selector attribution,
+     * shift classification, and the computed-style fingerprint; skipping it
+     * 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.
+     */
+    maxElements?: number;
     /**
      * CSS selectors for elements to hide (`visibility: hidden`) for the
      * duration of the capture, so dynamic content (timestamps, ads, live

package/dist/witness.js

@@ -20,9 +20,44 @@
  *     capture is viewport-only (keep the window sized to what you want
  *     compared; baselines are consistent run-to-run either way)
  */
+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.witness = witness;
 const witness_1 = require("@testivai/witness");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 /** id of the style element injected for the duration of a capture */
 const STYLE_ID = '__testivai_capture_css__';
 /**
@@ -61,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 (;;) {
@@ -138,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;
@@ -149,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;
@@ -172,7 +252,45 @@ async function witness(driver, name, options = {}) {
             // is unavailable for this snapshot; pixel diff still works.
         }
     }
-    // 3. Write to .testivai/temp/<name>/
+    // 3. Capture the element map (best-effort — same contract as the DOM).
+    //    This is what powers region→selector attribution, shift
+    //    classification, and the computed-style fingerprint on the compare
+    //    side. The injected function is the SAME one the Playwright adapter
+    //    uses (`@testivai/witness`), so both lanes produce identical maps.
+    //    Selenium's executeScript needs an explicit `return`.
+    let elementMap;
+    if (!options.skipElementMap && typeof driver.executeScript === 'function') {
+        try {
+            const expr = (0, witness_1.buildElementMapExpression)(options.maxElements ?? witness_1.DEFAULT_MAX_ELEMENTS, ignoreSelectors);
+            const result = await driver.executeScript(`return ${expr}`);
+            if (Array.isArray(result) && result.length > 0) {
+                elementMap = result;
+            }
+        }
+        catch {
+            // Suppressed by design, exactly like DOM capture: without a map the
+            // report falls back to pixel + DOM layers instead of failing.
+        }
+    }
+    // 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 {
+            fs.mkdirSync(tempDir, { recursive: true });
+            fs.writeFileSync(path.join(tempDir, 'elements.json'), JSON.stringify(elementMap));
+        }
+        catch {
+            // A map we cannot persist is not worth failing a capture over.
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testivai/witness-selenium",
-  "version": "0.1.10",
+  "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.11.1"
+    "@testivai/witness": "1.13.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",