@testivai/witness-playwright 2.0.8 → 2.0.10

package/dist/capture/environment.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Capture provenance for the Playwright adapter: the `environment` block
+ * witness() records in the capture's metadata.json (see capture/environment.ts
+ * in @testivai/witness for the shape and why it matters).
+ *
+ * Sources, in order of trust: the project's own `use` settings and Playwright's
+ * browser.version(); the in-page render probe (what the page is actually
+ * rendered with); the user agent as the fallback for a browser that cannot be
+ * asked (a persistent context has no browser()). Nothing is guessed: what none
+ * of them says is left out, or null for the version.
+ */
+import { type CaptureEnvironment, type HostEnvironment } from '@testivai/witness';
+/** The parts of Playwright's TestInfo this reads (structural, so tests need no runner). */
+export interface TestInfoLike {
+    config?: {
+        version?: string;
+    };
+    project?: {
+        name?: string;
+        use?: Record<string, unknown>;
+    };
+    file?: string;
+}
+/** The engine witness() runs in: the project's browserName, else the user agent, else Playwright's default. */
+export declare function playwrightBrowserName(testInfo: TestInfoLike, userAgent: string | undefined): string;
+export interface PlaywrightEnvironmentInput {
+    testInfo: TestInfoLike;
+    /** page.context().browser()?.version(), or null when there is no browser to ask. */
+    browserVersion: string | null;
+    /** The raw RENDER_PROBE_EXPRESSION result (null when the probe failed). */
+    probe: unknown;
+    captureMethod: string;
+    /** Injected in tests; collected from this machine otherwise. */
+    host?: HostEnvironment;
+}
+export declare function playwrightEnvironment(input: PlaywrightEnvironmentInput): CaptureEnvironment;

package/dist/capture/environment.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.playwrightBrowserName = playwrightBrowserName;
+exports.playwrightEnvironment = playwrightEnvironment;
+/**
+ * Capture provenance for the Playwright adapter: the `environment` block
+ * witness() records in the capture's metadata.json (see capture/environment.ts
+ * in @testivai/witness for the shape and why it matters).
+ *
+ * Sources, in order of trust: the project's own `use` settings and Playwright's
+ * browser.version(); the in-page render probe (what the page is actually
+ * rendered with); the user agent as the fallback for a browser that cannot be
+ * asked (a persistent context has no browser()). Nothing is guessed: what none
+ * of them says is left out, or null for the version.
+ */
+const witness_1 = require("@testivai/witness");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const ADAPTER_VERSION = require('../../package.json').version;
+/** The engine witness() runs in: the project's browserName, else the user agent, else Playwright's default. */
+function playwrightBrowserName(testInfo, userAgent) {
+    const configured = testInfo.project?.use?.browserName;
+    if (typeof configured === 'string' && configured.length > 0)
+        return configured;
+    return (0, witness_1.browserFromUserAgent)(userAgent ?? '')?.name ?? 'chromium';
+}
+function playwrightEnvironment(input) {
+    const { testInfo } = input;
+    const use = testInfo.project?.use ?? {};
+    const probed = (0, witness_1.parseRenderProbe)(input.probe);
+    const fromUa = probed?.userAgent ? (0, witness_1.browserFromUserAgent)(probed.userAgent) : null;
+    const browser = {
+        name: playwrightBrowserName(testInfo, probed?.userAgent),
+        version: input.browserVersion ?? fromUa?.version ?? null,
+    };
+    if (typeof use.channel === 'string' && use.channel.length > 0)
+        browser.channel = use.channel;
+    if (typeof use.headless === 'boolean')
+        browser.headless = use.headless;
+    else if (fromUa?.headless)
+        browser.headless = true;
+    const file = testInfo.file ?? '';
+    const projectName = testInfo.project?.name;
+    return (0, witness_1.buildCaptureEnvironment)({
+        host: input.host ?? (0, witness_1.collectHostEnvironment)(),
+        browser,
+        framework: {
+            name: 'playwright',
+            version: testInfo.config?.version ?? null,
+            language: /\.[cm]?tsx?$/.test(file) ? 'typescript' : 'javascript',
+            runner: '@playwright/test',
+        },
+        adapter: { name: '@testivai/witness-playwright', version: ADAPTER_VERSION, captureMethod: input.captureMethod },
+        render: probed?.render,
+        project: typeof projectName === 'string' && projectName.length > 0 ? projectName : undefined,
+    });
+}

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

