@testivai/witness-selenium 0.3.10 → 0.3.12

package/README.md

@@ -57,7 +57,7 @@ All of these stay `changed` unless you configure a pass criterion; `noiseAutoPas
 
 ## Full-page screenshots
 
-- **Chrome / Edge** — true full-page capture via CDP (`captureBeyondViewport`), the same mechanism Playwright uses. Automatic; nothing to configure.
+- **Chrome / Edge** — true full-page capture via CDP (`captureBeyondViewport`), the same mechanism Playwright uses. Automatic; nothing to configure. Chrome can return a frame painted for the wrong viewport while it sets up that capture, so the adapter waits for a freshly rendered frame, then captures until two captures in a row are identical (at most four). A stable page costs one extra screenshot; `TESTIVAI_DEBUG=true` logs when captures differed.
 - **Firefox / Safari** — the Selenium JS bindings expose no full-page API, so captures are viewport-sized. Set the window to the size you want compared; runs are consistent either way. (The Python and Java TestivAI adapters do full-page on Firefox via its native API.)
 
 ## Stabilized captures

package/dist/capture/full-page.d.ts

@@ -0,0 +1,30 @@
+import { type CaptureLog } from '@testivai/witness';
+import type { WitnessDriver } from '../types';
+/** A Chromium driver: one that can send raw CDP commands. */
+export type CdpDriver = Required<Pick<WitnessDriver, 'sendAndGetDevToolsCommand'>>;
+/**
+ * Full-page screenshot through CDP: wait for a fresh frame, measure the
+ * content, then capture beyond the viewport until two captures in a row match
+ * (at most MAX_STABLE_CAPTURES from @testivai/witness).
+ *
+ * Chrome can hand back a frame painted with styles resolved against the wrong
+ * viewport while it sets up a beyond-viewport capture: narrow-viewport media
+ * rules, a collapsed 100vh hero, or em text drawn at a `max-width: 480px`
+ * body size. The page measures correctly but the pixels do not, so an
+ * unchanged page flips between "changed" and "passed" across runs. See
+ * capture/stable-capture.ts in @testivai/witness, which the standalone CLI
+ * and the Playwright adapter share.
+ *
+ * Selenium reaches the page only through `sendAndGetDevToolsCommand`, so the
+ * frame wait is CDP `Runtime.evaluate` with `awaitPromise`. Every command gets
+ * an explicit params object instead of relying on the bindings' default.
+ *
+ * A stable page costs one extra screenshot.
+ *
+ * @param driver A Chromium (Chrome/Edge) driver.
+ * @param log Optional debug sink.
+ * @returns The PNG bytes of the kept capture.
+ * @throws When the page reports no usable size or a capture returns no data,
+ *   so the caller can fall back to a viewport screenshot.
+ */
+export declare function captureFullPageScreenshot(driver: CdpDriver, log?: CaptureLog): Promise<Buffer>;

package/dist/capture/full-page.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureFullPageScreenshot = captureFullPageScreenshot;
+const witness_1 = require("@testivai/witness");
+/**
+ * Full-page screenshot through CDP: wait for a fresh frame, measure the
+ * content, then capture beyond the viewport until two captures in a row match
+ * (at most MAX_STABLE_CAPTURES from @testivai/witness).
+ *
+ * Chrome can hand back a frame painted with styles resolved against the wrong
+ * viewport while it sets up a beyond-viewport capture: narrow-viewport media
+ * rules, a collapsed 100vh hero, or em text drawn at a `max-width: 480px`
+ * body size. The page measures correctly but the pixels do not, so an
+ * unchanged page flips between "changed" and "passed" across runs. See
+ * capture/stable-capture.ts in @testivai/witness, which the standalone CLI
+ * and the Playwright adapter share.
+ *
+ * Selenium reaches the page only through `sendAndGetDevToolsCommand`, so the
+ * frame wait is CDP `Runtime.evaluate` with `awaitPromise`. Every command gets
+ * an explicit params object instead of relying on the bindings' default.
+ *
+ * A stable page costs one extra screenshot.
+ *
+ * @param driver A Chromium (Chrome/Edge) driver.
+ * @param log Optional debug sink.
+ * @returns The PNG bytes of the kept capture.
+ * @throws When the page reports no usable size or a capture returns no data,
+ *   so the caller can fall back to a viewport screenshot.
+ */
+async function captureFullPageScreenshot(driver, log) {
+    const waitOnce = async () => {
+        const evaluated = await driver.sendAndGetDevToolsCommand('Runtime.evaluate', {
+            expression: witness_1.FRESH_FRAME_EXPRESSION,
+            awaitPromise: true,
+            returnByValue: true,
+        });
+        return evaluated?.result?.value === true;
+    };
+    const settle = () => (0, witness_1.settleFreshFrame)(waitOnce, log);
+    await settle();
+    const metrics = await driver.sendAndGetDevToolsCommand('Page.getLayoutMetrics', {});
+    const size = metrics?.cssContentSize ?? metrics?.contentSize;
+    const width = Math.ceil(size?.width ?? 0);
+    const height = Math.ceil(size?.height ?? 0);
+    if (!(width > 0 && height > 0)) {
+        throw new Error(`page reported unusable content size ${width}x${height}`);
+    }
+    log?.(`page ${width}x${height}, viewport ${metrics.cssLayoutViewport?.clientWidth}x${metrics.cssLayoutViewport?.clientHeight}`);
+    const data = await (0, witness_1.captureUntilStable)({
+        capture: async () => {
+            const shot = await driver.sendAndGetDevToolsCommand('Page.captureScreenshot', {
+                format: 'png',
+                captureBeyondViewport: true,
+                clip: { x: 0, y: 0, width, height, scale: 1 },
+            });
+            if (typeof shot?.data !== 'string' || shot.data.length === 0) {
+                throw new Error('Page.captureScreenshot returned no data');
+            }
+            return shot.data;
+        },
+        settle,
+        log,
+    });
+    return Buffer.from(data, 'base64');
+}

package/dist/types.d.ts

@@ -27,6 +27,12 @@ export interface WitnessDriver {
      * Safari drivers, which fall back to the viewport screenshot.
      */
     sendAndGetDevToolsCommand?<T = unknown>(cmd: string, params?: object): Promise<T>;
+    /**
+     * selenium-webdriver's `driver.getCapabilities()`. Optional: when present,
+     * the browser, its version and the driver are recorded as capture
+     * provenance in the capture's metadata.json.
+     */
+    getCapabilities?(): Promise<unknown>;
 }
 /**
  * Options for a single witness() call. All optional.

package/dist/witness.js

@@ -58,6 +58,9 @@ exports.witness = witness;
 const witness_1 = require("@testivai/witness");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const full_page_1 = require("./capture/full-page");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const ADAPTER_VERSION = require('../package.json').version;
 /** id of the style element injected for the duration of a capture */
 const STYLE_ID = '__testivai_capture_css__';
 /**
@@ -153,18 +156,22 @@ async function waitForFonts(driver) {
 }
 /**
  * Full-page screenshot where the driver supports it, viewport otherwise.
- * Returns a PNG Buffer.
+ * Returns the PNG and the capture method it came from.
  */
 async function captureScreenshot(driver) {
     // Chromium drivers expose raw CDP; captureBeyondViewport gives a true
     // full-page capture without resizing the window (which breaks 100vh
-    // layouts — the reason we never use the resize trick).
+    // layouts — the reason we never use the resize trick). It waits for a
+    // fresh frame and captures until two in a row match: Chrome can return a
+    // frame painted for the wrong viewport while it sets up the capture
+    // (capture/full-page.ts).
     if (typeof driver.sendAndGetDevToolsCommand === 'function') {
+        const captureLog = process.env.TESTIVAI_DEBUG === 'true'
+            ? (message) => console.log(`[TestivAI] Full-page capture: ${message}`)
+            : undefined;
         try {
-            const result = await driver.sendAndGetDevToolsCommand('Page.captureScreenshot', { captureBeyondViewport: true, format: 'png' });
-            if (result && typeof result.data === 'string' && result.data.length > 0) {
-                return Buffer.from(result.data, 'base64');
-            }
+            const png = await (0, full_page_1.captureFullPageScreenshot)(driver, captureLog);
+            return { png, method: witness_1.CAPTURE_METHODS.CDP_FULL_PAGE };
         }
         catch {
             // fall through to the viewport screenshot
@@ -174,7 +181,7 @@ async function captureScreenshot(driver) {
     if (typeof base64 !== 'string' || base64.length === 0) {
         throw new Error('testivai.witness: driver.takeScreenshot() returned an empty value');
     }
-    return Buffer.from(base64, 'base64');
+    return { png: Buffer.from(base64, 'base64'), method: witness_1.CAPTURE_METHODS.WEBDRIVER_VIEWPORT };
 }
 /**
  * Capture a screenshot + DOM and write them as a temp snapshot.
@@ -198,10 +205,35 @@ async function witness(driver, name, options = {}) {
     if (options.variant) {
         name = `${name}__${options.variant.replace(/[^a-z0-9_-]+/gi, '_').toLowerCase()}`;
     }
+    const localConfig = (0, witness_1.loadLocalConfig)(process.cwd());
+    // Capture provenance: what the page is rendered with, measured before
+    // anything is injected, plus the session's capabilities. Best-effort.
+    let renderProbe = null;
+    let capabilities = null;
+    if (typeof driver.executeScript === 'function') {
+        try {
+            renderProbe = await driver.executeScript(`return ${witness_1.RENDER_PROBE_EXPRESSION}`);
+        }
+        catch {
+            // no probe: no render settings recorded
+        }
+    }
+    if (typeof driver.getCapabilities === 'function') {
+        try {
+            capabilities = await driver.getCapabilities();
+        }
+        catch {
+            // no capabilities: the probe's user agent is the fallback
+        }
+    }
+    const browserName = (0, witness_1.browserFromCapabilities)(capabilities)?.browser.name ?? (() => {
+        const ua = (0, witness_1.parseRenderProbe)(renderProbe)?.userAgent;
+        return (ua ? (0, witness_1.browserFromUserAgent)(ua)?.name : undefined) ?? 'unknown';
+    })();
+    name = (0, witness_1.applyEnvironmentPolicyToName)(name, { browser: { name: browserName }, os: { platform: process.platform } }, localConfig.environmentPolicy);
     // 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 ?? [])]),
@@ -221,8 +253,9 @@ async function witness(driver, name, options = {}) {
     }
     // 1. Capture screenshot (full-page on Chromium, viewport elsewhere)
     let screenshot;
+    let captureMethod;
     try {
-        screenshot = await captureScreenshot(driver);
+        ({ png: screenshot, method: captureMethod } = await captureScreenshot(driver));
     }
     finally {
         if (injected)
@@ -275,6 +308,20 @@ 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);
+    const environment = (0, witness_1.webDriverEnvironment)({
+        capabilities,
+        probe: renderProbe,
+        adapter: { name: '@testivai/witness-selenium', version: ADAPTER_VERSION, captureMethod },
+        framework: { name: 'selenium-webdriver', version: (0, witness_1.installedPackageVersion)('selenium-webdriver') },
+    });
+    if (environment) {
+        try {
+            store.writeTempMetadata(name, { name, environment });
+        }
+        catch {
+            // without it the compare cannot tell rendering drift from noise for this capture
+        }
+    }
     // 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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testivai/witness-selenium",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "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": "2.4.0"
+    "@testivai/witness": "2.5.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",