@testivai/witness-webdriverio 0.3.1 → 0.4.0

package/README.md

@@ -95,27 +95,37 @@ npx testivai approve --all
 
 Approve writes the temp capture over the baseline and backs the previous baseline up to `.testivai/baselines/<name>/.previous/`. `npx testivai approve --undo "homepage"` reverts.
 
-## DOM noise hint
+## DOM noise hint and style check
 
-When pixels differ but the page DOM is structurally identical, the report flags the change as "likely render noise" (anti-aliasing, font hinting, sub-pixel layout). When the DOM is also different, the report shows added / removed / attribute-change counts so you can decide whether the change is intentional. Same signal as the Playwright adapter — both write `dom.html` alongside the screenshot.
+Alongside the screenshot the adapter writes `dom.html` and `elements.json`, the element map: each element's box and a digest of its computed styles, collected by the same function the Playwright and Selenium adapters use.
 
-DOM capture happens automatically. To skip it for a single snapshot:
+- When pixels differ but the DOM is structurally identical and no computed style changed, the report flags the change as "likely render noise" (anti-aliasing, font hinting, sub-pixel layout).
+- When the DOM is identical but computed styles differ, it reports a style-only change, which is real, and names the restyled elements.
+- When the DOM also differs, it shows added / removed / attribute-change counts so you can decide whether the change is intentional.
+
+The element map also powers region attribution (which selectors a diff region covers) and page-shift detection.
+
+WebDriver's screenshot is the **viewport**, not the full page, so the element map keeps only the elements inside the captured viewport, in screenshot coordinates. Size the browser window to what you want compared, and capture at the same scroll position each run.
+
+Both captures happen automatically and are best-effort: if either fails, the pixel diff still runs. To skip them for a single snapshot:
 
 ```ts
-await testivai.witness(browser, 'no-dom', { skipDom: true });
+await testivai.witness(browser, 'no-dom', { skipDom: true, skipElementMap: true });
 ```
 
 ## API
 
 ### `testivai.witness(browser, name, options?)`
 
-Captures a screenshot + DOM and writes them as a temp snapshot.
+Captures a viewport screenshot, the DOM and the element map, and writes them as a temp snapshot.
 
 | Param | Type | Description |
 |---|---|---|
 | `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.skipElementMap` | boolean | Skip the element map for this snapshot (no style check, region attribution or page-shift detection). |
