@testivai/witness-selenium 0.3.11 → 0.4.0

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

@@ -59,6 +59,8 @@ 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__';
 /**
@@ -154,7 +156,7 @@ 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
@@ -168,7 +170,8 @@ async function captureScreenshot(driver) {
             ? (message) => console.log(`[TestivAI] Full-page capture: ${message}`)
             : undefined;
         try {
-            return await (0, full_page_1.captureFullPageScreenshot)(driver, captureLog);
+            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
@@ -178,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.
@@ -202,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 ?? [])]),
@@ -225,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)
@@ -262,10 +291,13 @@ async function witness(driver, name, options = {}) {
     //    side. The injected function is the SAME one the Playwright adapter
     //    uses (`@testivai/witness`), so both lanes produce identical maps.
     //    Selenium's executeScript needs an explicit `return`.
+    // Opt-in: paths anchored on attributes such as data-testid (config
+    // `elementIdAttributes`), recorded with the capture only when set.
+    const idAttributes = (0, witness_1.normalizeElementIdAttributes)(localConfig.elementIdAttributes);
     let elementMap;
     if (!options.skipElementMap && typeof driver.executeScript === 'function') {
         try {
-            const expr = (0, witness_1.buildElementMapExpression)(options.maxElements ?? witness_1.DEFAULT_MAX_ELEMENTS, ignoreSelectors);
+            const expr = (0, witness_1.buildElementMapExpression)(options.maxElements ?? witness_1.DEFAULT_MAX_ELEMENTS, ignoreSelectors, idAttributes);
             const result = await driver.executeScript(`return ${expr}`);
             if (Array.isArray(result) && result.length > 0) {
                 elementMap = result;
@@ -279,6 +311,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`
@@ -292,6 +338,8 @@ async function witness(driver, name, options = {}) {
         try {
             fs.mkdirSync(tempDir, { recursive: true });
             fs.writeFileSync(path.join(tempDir, 'elements.json'), JSON.stringify(elementMap));
+            if (idAttributes.length > 0)
+                store.writeTempMetadata(name, { elementIdAttributes: idAttributes });
         }
         catch {
             // A map we cannot persist is not worth failing a capture over.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testivai/witness-selenium",
-  "version": "0.3.11",
+  "version": "0.4.0",
   "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.6.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",