@@ -0,0 +1,22 @@
+import type { CDPSession, Page } from '@playwright/test';
+import { type CaptureLog } from '@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: on testivai-site's CI,
+ * em-sized text on the home page was drawn at its `max-width: 480px` size in
+ * some captures, so an unchanged page read as 4.13% changed while its measured
+ * layout matched the baseline. See capture/stable-capture.ts in
+ * @testivai/witness, which the standalone CLI shares.
+ *
+ * A stable page costs one extra screenshot.
+ *
+ * @param page The page being captured; used for the in-page frame wait.
+ * @param client A CDP session attached to `page`.
+ * @param log Optional debug sink.
+ * @returns The PNG bytes of the kept capture.
+ */
+export declare function captureFullPageScreenshot(page: Page, client: CDPSession, log?: CaptureLog): Promise<Buffer>;

package/dist/capture/full-page.js

@@ -0,0 +1,42 @@
+"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: on testivai-site's CI,
+ * em-sized text on the home page was drawn at its `max-width: 480px` size in
+ * some captures, so an unchanged page read as 4.13% changed while its measured
+ * layout matched the baseline. See capture/stable-capture.ts in
+ * @testivai/witness, which the standalone CLI shares.
+ *
+ * A stable page costs one extra screenshot.
+ *
+ * @param page The page being captured; used for the in-page frame wait.
+ * @param client A CDP session attached to `page`.
+ * @param log Optional debug sink.
+ * @returns The PNG bytes of the kept capture.
+ */
+async function captureFullPageScreenshot(page, client, log) {
+    const waitOnce = async () => (await page.evaluate(witness_1.FRESH_FRAME_EXPRESSION)) === true;
+    const settle = () => (0, witness_1.settleFreshFrame)(waitOnce, log);
+    await settle();
+    const layoutMetrics = await client.send('Page.getLayoutMetrics');
+    const width = Math.ceil(layoutMetrics.contentSize.width);
+    const height = Math.ceil(layoutMetrics.contentSize.height);
+    log?.(`page ${width}x${height}, viewport ${layoutMetrics.layoutViewport?.clientWidth}x${layoutMetrics.layoutViewport?.clientHeight}`);
+    const data = await (0, witness_1.captureUntilStable)({
+        capture: async () => (await client.send('Page.captureScreenshot', {
+            format: 'png',
+            captureBeyondViewport: true,
+            clip: { x: 0, y: 0, width, height, scale: 1 },
+        })).data,
+        settle,
+        log,
+    });
+    return Buffer.from(data, 'base64');
+}

package/dist/snapshot.js

@@ -46,6 +46,9 @@ const loader_1 = require("./config/loader");
 const ignore_selectors_1 = require("./config/ignore-selectors");
 const element_map_1 = require("./capture/element-map");
 const stabilize_1 = require("./config/stabilize");