+| `options.maxElements` | number | Cap on elements collected for the element map. Default: 3000. |
 | `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). |
 

package/dist/element-map.d.ts

@@ -0,0 +1,25 @@
+import { type CollectedElement } from '@testivai/witness';
+/** What the page reports: the shared collector's map plus where the viewport was. */
+export interface PageElementMap {
+    /** From the shared collector: document coordinates in device pixels. */
+    elements: CollectedElement[];
+    scrollX: number;
+    scrollY: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    dpr: number;
+}
+/**
+ * Page-side script: the same collector the Playwright and Selenium adapters
+ * run (so all lanes produce identical maps), plus the viewport it was taken
+ * in. WebdriverIO string scripts need an explicit `return`.
+ */
+export declare function elementMapScript(maxElements: number, ignoreSelectors: string[]): string;
+export declare function isPageElementMap(value: unknown): value is PageElementMap;
+/**
+ * WebDriver's Take Screenshot captures the viewport, while the collector
+ * reports document coordinates. Keep only the elements inside the captured
+ * viewport, moved into screenshot coordinates, so the map describes the
+ * pixels that were actually compared.
+ */
+export declare function toViewportElementMap(page: PageElementMap): CollectedElement[];

package/dist/element-map.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.elementMapScript = elementMapScript;
+exports.isPageElementMap = isPageElementMap;
+exports.toViewportElementMap = toViewportElementMap;
+const witness_1 = require("@testivai/witness");
+/**
+ * Page-side script: the same collector the Playwright and Selenium adapters
+ * run (so all lanes produce identical maps), plus the viewport it was taken
+ * in. WebdriverIO string scripts need an explicit `return`.
+ */
+function elementMapScript(maxElements, ignoreSelectors) {
+    return (`return { elements: ${(0, witness_1.buildElementMapExpression)(maxElements, ignoreSelectors)}, ` +
+        'scrollX: window.scrollX || 0, scrollY: window.scrollY || 0, ' +
+        'viewportWidth: window.innerWidth, viewportHeight: window.innerHeight, ' +
+        'dpr: window.devicePixelRatio || 1 };');
+}
+function isPageElementMap(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (Array.isArray(v.elements) &&
+        ['scrollX', 'scrollY', 'viewportWidth', 'viewportHeight', 'dpr'].every((k) => typeof v[k] === 'number'));
+}
+/**
+ * WebDriver's Take Screenshot captures the viewport, while the collector
+ * reports document coordinates. Keep only the elements inside the captured
+ * viewport, moved into screenshot coordinates, so the map describes the
+ * pixels that were actually compared.
+ */
+function toViewportElementMap(page) {
+    const offsetX = Math.round(page.scrollX * page.dpr);
+    const offsetY = Math.round(page.scrollY * page.dpr);
+    const width = Math.round(page.viewportWidth * page.dpr);
+    const height = Math.round(page.viewportHeight * page.dpr);
+    return page.elements
+        .map((e) => ({ ...e, x: e.x - offsetX, y: e.y - offsetY }))
+        .filter((e) => e.x < width && e.x + e.width > 0 && e.y < height && e.y + e.height > 0);
+}

package/dist/types.d.ts

@@ -29,6 +29,14 @@ export interface WitnessOptions {
      * known to be expensive or unstable.
      */
     skipDom?: boolean;
+    /**
+     * Skip the element map (each element's box and a digest of its computed
+     * styles). Without it the report falls back to the pixel and DOM layers:
+     * no style check, region attribution or page-shift detection.
+     */
+    skipElementMap?: boolean;
+    /** Cap on elements collected for the element map. Default: 3000. */
+    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.d.ts

@@ -6,9 +6,9 @@
  *   import { testivai } from '@testivai/witness-webdriverio';
  *   await testivai.witness(browser, 'homepage');
  *
- * Captures a full-page screenshot via `browser.takeScreenshot()` and the
- * page DOM via `browser.execute(() => document.documentElement.outerHTML)`,
- * then writes both into `.testivai/temp/<name>/` using the same
+ * Captures the viewport screenshot via `browser.takeScreenshot()` (WebDriver's
+ * Take Screenshot is viewport-sized), the page DOM, and the element map via
+ * `browser.execute(...)`, then writes them into `.testivai/temp/<name>/` using the same
  * BaselineStore layout as @testivai/witness-playwright. The TestivaiService
  * (registered in wdio.conf.ts) runs `compareAll` + `generateReport` after
  * all tests finish.

package/dist/witness.js

@@ -7,9 +7,9 @@
  *   import { testivai } from '@testivai/witness-webdriverio';
  *   await testivai.witness(browser, 'homepage');
  *
- * Captures a full-page screenshot via `browser.takeScreenshot()` and the
- * page DOM via `browser.execute(() => document.documentElement.outerHTML)`,
- * then writes both into `.testivai/temp/<name>/` using the same
+ * Captures the viewport screenshot via `browser.takeScreenshot()` (WebDriver's
+ * Take Screenshot is viewport-sized), the page DOM, and the element map via
+ * `browser.execute(...)`, then writes them into `.testivai/temp/<name>/` using the same
  * BaselineStore layout as @testivai/witness-playwright. The TestivaiService
  * (registered in wdio.conf.ts) runs `compareAll` + `generateReport` after
  * all tests finish.
@@ -19,9 +19,45 @@
  * point of the per-framework adapter — using the framework's stable public
  * API instead of fighting Chrome-launch coordination.
  */
+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 fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const witness_1 = require("@testivai/witness");
+const element_map_1 = require("./element-map");
 /** id of the style element injected for the duration of a capture */
 const STYLE_ID = '__testivai_capture_css__';
 /**
@@ -157,7 +193,36 @@ async function witness(browser, 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).
+    //    It powers the style check, region attribution and page-shift
+    //    detection on the compare side. The screenshot is the viewport, so the
+    //    map keeps only the elements inside it, in screenshot coordinates.
+    let elementMap;
+    if (!options.skipElementMap && typeof browser.execute === 'function') {
+        try {
+            const result = await browser.execute((0, element_map_1.elementMapScript)(options.maxElements ?? witness_1.DEFAULT_MAX_ELEMENTS, ignoreSelectors));
+            if ((0, element_map_1.isPageElementMap)(result)) {
+                const inView = (0, element_map_1.toViewportElementMap)(result);
+                if (inView.length > 0)
+                    elementMap = inView;
+            }
+        }
+        catch {
+            // Suppressed by design, exactly like DOM capture: without a map the
+            // report falls back to the pixel and DOM layers instead of failing.
+        }
+    }
+    // 4. Write to .testivai/temp/<name>/
     const store = new witness_1.BaselineStore(process.cwd());
     store.writeTemp(name, screenshot, dom);
+    if (elementMap) {
+        try {
+            const tempDir = path.join(process.cwd(), '.testivai', 'temp', name);
+            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-webdriverio",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "WebdriverIO adapter for TestivAI Witness — local-first visual regression with pixel + DOM comparison",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -54,15 +54,15 @@
     }
   },
   "dependencies": {
-    "@testivai/witness": "2.0.1"
+    "@testivai/witness": "2.1.1"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
-    "jest": "^30.4.2",
+    "jest": "^30.5.1",
     "ts-jest": "^29.4.12",
     "typescript": "^6.0.3",
-    "webdriverio": "^9.30.1"
+    "webdriverio": "^9.31.7"
   },
   "scripts": {
     "build": "tsc",