@testivai/witness-webdriverio 0.1.2 → 0.2.0

package/README.md

@@ -27,7 +27,11 @@ Create `.testivai/config.json` at your project root:
   "mode": "local",
   "threshold": 0.1,
   "reportDir": "visual-report",
-  "autoOpen": false
+  "autoOpen": false,
+  "maxDiffPercent": 0,
+  "noiseAutoPass": false,
+  "stabilize": true,
+  "ignoreSelectors": []
 }
 ```
 
@@ -113,6 +117,8 @@ Captures a screenshot + DOM and writes them as a temp snapshot.
 | `browser` | WebdriverIO browser | Must expose `takeScreenshot()` and (for DOM) `execute()`. |
 | `name` | string | Snapshot name. Becomes `.testivai/temp/<name>/` and the key in the report. |
 | `options.skipDom` | boolean | Skip DOM capture for this snapshot. |
+| `options.ignoreSelectors` | string[] | Elements hidden (`visibility: hidden`) for this capture; merged with the global `ignoreSelectors` from `.testivai/config.json`. |
+| `options.stabilize` | boolean | Override capture stabilization (animations frozen, caret hidden, fonts awaited). Default: `true` (or the global `stabilize` setting). |
 
 ### `TestivaiService`
 

package/dist/types.d.ts

@@ -29,6 +29,27 @@ export interface WitnessOptions {
      * known to be expensive or unstable.
      */
     skipDom?: boolean;
+    /**
+     * CSS selectors for elements to hide (`visibility: hidden`) for the
+     * duration of the capture, so dynamic content (timestamps, ads, live
+     * widgets) never contributes to the pixel diff. Merged with the global
+     * `ignoreSelectors` list from `.testivai/config.json`.
+     */
+    ignoreSelectors?: string[];
+    /**
+     * Variant key for multi-browser / multi-viewport runs. Folded into the
+     * snapshot name (`<name>__<variant>`) so parallel capabilities don't
+     * overwrite each other's baselines. Example: set it per capability in
+     * wdio.conf.ts (`'chrome-1280'`, `'firefox-mobile'`).
+     */
+    variant?: string;
+    /**
+     * Stabilize the page before capture: disable CSS animations/transitions,
+     * hide the text caret, and wait for web fonts to finish loading — the top
+     * causes of flaky visual diffs. Default: true (also configurable globally
+     * via `stabilize` in `.testivai/config.json`; this per-call value wins).
+     */
+    stabilize?: boolean;
 }
 /**
  * Configuration passed to the WDIO service.

package/dist/witness.js

@@ -22,6 +22,64 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.witness = witness;
 const witness_1 = require("@testivai/witness");
+/** id of the style element injected for the duration of a capture */
+const STYLE_ID = '__testivai_capture_css__';
+/**
+ * Freezes CSS animations/transitions, hides the caret, and forces instant
+ * scrolling — the top causes of flaky visual diffs. Mirrors the Playwright
+ * adapter's STABILIZE_CSS.
+ */
+const STABILIZE_CSS = '*, *::before, *::after { animation-duration: 0.001s !important; animation-delay: 0s !important; ' +
+    'animation-iteration-count: 1 !important; transition-duration: 0.001s !important; ' +
+    'transition-delay: 0s !important; caret-color: transparent !important; scroll-behavior: auto !important; }';
+/** Build the ignoreSelectors CSS block (visibility preserves layout). */
+function buildIgnoreCss(selectors) {
+    return selectors.map((s) => `${s} { visibility: hidden !important; }`).join('\n');
+}
+/**
+ * Inject a <style> tag with the given CSS. Returns true when injection
+ * succeeded. Uses the inline-string form of execute for WDIO 8/9 parity.
+ */
+async function injectCaptureCss(browser, css) {
+    try {
+        await browser.execute(`var el = document.createElement('style');` +
+            `el.id = ${JSON.stringify(STYLE_ID)};` +
+            `el.textContent = ${JSON.stringify(css)};` +
+            `document.head.appendChild(el);`);
+        return true;
+    }
+    catch {
+        return false; // capture proceeds without stabilization/ignores
+    }
+}
+async function removeCaptureCss(browser) {
+    try {
+        await browser.execute(`var el = document.getElementById(${JSON.stringify(STYLE_ID)});` +
+            `if (el) el.remove();`);
+    }
+    catch {
+        // best-effort cleanup
+    }
+}
+/**
+ * Wait (bounded at ~3s) for web fonts to finish loading so the capture never
+ * shows a fallback font. Polled from Node because classic WebDriver execute
+ * does not await page-side promises.
+ */
+async function waitForFonts(browser) {
+    const deadline = Date.now() + 3000;
+    for (;;) {
+        try {
+            const status = await browser.execute(`return document.fonts ? document.fonts.status : 'loaded';`);
+            if (status !== 'loading' || Date.now() >= deadline)
+                return;
+        }
+        catch {
+            return; // no FontFaceSet or execute failed — proceed
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+}
 /**
  * Capture a screenshot + DOM and write them as a temp snapshot.
  *
@@ -38,8 +96,40 @@ async function witness(browser, name, options = {}) {
     if (!browser || typeof browser.takeScreenshot !== 'function') {
         throw new Error('testivai.witness: browser argument must expose takeScreenshot()');
     }
+    // Multi-capability runs: fold the variant into the name so capabilities
+    // don't overwrite each other's baselines (same mechanism as the Playwright
+    // adapter's multi-project handling).
+    if (options.variant) {
+        name = `${name}__${options.variant.replace(/[^a-z0-9_-]+/gi, '_').toLowerCase()}`;
+    }
+    // 0. Prepare the page: stabilization CSS (animations/caret/fonts — the
+    //    flake killers) + ignoreSelectors from config.json and this call,
+    //    injected as one style tag and removed after the capture.
+    const localConfig = (0, witness_1.loadLocalConfig)(process.cwd());
+    const stabilize = options.stabilize ?? localConfig.stabilize;
+    const ignoreSelectors = [
+        ...new Set([...(localConfig.ignoreSelectors ?? []), ...(options.ignoreSelectors ?? [])]),
+    ];
+    const cssParts = [];
+    if (stabilize)
+        cssParts.push(STABILIZE_CSS);
+    if (ignoreSelectors.length > 0)
+        cssParts.push(buildIgnoreCss(ignoreSelectors));
+    let injected = false;
+    if (cssParts.length > 0 && typeof browser.execute === 'function') {
+        injected = await injectCaptureCss(browser, cssParts.join('\n'));
+        if (stabilize)
+            await waitForFonts(browser);
+    }
     // 1. Capture screenshot (base64 PNG → Buffer)
-    const base64 = await browser.takeScreenshot();
+    let base64;
+    try {
+        base64 = await browser.takeScreenshot();
+    }
+    finally {
+        if (injected)
+            await removeCaptureCss(browser);
+    }
     if (typeof base64 !== 'string' || base64.length === 0) {
         throw new Error(`testivai.witness("${name}"): browser.takeScreenshot() returned an empty value`);
     }
@@ -50,9 +140,14 @@ async function witness(browser, name, options = {}) {
         try {
             const result = await browser.execute(
             // Inline string form for maximum WDIO sync/async compatibility.
-            // The function-form across WDIO 8/9 has subtle typing differences;
-            // the string form is stable.
-            'return document.documentElement.outerHTML;');
+            // ignoreSelectors excludes elements from the pixel diff, so they
+            // are excluded from the DOM/text signal too (consistent semantic).
+            `var clone = document.documentElement.cloneNode(true);` +
+                `var sels = ${JSON.stringify(ignoreSelectors)};` +
+                `for (var i = 0; i < sels.length; i++) {` +
+                ` try { clone.querySelectorAll(sels[i]).forEach(function(el){ el.remove(); }); } catch (e) {}` +
+                `}` +
+                `return clone.outerHTML;`);
             if (typeof result === 'string' && result.length > 0) {
                 dom = result;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testivai/witness-webdriverio",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "WebdriverIO adapter for TestivAI Witness — local-first visual regression with pixel + DOM comparison",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -53,14 +53,14 @@
     }
   },
   "dependencies": {
-    "@testivai/witness": "1.0.4"
+    "@testivai/witness": "1.2.0"
   },
   "devDependencies": {
-    "@types/jest": "^29.0.0",
+    "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
-    "jest": "^29.0.0",
-    "ts-jest": "^29.2.5",
-    "typescript": "^5.0.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.3",
     "webdriverio": "^9.0.0"
   },
   "scripts": {