+const witness_1 = require("@testivai/witness");
+const environment_1 = require("./capture/environment");
+const full_page_1 = require("./capture/full-page");
 /**
  * Generates a safe filename from a URL.
  * @param pageUrl The URL of the page.
@@ -110,7 +113,15 @@ async function snapshot(page, testInfo, name, config) {
     }
     const outputDir = path.join(process.cwd(), '.testivai', 'temp');
     await fs.ensureDir(outputDir);
-    const snapshotName = effectiveSnapshotName(name || getSnapshotNameFromUrl(page.url()), testInfo);
+    // What the page is rendered with, measured before anything is injected:
+    // recorded as capture provenance, and its user agent names the engine for
+    // environmentPolicy "separate" when the project does not.
+    const renderProbe = await page.evaluate(witness_1.RENDER_PROBE_EXPRESSION).catch(() => null);
+    const environmentPolicy = (0, witness_1.loadLocalConfig)(process.cwd()).environmentPolicy;
+    const snapshotName = (0, witness_1.applyEnvironmentPolicyToName)(effectiveSnapshotName(name || getSnapshotNameFromUrl(page.url()), testInfo), { browser: { name: (0, environment_1.playwrightBrowserName)(testInfo ?? {}, (0, witness_1.parseRenderProbe)(renderProbe)?.userAgent) }, os: { platform: process.platform } }, environmentPolicy);
+    // Which path took the screenshot (set below): part of the provenance, since
+    // another method changes the image and often its size.
+    let captureMethod = witness_1.CAPTURE_METHODS.CDP_FULL_PAGE;
     const timestamp = Date.now();
     const safeName = snapshotName.replace(/[^a-z0-9]/gi, '_').toLowerCase();
     const baseFilename = `${timestamp}_${safeName}`;
@@ -224,9 +235,11 @@ async function snapshot(page, testInfo, name, config) {
         }
         // If only one capture needed, just take a regular screenshot
         if (numCaptures <= 1) {
+            captureMethod = witness_1.CAPTURE_METHODS.PLAYWRIGHT_FULL_PAGE;
             await page.screenshot({ path: screenshotPath, fullPage: true });
         }
         else {
+            captureMethod = witness_1.CAPTURE_METHODS.STITCHED_FULL_PAGE;
             // Scroll-and-stitch approach
             const screenshots = [];
             for (let i = 0; i < numCaptures; i++) {
@@ -322,33 +335,15 @@ async function snapshot(page, testInfo, name, config) {
             });
             // Wait a bit for styles to apply
             await page.waitForTimeout(100);
-            // Get layout metrics to determine full page size
-            const layoutMetrics = await client.send('Page.getLayoutMetrics');
-            // Calculate full page dimensions
-            const pageWidth = Math.ceil(layoutMetrics.contentSize.width);
-            const pageHeight = Math.ceil(layoutMetrics.contentSize.height);
-            if (process.env.TESTIVAI_DEBUG === 'true') {
-                console.log('[TestivAI] Browser layout metrics:', {
-                    pageWidth,
-                    pageHeight,
-                    viewportWidth: layoutMetrics.layoutViewport.clientWidth,
-                    viewportHeight: layoutMetrics.layoutViewport.clientHeight
-                });
-            }
-            // Capture screenshot with captureBeyondViewport: true
-            const screenshot = await client.send('Page.captureScreenshot', {
-                format: 'png',
-                captureBeyondViewport: true,
-                clip: {
-                    x: 0,
-                    y: 0,
-                    width: pageWidth,
-                    height: pageHeight,
-                    scale: 1
-                }
-            });
+            // Wait for a fresh frame, measure, and capture beyond the viewport until
+            // two captures in a row match: Chrome can return a frame painted for the
+            // wrong viewport while it sets up the capture (capture/full-page.ts).
+            const captureLog = process.env.TESTIVAI_DEBUG === 'true'
+                ? (message) => console.log(`[TestivAI] Full-page capture: ${message}`)
+                : undefined;
+            const png = await (0, full_page_1.captureFullPageScreenshot)(page, client, captureLog);
             // Save the screenshot
-            await fs.writeFile(screenshotPath, Buffer.from(screenshot.data, 'base64'));
+            await fs.writeFile(screenshotPath, png);
             // Remove the temporary style tag
             await page.evaluate(`
         const styleTags = document.querySelectorAll('style');
@@ -363,6 +358,7 @@ async function snapshot(page, testInfo, name, config) {
         catch (error) {
             console.error('[TestivAI] Browser screenshot failed:', error.message);
             // Fallback to regular screenshot
+            captureMethod = witness_1.CAPTURE_METHODS.PLAYWRIGHT_FULL_PAGE;
             await page.screenshot({ path: screenshotPath, fullPage: true });
         }
     }
@@ -473,6 +469,23 @@ async function snapshot(page, testInfo, name, config) {
         catch {
             // metadata is an enhancement; the screenshot path never depends on it
         }
+        // Capture provenance: the environment this capture was taken in, merged
+        // into metadata.json (approving freezes it into the baseline). Best-effort
+        // like the rest: the screenshot path never depends on it.
+        try {
+            let browserVersion = null;
+            try {
+                browserVersion = page.context().browser()?.version() ?? null;
+            }
+            catch {
+                // a persistent context has no browser(): the probe's user agent is the fallback
+            }
+            const environment = (0, environment_1.playwrightEnvironment)({ testInfo: testInfo ?? {}, browserVersion, probe: renderProbe, captureMethod });
+            new witness_1.BaselineStore(process.cwd()).writeTempMetadata(snapshotName, { name: snapshotName, environment });
+        }
+        catch {
+            // no environment only means the compare cannot tell drift from noise for this capture
+        }
         // Element map: layout + computed-style digest for every visible
         // element, powering attribution ("WHICH element changed"), exact
         // shift classification, and the style fingerprint on the compare

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testivai/witness-playwright",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "description": "Playwright adapter for TestivAI Witness — local-first visual regression with pixel + DOM comparison",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
   "dependencies": {
     "fs-extra": "^11.4.0",
     "sharp": "^0.35.4",
-    "@testivai/witness": "2.3.1"
+    "@testivai/witness": "2.5.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.63.0",