@testivai/witness-selenium 0.3.10 → 0.3.11

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/witness.js

@@ -58,6 +58,7 @@ 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");
 /** id of the style element injected for the duration of a capture */
 const STYLE_ID = '__testivai_capture_css__';
 /**
@@ -158,13 +159,16 @@ async function waitForFonts(driver) {
 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');
-            }
+            return await (0, full_page_1.captureFullPageScreenshot)(driver, captureLog);
         }
         catch {
             // fall through to the viewport screenshot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testivai/witness-selenium",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "Selenium WebDriver adapter for TestivAI Witness — local-first visual regression with pixel + DOM comparison",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",