@testivai/witness-playwright 2.0.10 → 2.1.0

package/README.md

@@ -100,8 +100,10 @@ jobs:
       - run: npm ci
       - run: npx playwright install chromium
       - run: npx playwright test
-      - uses: testivai/testivai-action@v1
-        if: always()
+      # After a failing test too: the reporter writes the report whatever
+      # the tests did, and the action posts it.
+      - uses: testivai/testivai-oss@v1
+        if: ${{ !cancelled() }}
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           report-dir: visual-report

package/dist/capture/element-map.d.ts

@@ -4,5 +4,5 @@
  * injects the *same* page-side function. Keeping this shim means existing
  * imports and unit tests continue to work unchanged.
  */
-export { collectElementMap, buildElementMapExpression, DEFAULT_MAX_ELEMENTS, } from '@testivai/witness';
+export { collectElementMap, buildElementMapExpression, DEFAULT_MAX_ELEMENTS, normalizeElementIdAttributes, } from '@testivai/witness';
 export type { CollectedElement } from '@testivai/witness';

package/dist/capture/element-map.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_MAX_ELEMENTS = exports.buildElementMapExpression = exports.collectElementMap = void 0;
+exports.normalizeElementIdAttributes = exports.DEFAULT_MAX_ELEMENTS = exports.buildElementMapExpression = exports.collectElementMap = void 0;
 /**
  * Re-export of the canonical element-map collector, which now lives in
  * `@testivai/witness` so every adapter (Playwright, Selenium, WebdriverIO)
@@ -11,3 +11,4 @@ var witness_1 = require("@testivai/witness");
 Object.defineProperty(exports, "collectElementMap", { enumerable: true, get: function () { return witness_1.collectElementMap; } });
 Object.defineProperty(exports, "buildElementMapExpression", { enumerable: true, get: function () { return witness_1.buildElementMapExpression; } });
 Object.defineProperty(exports, "DEFAULT_MAX_ELEMENTS", { enumerable: true, get: function () { return witness_1.DEFAULT_MAX_ELEMENTS; } });
+Object.defineProperty(exports, "normalizeElementIdAttributes", { enumerable: true, get: function () { return witness_1.normalizeElementIdAttributes; } });

package/dist/capture/emulation.d.ts

@@ -0,0 +1,41 @@
+import type { Page } from '@playwright/test';
+/**
+ * Device emulation around the default full-page capture.
+ *
+ * The capture runs `Page.captureScreenshot` with `captureBeyondViewport` over
+ * a CDP session of our own. Chrome resizes the page for it and afterwards
+ * restores that session's emulation, which is none: the device emulation
+ * Playwright set on its own session is gone. Measured on the Pixel 7 profile:
+ * devicePixelRatio 2.625 → 1 and the touch pointer gone (`pointer: coarse`
+ * and `hover: none` false; maxTouchPoints 1 → 0 on Chrome 153, kept on
+ * Chrome 156) for the rest of the test. The image itself is
+ * rendered at a pixel ratio of 1 (412 px wide for a 412 px viewport).
+ *
+ * witness() reads the emulation before and right after the capture, records
+ * the pixel ratio the image was rendered at, and restores what the capture
+ * dropped once it has measured everything else in the page (the element map
+ * must stay aligned with the 1× image).
+ */
+export interface EmulationState {
+    dpr: number;
+    maxTouchPoints: number;
+    /** `(pointer: coarse)`: what touch emulation means to the page's CSS. */
+    coarsePointer: boolean;
+}
+/** Evaluated in the page; a self-contained expression. */
+export declare const EMULATION_PROBE = "({ dpr: window.devicePixelRatio, maxTouchPoints: navigator.maxTouchPoints, coarsePointer: window.matchMedia('(pointer: coarse)').matches })";
+/** The page's pixel ratio and touch points, or null when the page cannot say. */
+export declare function readEmulation(page: Pick<Page, 'evaluate'>): Promise<EmulationState | null>;
+/**
+ * Put back what the capture dropped: the pixel ratio (Playwright re-applies
+ * its device metrics, mobile flag included, on setViewportSize) and touch
+ * emulation. The page sees two resize events, after a capture that resized
+ * it already. Nothing is done when nothing changed, so a profile the capture
+ * leaves alone is never touched. Best effort: never fails the capture.
+ */
+export declare function restoreEmulation(page: Page, before: EmulationState | null): Promise<void>;
+/**
+ * The render probe with the pixel ratio the image was rendered at: the CDP
+ * capture renders at 1 whatever the profile says.
+ */
+export declare function withCapturedScale(probe: unknown, atCapture: EmulationState | null): unknown;

