@testivai/witness-selenium 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TestivAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# @testivai/witness-selenium
+
+Selenium WebDriver adapter for [TestivAI Witness](https://github.com/mcbuddy/testivai-oss) — local-first visual regression testing with pixel + DOM comparison. No cloud account, nothing uploaded.
+
+Shares baselines, tolerances, the HTML report, and the PR approval flow with every other TestivAI adapter (Playwright, WebdriverIO, Python, Java) through one on-disk contract.
+
+## Install
+
+```bash
+npm i -D @testivai/witness-selenium @testivai/witness selenium-webdriver
+```
+
+## Use
+
+```js
+const { Builder } = require('selenium-webdriver');
+const { testivai } = require('@testivai/witness-selenium');
+
+const driver = await new Builder().forBrowser('chrome').build();
+await driver.get('http://localhost:3000');
+await testivai.witness(driver, 'homepage');
+await driver.quit();
+```
+
+Then compare against baselines and render the report:
+
+```bash
+npx testivai report            # add --fail-on-diff in CI
+npx testivai approve --all     # promote current captures to baselines
+```
+
+Works inside any runner (Jest, Mocha, plain Node scripts) — the adapter only needs the `driver` object.
+
+## Options
+
+```js
+await testivai.witness(driver, 'pricing', {
+  ignoreSelectors: ['.live-chat', '[data-testid="ad"]'], // hidden from pixels AND the DOM snapshot
+  variant: 'firefox',       // baselines keyed as pricing__firefox
+  stabilize: false,         // skip animation-freeze + font wait for this capture
+  skipDom: true,            // pixel diff only, no noise hint
+});
+```
+
+Global settings (thresholds, tolerances, `ignoreSelectors`) live in `.testivai/config.json` — see the [main docs](https://github.com/mcbuddy/testivai-oss/tree/main/docs).
+
+## Full-page screenshots
+
+- **Chrome / Edge** — true full-page capture via CDP (`captureBeyondViewport`), the same mechanism Playwright uses. Automatic; nothing to configure.
+- **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
+
+Before every capture (default on): CSS animations/transitions complete instantly at their final state, the caret is hidden, smooth scrolling is disabled, and web fonts are awaited (bounded 10s). These are the top causes of flaky visual diffs.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @testivai/witness-selenium
+ *
+ * Selenium WebDriver adapter for the TestivAI Witness OSS toolkit. Pairs
+ * with `@testivai/witness` (the local CLI + diff engine) and shares the
+ * same `.testivai/baselines/` layout as every other TestivAI adapter.
+ *
+ *   import { testivai } from '@testivai/witness-selenium';
+ *   await testivai.witness(driver, 'homepage');
+ *
+ * Then run `npx testivai report` (add `--fail-on-diff` in CI) to compare
+ * against committed baselines and render visual-report/index.html.
+ */
+import { witness } from './witness';
+export { witness } from './witness';
+export type { WitnessDriver, WitnessOptions } from './types';
+/**
+ * Convenience namespace mirroring @testivai/witness-playwright's API:
+ *
+ *   await testivai.witness(driver, 'homepage');
+ */
+export declare const testivai: {
+    witness: typeof witness;
+};
+export declare const VERSION: string;

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * @testivai/witness-selenium
+ *
+ * Selenium WebDriver adapter for the TestivAI Witness OSS toolkit. Pairs
+ * with `@testivai/witness` (the local CLI + diff engine) and shares the
+ * same `.testivai/baselines/` layout as every other TestivAI adapter.
+ *
+ *   import { testivai } from '@testivai/witness-selenium';
+ *   await testivai.witness(driver, 'homepage');
+ *
+ * Then run `npx testivai report` (add `--fail-on-diff` in CI) to compare
+ * against committed baselines and render visual-report/index.html.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.testivai = exports.witness = void 0;
+const witness_1 = require("./witness");
+var witness_2 = require("./witness");
+Object.defineProperty(exports, "witness", { enumerable: true, get: function () { return witness_2.witness; } });
+/**
+ * Convenience namespace mirroring @testivai/witness-playwright's API:
+ *
+ *   await testivai.witness(driver, 'homepage');
+ */
+exports.testivai = {
+    witness: witness_1.witness,
+};
+exports.VERSION = require('../package.json').version;

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Public types for @testivai/witness-selenium.
+ */
+/**
+ * Minimal subset of the selenium-webdriver `WebDriver` the witness function
+ * relies on. Structural typing means consumers can pass any Selenium-shaped
+ * object (real driver or mock) without us pulling `selenium-webdriver`'s
+ * types into our public surface.
+ */
+export interface WitnessDriver {
+    /**
+     * Capture a screenshot of the current viewport. Returns a base64 PNG,
+     * matching selenium-webdriver's `driver.takeScreenshot()` return shape.
+     * Used as the fallback when no full-page mechanism is available.
+     */
+    takeScreenshot(): Promise<string>;
+    /**
+     * Execute a script in the page context. We only use the string form with
+     * trailing args (`arguments[0]`… inside the script).
+     */
+    executeScript<T = unknown>(script: string, ...args: unknown[]): Promise<T>;
+    /**
+     * Chromium-only (chrome.Driver / edge.Driver): raw CDP command. Presence
+     * of this method is how the adapter detects that full-page capture via
+     * `Page.captureScreenshot` (captureBeyondViewport) is available — the
+     * same mechanism Playwright uses under the hood. Absent on Firefox and
+     * Safari drivers, which fall back to the viewport screenshot.
+     */
+    sendAndGetDevToolsCommand?<T = unknown>(cmd: string, params?: object): Promise<T>;
+}
+/**
+ * Options for a single witness() call. All optional.
+ */
+export interface WitnessOptions {
+    /**
+     * Skip DOM capture even if the adapter would normally write dom.html
+     * alongside the screenshot. Use for pages where DOM serialization is
+     * known to be expensive or unstable.
+     */
+    skipDom?: boolean;
+    /**
+     * CSS selectors for elements to hide (`visibility: hidden`) for the
+     * duration of the capture, so dynamic content (timestamps, ads, live
+     * widgets) never contributes to the pixel diff. Merged with the global
+     * `ignoreSelectors` list from `.testivai/config.json`. Matched elements
+     * are also excluded from the DOM snapshot (one consistent semantic).
+     */
+    ignoreSelectors?: string[];
+    /**
+     * Variant key for multi-browser / multi-viewport runs. Folded into the
+     * snapshot name (`<name>__<variant>`) so parallel sessions don't
+     * overwrite each other's baselines. Example: `'firefox'`, `'chrome-1280'`.
+     */
+    variant?: string;
+    /**
+     * Stabilize the page before capture: disable CSS animations/transitions,
+     * hide the caret, and wait for web fonts. Overrides the `stabilize`
+     * setting from `.testivai/config.json` (default true).
+     */
+    stabilize?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Public types for @testivai/witness-selenium.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/witness.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @testivai/witness-selenium — capture function
+ *
+ * The user-facing call inside a Selenium (JavaScript) test:
+ *
+ *   import { testivai } from '@testivai/witness-selenium';
+ *   await testivai.witness(driver, 'homepage');
+ *
+ * Captures a screenshot and the page DOM through Selenium's public APIs,
+ * then writes both into `.testivai/temp/<name>/` using the same
+ * BaselineStore layout as every other TestivAI adapter. Run
+ * `npx testivai report` after the tests to compare against baselines.
+ *
+ * Full-page screenshots per browser:
+ *   - Chromium (Chrome/Edge): CDP `Page.captureScreenshot` with
+ *     captureBeyondViewport via `sendAndGetDevToolsCommand` — the same
+ *     mechanism Playwright uses under the hood
+ *   - Firefox/Safari: the JS bindings expose no full-page API, so the
+ *     capture is viewport-only (keep the window sized to what you want
+ *     compared; baselines are consistent run-to-run either way)
+ */
+import type { WitnessDriver, WitnessOptions } from './types';
+/**
+ * Capture a screenshot + DOM and write them as a temp snapshot.
+ *
+ * @param driver  selenium-webdriver WebDriver (must expose
+ *   `takeScreenshot()` and `executeScript()`).
+ * @param name    Snapshot name. Becomes the directory under
+ *   `.testivai/temp/<name>/` and the key in the rendered report.
+ * @param options Per-call overrides.
+ */
+export declare function witness(driver: WitnessDriver, name: string, options?: WitnessOptions): Promise<void>;

package/dist/witness.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * @testivai/witness-selenium — capture function
+ *
+ * The user-facing call inside a Selenium (JavaScript) test:
+ *
+ *   import { testivai } from '@testivai/witness-selenium';
+ *   await testivai.witness(driver, 'homepage');
+ *
+ * Captures a screenshot and the page DOM through Selenium's public APIs,
+ * then writes both into `.testivai/temp/<name>/` using the same
+ * BaselineStore layout as every other TestivAI adapter. Run
+ * `npx testivai report` after the tests to compare against baselines.
+ *
+ * Full-page screenshots per browser:
+ *   - Chromium (Chrome/Edge): CDP `Page.captureScreenshot` with
+ *     captureBeyondViewport via `sendAndGetDevToolsCommand` — the same
+ *     mechanism Playwright uses under the hood
+ *   - Firefox/Safari: the JS bindings expose no full-page API, so the
+ *     capture is viewport-only (keep the window sized to what you want
+ *     compared; baselines are consistent run-to-run either way)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.witness = witness;
+const witness_1 = require("@testivai/witness");
+/** id of the style element injected for the duration of a capture */
+const STYLE_ID = '__testivai_capture_css__';
+/**
+ * Freezes CSS animations/transitions, hides the caret, and forces instant
+ * scrolling — the top causes of flaky visual diffs. Near-zero durations
+ * (not `none`) let entry animations COMPLETE at their final state.
+ * Mirrors the Playwright adapter's STABILIZE_CSS.
+ */
+const STABILIZE_CSS = '*, *::before, *::after { animation-duration: 0.001s !important; animation-delay: 0s !important; ' +
+    'animation-iteration-count: 1 !important; transition-duration: 0.001s !important; ' +
+    'transition-delay: 0s !important; caret-color: transparent !important; scroll-behavior: auto !important; }';
+/** Build the ignoreSelectors CSS block (visibility preserves layout). */
+function buildIgnoreCss(selectors) {
+    return selectors.map((s) => `${s} { visibility: hidden !important; }`).join('\n');
+}
+async function injectCaptureCss(driver, css) {
+    try {
+        await driver.executeScript(`var el = document.createElement('style');` +
+            `el.id = arguments[0]; el.textContent = arguments[1];` +
+            `document.head.appendChild(el);`, STYLE_ID, css);
+        return true;
+    }
+    catch {
+        return false; // locked-down page; capture proceeds without stabilization
+    }
+}
+async function removeCaptureCss(driver) {
+    try {
+        await driver.executeScript(`var el = document.getElementById(arguments[0]); if (el) el.remove();`, STYLE_ID);
+    }
+    catch {
+        // best-effort cleanup
+    }
+}
+/**
+ * Wait (bounded at 10s) for web fonts to finish loading so the capture
+ * never shows a fallback font — a fallback-font capture diffs 30%+.
+ */
+async function waitForFonts(driver) {
+    const deadline = Date.now() + 10000;
+    for (;;) {
+        try {
+            const ready = await driver.executeScript(`return document.fonts ? document.fonts.status !== 'loading' : true;`);
+            if (ready || Date.now() >= deadline)
+                return;
+        }
+        catch {
+            return; // no FontFaceSet or executeScript failed — proceed
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+}
+/**
+ * Full-page screenshot where the driver supports it, viewport otherwise.
+ * Returns a PNG Buffer.
+ */
+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).
+    if (typeof driver.sendAndGetDevToolsCommand === 'function') {
+        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');
+            }
+        }
+        catch {
+            // fall through to the viewport screenshot
+        }
+    }
+    const base64 = await driver.takeScreenshot();
+    if (typeof base64 !== 'string' || base64.length === 0) {
+        throw new Error('testivai.witness: driver.takeScreenshot() returned an empty value');
+    }
+    return Buffer.from(base64, 'base64');
+}
+/**
+ * Capture a screenshot + DOM and write them as a temp snapshot.
+ *
+ * @param driver  selenium-webdriver WebDriver (must expose
+ *   `takeScreenshot()` and `executeScript()`).
+ * @param name    Snapshot name. Becomes the directory under
+ *   `.testivai/temp/<name>/` and the key in the rendered report.
+ * @param options Per-call overrides.
+ */
+async function witness(driver, name, options = {}) {
+    if (!name || typeof name !== 'string') {
+        throw new Error('testivai.witness: snapshot name is required and must be a non-empty string');
+    }
+    if (!driver || typeof driver.takeScreenshot !== 'function') {
+        throw new Error('testivai.witness: driver argument must expose takeScreenshot()');
+    }
+    // Multi-browser runs: fold the variant into the name so sessions don't
+    // overwrite each other's baselines (same mechanism as the Playwright
+    // adapter's multi-project handling).
+    if (options.variant) {
+        name = `${name}__${options.variant.replace(/[^a-z0-9_-]+/gi, '_').toLowerCase()}`;
+    }
+    // 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 ?? [])]),
+    ];
+    const cssParts = [];
+    if (stabilize)
+        cssParts.push(STABILIZE_CSS);
+    if (ignoreSelectors.length > 0)
+        cssParts.push(buildIgnoreCss(ignoreSelectors));
+    let injected = false;
+    if (cssParts.length > 0 && typeof driver.executeScript === 'function') {
+        injected = await injectCaptureCss(driver, cssParts.join('\n'));
+        if (stabilize)
+            await waitForFonts(driver);
+    }
+    // 1. Capture screenshot (full-page on Chromium, viewport elsewhere)
+    let screenshot;
+    try {
+        screenshot = await captureScreenshot(driver);
+    }
+    finally {
+        if (injected)
+            await removeCaptureCss(driver);
+    }
+    // 2. Capture DOM (best-effort — never break the screenshot path)
+    let dom;
+    if (!options.skipDom && typeof driver.executeScript === 'function') {
+        try {
+            const result = await driver.executeScript(
+            // ignoreSelectors excludes elements from the pixel diff, so they
+            // are excluded from the DOM/text signal too (consistent semantic).
+            `var clone = document.documentElement.cloneNode(true);` +
+                `var sels = arguments[0] || [];` +
+                `for (var i = 0; i < sels.length; i++) {` +
+                ` try { clone.querySelectorAll(sels[i]).forEach(function(el){ el.remove(); }); } catch (e) {}` +
+                `}` +
+                `return clone.outerHTML;`, ignoreSelectors);
+            if (typeof result === 'string' && result.length > 0) {
+                dom = result;
+            }
+        }
+        catch {
+            // Suppressed by design. DOM capture failure means the noise hint
+            // is unavailable for this snapshot; pixel diff still works.
+        }
+    }
+    // 3. Write to .testivai/temp/<name>/
+    const store = new witness_1.BaselineStore(process.cwd());
+    store.writeTemp(name, screenshot, dom);
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@testivai/witness-selenium",
+  "version": "0.1.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",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "selenium",
+    "selenium-webdriver",
+    "visual-regression",
+    "testing",
+    "screenshot-testing",
+    "testivai"
+  ],
+  "author": "TestivAI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcbuddy/testivai-oss.git",
+    "directory": "packages/selenium"
+  },
+  "bugs": {
+    "url": "https://github.com/mcbuddy/testivai-oss/issues"
+  },
+  "homepage": "https://github.com/mcbuddy/testivai-oss/tree/main/packages/selenium#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "selenium-webdriver": ">=4.6.0"
+  },
+  "peerDependenciesMeta": {
+    "selenium-webdriver": {
+      "optional": false
+    }
+  },
+  "dependencies": {
+    "@testivai/witness": "1.3.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "test:unit": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  }
+}