package/dist/capture/emulation.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMULATION_PROBE = void 0;
+exports.readEmulation = readEmulation;
+exports.restoreEmulation = restoreEmulation;
+exports.withCapturedScale = withCapturedScale;
+/** Evaluated in the page; a self-contained expression. */
+exports.EMULATION_PROBE = "({ dpr: window.devicePixelRatio, maxTouchPoints: navigator.maxTouchPoints, coarsePointer: window.matchMedia('(pointer: coarse)').matches })";
+/** The page's pixel ratio and touch points, or null when the page cannot say. */
+async function readEmulation(page) {
+    try {
+        const raw = (await page.evaluate(exports.EMULATION_PROBE));
+        if (raw && typeof raw.dpr === 'number' && typeof raw.maxTouchPoints === 'number') {
+            return { dpr: raw.dpr, maxTouchPoints: raw.maxTouchPoints, coarsePointer: raw.coarsePointer === true };
+        }
+    }
+    catch {
+        // a page that cannot be evaluated has nothing to restore
+    }
+    return null;
+}
+/**
+ * Touch emulation lives on the CDP session that set it, and goes when that
+ * session detaches, so the session that restores it stays attached for the
+ * page's lifetime, one per page.
+ */
+const touchSessions = new WeakMap();
+/**
+ * Put back what the capture dropped: the pixel ratio (Playwright re-applies
+ * its device metrics, mobile flag included, on setViewportSize) and touch
+ * emulation. The page sees two resize events, after a capture that resized
+ * it already. Nothing is done when nothing changed, so a profile the capture
+ * leaves alone is never touched. Best effort: never fails the capture.
+ */
+async function restoreEmulation(page, before) {
+    if (!before)
+        return;
+    const now = await readEmulation(page);
+    if (!now)
+        return;
+    if (now.dpr === before.dpr && now.maxTouchPoints === before.maxTouchPoints && now.coarsePointer === before.coarsePointer)
+        return;
+    try {
+        // Touch emulation, whenever the page had touch and its touch points or
+        // pointer media changed. What the capture drops depends on Chrome:
+        // Chrome 153 drops the touch points and `pointer: coarse`; Chrome 156
+        // keeps the touch points and drops `pointer: coarse` and `hover: none`.
+        // Sending it again brings back all three; device metrics alone do not.
+        if (before.maxTouchPoints > 0 &&
+            (now.maxTouchPoints !== before.maxTouchPoints || now.coarsePointer !== before.coarsePointer)) {
+            let session = touchSessions.get(page);
+            if (!session) {
+                session = await page.context().newCDPSession(page);
+                touchSessions.set(page, session);
+            }
+            await session.send('Emulation.setTouchEmulationEnabled', { enabled: true, maxTouchPoints: before.maxTouchPoints });
+        }
+        // The device metrics (pixel ratio, mobile). Playwright does not send a viewport equal to
+        // the last one it set, so re-applying the same size does nothing: step
+        // 1 px away and back.
+        const viewport = page.viewportSize();
+        if (viewport) {
+            await page.setViewportSize({ width: viewport.width, height: viewport.height + 1 });
+            await page.setViewportSize(viewport);
+        }
+    }
+    catch {
+        // the capture is written; a page we cannot restore stays as Chrome left it
+    }
+}
+/**
+ * The render probe with the pixel ratio the image was rendered at: the CDP
+ * capture renders at 1 whatever the profile says.
+ */
+function withCapturedScale(probe, atCapture) {
+    if (!atCapture || !probe || typeof probe !== 'object' || Array.isArray(probe))
+        return probe;
+    return { ...probe, deviceScaleFactor: atCapture.dpr };
+}

package/dist/capture/health.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Capture health for the Playwright adapter: what failed to load (web fonts,
+ * stylesheets, images, requests that answered 400 or more), read by the
+ * shared probe in the page right AFTER the screenshot, so it sees what loaded,
+ * and BEFORE the ignoreSelectors and stabilize styles come off: removing them
+ * shows elements that were hidden in the capture, and a web font only such an
+ * element uses starts loading then, for glyphs that were never in the image.
+ * Merged into the capture's metadata.json as `health`; approving freezes it
+ * into the baseline's. See capture/health.ts in @testivai/witness for the
+ * shape and report/health.ts for when a capture is unhealthy.
+ */
+import { type BaselineStore, type CaptureHealth } from '@testivai/witness';
+/** The part of a Playwright Page this needs (structural, so tests need no browser). */
+export interface EvaluatesExpressions {
+    evaluate(expression: string): Promise<unknown>;
+}
+/**
+ * Run the probe. Best-effort, like the rest of the metadata: a probe that
+ * throws or returns something malformed gives null, which reads as "not
+ * checked", never as healthy.
+ */
+export declare function probeCaptureHealth(page: EvaluatesExpressions): Promise<CaptureHealth | null>;
+/** Record a probe's result in the capture's metadata.json; nothing for null (not checked). */
+export declare function recordCaptureHealth(store: BaselineStore, name: string, health: CaptureHealth | null): void;

package/dist/capture/health.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probeCaptureHealth = probeCaptureHealth;
+exports.recordCaptureHealth = recordCaptureHealth;
+/**
+ * Capture health for the Playwright adapter: what failed to load (web fonts,
+ * stylesheets, images, requests that answered 400 or more), read by the
+ * shared probe in the page right AFTER the screenshot, so it sees what loaded,
+ * and BEFORE the ignoreSelectors and stabilize styles come off: removing them
+ * shows elements that were hidden in the capture, and a web font only such an
+ * element uses starts loading then, for glyphs that were never in the image.
+ * Merged into the capture's metadata.json as `health`; approving freezes it
+ * into the baseline's. See capture/health.ts in @testivai/witness for the
+ * shape and report/health.ts for when a capture is unhealthy.
+ */
+const witness_1 = require("@testivai/witness");
+/**
+ * Run the probe. Best-effort, like the rest of the metadata: a probe that
+ * throws or returns something malformed gives null, which reads as "not
+ * checked", never as healthy.
+ */
+async function probeCaptureHealth(page) {
+    try {
+        return (0, witness_1.parseHealth)(await page.evaluate(witness_1.HEALTH_PROBE_EXPRESSION));
+    }
+    catch {
+        return null;
+    }
+}
+/** Record a probe's result in the capture's metadata.json; nothing for null (not checked). */
+function recordCaptureHealth(store, name, health) {
+    if (!health)
+        return;
+    try {
+        store.writeTempMetadata(name, { health });
+    }
+    catch {
+        // not checked: the screenshot path never depends on it
+    }
+}

package/dist/reporter.js

@@ -88,6 +88,10 @@ class TestivAIPlaywrightReporter {
                 console.log(`\n  TestivAI: ${where} — captured to .testivai/temp/, comparison skipped.`);
                 console.log('  Collect every shard\'s .testivai/temp/, then compare once:');
                 console.log('    npx testivai merge-captures <dirs...> && npx testivai report --fail-on-diff');
+                // A CI step runs only on success by default, so one failing test would
+                // skip the comparison and leave the pull request without a report.
+                console.log('  Run that step even when a test fails: in GitHub Actions, `if: ${{ !cancelled() }}`');
+                console.log('  (and on a job that `needs` the shards, too).');
                 return;
             }
             // ── Generate the HTML report ──────────────────────────────────────────

package/dist/snapshot.js

@@ -48,7 +48,9 @@ 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 health_1 = require("./capture/health");
 const full_page_1 = require("./capture/full-page");
+const emulation_1 = require("./capture/emulation");
 /**
  * Generates a safe filename from a URL.
  * @param pageUrl The URL of the page.
@@ -117,7 +119,11 @@ async function snapshot(page, testInfo, name, config) {
     // 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;
+    // The device emulation before the capture, which the CDP capture drops
+    // (capture/emulation.ts); restored once everything is measured.
+    const emulationBefore = await (0, emulation_1.readEmulation)(page);
+    const localConfig = (0, witness_1.loadLocalConfig)(process.cwd());
+    const environmentPolicy = localConfig.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.
@@ -307,6 +313,12 @@ async function snapshot(page, testInfo, name, config) {
             }
         }
     }
+    else if (!hasCdp(page)) {
+        // WebKit and Firefox have no CDP: Playwright's own full-page screenshot
+        // is the capture there, not a fallback from a failure.
+        captureMethod = witness_1.CAPTURE_METHODS.PLAYWRIGHT_FULL_PAGE;
+        await page.screenshot({ path: screenshotPath, fullPage: true });
+    }
     else {
         // Use browser capture approach (default)
         if (process.env.TESTIVAI_DEBUG === 'true') {
@@ -356,12 +368,28 @@ async function snapshot(page, testInfo, name, config) {
             await client.detach();
         }
         catch (error) {
-            console.error('[TestivAI] Browser screenshot failed:', error.message);
+            // An engine we could not name (a persistent context has no browser())
+            // answers that CDP is Chromium-only: the expected path, not a failure.
+            if (!/only available in Chromium/i.test(String(error?.message))) {
+                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 });
         }
     }
+    // Capture health: what failed to load (web fonts, stylesheets, images,
+    // requests that answered 400+), read right after the screenshot (every
+    // capture path above ends here) so it sees what loaded, and before the
+    // ignoreSelectors and stabilize styles come off: removing them shows
+    // elements that were hidden in the capture, and a web font only they use
+    // starts loading then, for glyphs that were never in the image. A font that
+    // fell back leaves the DOM and the declared styles the same, so only this
+    // tells an unhealthy capture from render noise. Recorded with the metadata.
+    const captureHealth = await (0, health_1.probeCaptureHealth)(page);
+    // The pixel ratio the image was rendered at (1 after a CDP capture,
+    // whatever the profile says): recorded with the capture's provenance.
+    const emulationAtCapture = await (0, emulation_1.readEmulation)(page);
     // Restore any elements hidden for ignoreSelectors
     if (ignoreStyleEl) {
         await ignoreStyleEl.evaluate((el) => el.remove()).catch(() => { });
@@ -480,27 +508,58 @@ async function snapshot(page, testInfo, name, config) {
             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 });
+            const environment = (0, environment_1.playwrightEnvironment)({
+                testInfo: testInfo ?? {},
+                browserVersion,
+                probe: (0, emulation_1.withCapturedScale)(renderProbe, emulationAtCapture),
+                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
         }
+        // Capture health, probed right after the screenshot (above).
+        (0, health_1.recordCaptureHealth)(new witness_1.BaselineStore(process.cwd()), snapshotName, captureHealth);
         // 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
         // side. Best-effort — the screenshot path never depends on it.
         try {
             const mapIgnores = (0, ignore_selectors_1.collectIgnoreSelectors)(process.cwd(), projectConfig, effectiveConfig);
-            const elementMap = await page.evaluate((0, element_map_1.buildElementMapExpression)(undefined, mapIgnores));
+            // Opt-in: paths anchored on attributes such as data-testid. Recorded
+            // with the capture only when set, so the compare can tell paths built
+            // another way; unset, nothing written changes.
+            const idAttributes = (0, witness_1.normalizeElementIdAttributes)(localConfig.elementIdAttributes);
+            const elementMap = await page.evaluate((0, element_map_1.buildElementMapExpression)(undefined, mapIgnores, idAttributes));
             if (Array.isArray(elementMap) && elementMap.length > 0) {
                 await fs.writeJson(path.join(localSnapshotDir, 'elements.json'), elementMap);
+                if (idAttributes.length > 0) {
+                    new witness_1.BaselineStore(process.cwd()).writeTempMetadata(snapshotName, { elementIdAttributes: idAttributes });
+                }
             }
         }
         catch {
             // missing elements.json only disables attribution for this capture
         }
     }
+    // Last, after everything measured in the page at the capture's scale:
+    // put back the device emulation the CDP capture dropped.
+    await (0, emulation_1.restoreEmulation)(page, emulationBefore);
+}
+/**
+ * Whether the page's engine can have a CDP session. False only when the
+ * browser names an engine other than Chromium; unknown (no browser(), as in a
+ * persistent context) is tried, and its answer handled where it fails.
+ */
+function hasCdp(page) {
+    try {
+        const name = page.context().browser()?.browserType().name();
+        return name === undefined || name === 'chromium';
+    }
+    catch {
+        return true;
+    }
 }
 /**
  * Read the global `mask` list from .testivai/config.json (selector strings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testivai/witness-playwright",
-  "version": "2.0.10",
+  "version": "2.1.0",
   "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.5.0"
+    "@testivai/witness": "2.6.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.63.0",