@testivai/witness-webdriverio 0.1.1

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,142 @@
+# @testivai/witness-webdriverio
+
+WebdriverIO adapter for [TestivAI Witness](https://github.com/mcbuddy/testivai-oss) — local-first visual regression testing with pixel + DOM comparison. No account required.
+
+Pairs with `@testivai/witness` (the local CLI + diff engine + HTML report) and shares the `.testivai/baselines/` layout used by `@testivai/witness-playwright`. Switching between Playwright and WebdriverIO produces the same baselines, the same report, and the same approval workflow.
+
+## Why an adapter and not the `testivai run` sidecar?
+
+The framework-agnostic `testivai run` mode launches your test process and attaches to Chrome via CDP. That works but is brittle: framework-specific Chrome launch flags, target selection across iframes, signal handling. This adapter sidesteps all of that by using WebdriverIO's native `browser.takeScreenshot()` + `browser.execute()`. No port polling, no race conditions.
+
+## Install
+
+```bash
+npm install -D @testivai/witness @testivai/witness-webdriverio
+```
+
+`webdriverio@>=8` is a peer dependency (you should already have it).
+
+## Quick start
+
+### 1. Tell TestivAI to run in local mode
+
+Create `.testivai/config.json` at your project root:
+
+```json
+{
+  "mode": "local",
+  "threshold": 0.1,
+  "reportDir": "visual-report",
+  "autoOpen": false
+}
+```
+
+This file is the local-mode marker. Without it, the adapter logs a warning and skips report generation (cloud mode upload is not yet implemented for WDIO).
+
+### 2. Register the service in `wdio.conf.ts`
+
+```ts
+import { TestivaiService } from '@testivai/witness-webdriverio/service';
+
+export const config = {
+  // ...
+  services: [
+    [TestivaiService, { quiet: false }],
+  ],
+};
+```
+
+The service runs after all tests complete. It reads `.testivai/temp/` (where `witness()` wrote captures), diffs against `.testivai/baselines/`, and produces `visual-report/` with `index.html` + `results.json`.
+
+### 3. Capture inside your tests
+
+```ts
+import { testivai } from '@testivai/witness-webdriverio';
+
+describe('Homepage', () => {
+  it('looks correct', async () => {
+    await browser.url('https://example.com');
+    await testivai.witness(browser, 'homepage');
+  });
+
+  it('checkout flow first step', async () => {
+    await browser.url('https://example.com/checkout');
+    await testivai.witness(browser, 'checkout-step-1');
+  });
+});
+```
+
+### 4. Run
+
+```bash
+npx wdio run wdio.conf.ts
+```
+
+- **First run**: baselines are written to `.testivai/baselines/<name>/`. Commit them with `git add .testivai/baselines`.
+- **Later runs**: screenshots are diffed and a self-contained HTML report is written to `./visual-report/`.
+
+## Approving changes
+
+When the report shows changed snapshots:
+
+```bash
+# Review them in visual-report/index.html
+open visual-report/index.html
+
+# Approve a single snapshot
+npx testivai approve "homepage"
+
+# Approve everything that changed
+npx testivai approve --all
+```
+
+Approve writes the temp capture over the baseline and backs the previous baseline up to `.testivai/baselines/<name>/.previous/`. `npx testivai approve --undo "homepage"` reverts.
+
+## DOM noise hint
+
+When pixels differ but the page DOM is structurally identical, the report flags the change as "likely render noise" (anti-aliasing, font hinting, sub-pixel layout). When the DOM is also different, the report shows added / removed / attribute-change counts so you can decide whether the change is intentional. Same signal as the Playwright adapter — both write `dom.html` alongside the screenshot.
+
+DOM capture happens automatically. To skip it for a single snapshot:
+
+```ts
+await testivai.witness(browser, 'no-dom', { skipDom: true });
+```
+
+## API
+
+### `testivai.witness(browser, name, options?)`
+
+Captures a screenshot + DOM and writes them as a temp snapshot.
+
+| Param | Type | Description |
+|---|---|---|
+| `browser` | WebdriverIO browser | Must expose `takeScreenshot()` and (for DOM) `execute()`. |
+| `name` | string | Snapshot name. Becomes `.testivai/temp/<name>/` and the key in the report. |
+| `options.skipDom` | boolean | Skip DOM capture for this snapshot. |
+
+### `TestivaiService`
+
+Class registered as a WDIO service. Implements `onComplete`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `projectRoot` | string | `process.cwd()` | Project root for the test run. |
+| `reportDir` | string | local config (`visual-report`) | Override the report directory. |
+| `threshold` | number | local config (`0.1`) | Diff threshold (0–1). |
+| `autoOpen` | boolean | `false` | Auto-open the report in a browser. |
+| `quiet` | boolean | `false` | Suppress all logging except errors. |
+
+## Status
+
+- **Local mode**: stable
+- **Cloud mode** (upload to TestivAI hosted): not yet implemented in this adapter — coming in a later iteration. The Playwright adapter has both lanes today; the WDIO adapter will follow once local is broadly used.
+
+## Links
+
+- Repo: https://github.com/mcbuddy/testivai-oss
+- Plan: see `docs/OSS_PLAN_V3.md` in `mcbuddy/testivai-monorepo`
+- Issues: https://github.com/mcbuddy/testivai-oss/issues
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @testivai/witness-webdriverio
+ *
+ * WebdriverIO adapter for the TestivAI Witness OSS toolkit. Pairs with
+ * `@testivai/witness` (the local CLI + diff engine) and shares the same
+ * `.testivai/baselines/` layout as `@testivai/witness-playwright`.
+ *
+ *   import { testivai } from '@testivai/witness-webdriverio';
+ *   import { TestivaiService } from '@testivai/witness-webdriverio/service';
+ */
+import { witness } from './witness';
+export { witness } from './witness';
+export { TestivaiService, default as DefaultTestivaiService } from './service';
+export type { WitnessBrowser, WitnessOptions, TestivaiServiceOptions } from './types';
+/**
+ * Convenience namespace mirroring @testivai/witness-playwright's API:
+ *
+ *   await testivai.witness(browser, 'homepage');
+ */
+export declare const testivai: {
+    witness: typeof witness;
+};
+export declare const VERSION: string;

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * @testivai/witness-webdriverio
+ *
+ * WebdriverIO adapter for the TestivAI Witness OSS toolkit. Pairs with
+ * `@testivai/witness` (the local CLI + diff engine) and shares the same
+ * `.testivai/baselines/` layout as `@testivai/witness-playwright`.
+ *
+ *   import { testivai } from '@testivai/witness-webdriverio';
+ *   import { TestivaiService } from '@testivai/witness-webdriverio/service';
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.testivai = exports.DefaultTestivaiService = exports.TestivaiService = 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; } });
+var service_1 = require("./service");
+Object.defineProperty(exports, "TestivaiService", { enumerable: true, get: function () { return service_1.TestivaiService; } });
+Object.defineProperty(exports, "DefaultTestivaiService", { enumerable: true, get: function () { return __importDefault(service_1).default; } });
+/**
+ * Convenience namespace mirroring @testivai/witness-playwright's API:
+ *
+ *   await testivai.witness(browser, 'homepage');
+ */
+exports.testivai = {
+    witness: witness_1.witness,
+};
+exports.VERSION = require('../package.json').version;

package/dist/service.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @testivai/witness-webdriverio — WDIO service
+ *
+ * Registered in wdio.conf.ts so the report is generated automatically
+ * after the test suite finishes:
+ *
+ *   import { TestivaiService } from '@testivai/witness-webdriverio/service';
+ *
+ *   export const config = {
+ *     services: [[TestivaiService, { quiet: false }]],
+ *     // ...
+ *   };
+ *
+ * The service does ONE thing in `onComplete`: detect local mode, then
+ * call `generateReport()` from @testivai/witness/report. There is no
+ * cloud upload path in this iteration — the OSS goal is standalone-
+ * complete local mode. If a future cloud upload is added, it slots in
+ * here without changing the witness() capture function.
+ */
+import type { TestivaiServiceOptions } from './types';
+export declare class TestivaiService {
+    private readonly options;
+    constructor(serviceOptions?: TestivaiServiceOptions);
+    /**
+     * WebdriverIO calls onComplete after all worker processes finish.
+     * Signature is intentionally loose — we only consume the parts we need
+     * and remain forward-compatible with WDIO 8 and 9.
+     */
+    onComplete(_exitCode?: number, _config?: unknown, _capabilities?: unknown, _results?: unknown): Promise<void>;
+}
+/**
+ * Default export so consumers can use the WDIO services-by-class form
+ * directly: `services: [TestivaiService]`. The class form is also
+ * compatible with the tuple form for passing options.
+ */
+export default TestivaiService;

package/dist/service.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * @testivai/witness-webdriverio — WDIO service
+ *
+ * Registered in wdio.conf.ts so the report is generated automatically
+ * after the test suite finishes:
+ *
+ *   import { TestivaiService } from '@testivai/witness-webdriverio/service';
+ *
+ *   export const config = {
+ *     services: [[TestivaiService, { quiet: false }]],
+ *     // ...
+ *   };
+ *
+ * The service does ONE thing in `onComplete`: detect local mode, then
+ * call `generateReport()` from @testivai/witness/report. There is no
+ * cloud upload path in this iteration — the OSS goal is standalone-
+ * complete local mode. If a future cloud upload is added, it slots in
+ * here without changing the witness() capture function.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestivaiService = void 0;
+const witness_1 = require("@testivai/witness");
+class TestivaiService {
+    constructor(serviceOptions = {}) {
+        this.options = serviceOptions;
+    }
+    /**
+     * WebdriverIO calls onComplete after all worker processes finish.
+     * Signature is intentionally loose — we only consume the parts we need
+     * and remain forward-compatible with WDIO 8 and 9.
+     */
+    async onComplete(_exitCode, _config, _capabilities, _results) {
+        const projectRoot = this.options.projectRoot ?? process.cwd();
+        const log = (msg) => {
+            if (!this.options.quiet) {
+                // eslint-disable-next-line no-console
+                console.log(`[testivai] ${msg}`);
+            }
+        };
+        if (!(0, witness_1.isLocalMode)(projectRoot)) {
+            log('Cloud mode is not yet supported by @testivai/witness-webdriverio — skipping report generation. ' +
+                'To enable local mode, create .testivai/config.json with {"mode":"local"}.');
+            return;
+        }
+        try {
+            const reportData = (0, witness_1.generateReport)({
+                projectRoot,
+                reportDir: this.options.reportDir,
+                threshold: this.options.threshold,
+                autoOpen: this.options.autoOpen ?? false,
+            });
+            const { summary } = reportData;
+            log(`Visual report: total=${summary.total} passed=${summary.passed} ` +
+                `changed=${summary.changed} new=${summary.newSnapshots}`);
+            if (summary.changed > 0 || summary.newSnapshots > 0) {
+                log('To approve: npx testivai approve --all');
+            }
+        }
+        catch (err) {
+            // Reporting failure must not crash the WDIO run after all tests
+            // already passed. Log and exit cleanly.
+            // eslint-disable-next-line no-console
+            console.error('[testivai] Failed to generate visual report:', err);
+        }
+    }
+}
+exports.TestivaiService = TestivaiService;
+/**
+ * Default export so consumers can use the WDIO services-by-class form
+ * directly: `services: [TestivaiService]`. The class form is also
+ * compatible with the tuple form for passing options.
+ */
+exports.default = TestivaiService;

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Public types for @testivai/witness-webdriverio.
+ */
+/**
+ * Minimal subset of the WebdriverIO `browser` object the witness function
+ * relies on. Defining a structural type here means consumers can pass any
+ * WDIO-shaped object (sync or async, real or mocked) without us pulling
+ * `webdriverio`'s heavy global type into our public surface.
+ */
+export interface WitnessBrowser {
+    /**
+     * Capture a full-page screenshot of the active session. Returns a base64
+     * PNG, matching the WebdriverIO `browser.takeScreenshot()` return shape.
+     */
+    takeScreenshot(): Promise<string>;
+    /**
+     * Execute a script in the page context. We only use the no-arg form.
+     * Type kept loose to accept WDIO 8/9 signature variants.
+     */
+    execute<T = unknown>(script: string | ((...args: any[]) => T), ...args: any[]): 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;
+}
+/**
+ * Configuration passed to the WDIO service.
+ *
+ * Local mode is detected automatically from `.testivai/config.json` —
+ * these options exist only to override the defaults that
+ * generateReport() picks up from that file.
+ */
+export interface TestivaiServiceOptions {
+    /** Project root for the test run. Defaults to `process.cwd()`. */
+    projectRoot?: string;
+    /** Override the report directory. Defaults to local config (`visual-report`). */
+    reportDir?: string;
+    /** Override the diff threshold (0–1). Defaults to local config (0.1). */
+    threshold?: number;
+    /** Auto-open the rendered report in a browser. Defaults to local config. */
+    autoOpen?: boolean;
+    /** Suppress all adapter logging except errors. */
+    quiet?: boolean;
+}

package/dist/types.js

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

package/dist/witness.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @testivai/witness-webdriverio — capture function
+ *
+ * The user-facing call inside a WebdriverIO test:
+ *
+ *   import { testivai } from '@testivai/witness-webdriverio';
+ *   await testivai.witness(browser, 'homepage');
+ *
+ * Captures a full-page screenshot via `browser.takeScreenshot()` and the
+ * page DOM via `browser.execute(() => document.documentElement.outerHTML)`,
+ * then writes both into `.testivai/temp/<name>/` using the same
+ * BaselineStore layout as @testivai/witness-playwright. The TestivaiService
+ * (registered in wdio.conf.ts) runs `compareAll` + `generateReport` after
+ * all tests finish.
+ *
+ * Architectural choice: we rely on WebdriverIO's native `takeScreenshot`
+ * and `execute` APIs rather than opening a CDP session. This is the whole
+ * point of the per-framework adapter — using the framework's stable public
+ * API instead of fighting Chrome-launch coordination.
+ */
+import type { WitnessBrowser, WitnessOptions } from './types';
+/**
+ * Capture a screenshot + DOM and write them as a temp snapshot.
+ *
+ * @param browser WebdriverIO browser-like object (must expose
+ *   `takeScreenshot()` and `execute()`).
+ * @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(browser: WitnessBrowser, name: string, options?: WitnessOptions): Promise<void>;

package/dist/witness.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * @testivai/witness-webdriverio — capture function
+ *
+ * The user-facing call inside a WebdriverIO test:
+ *
+ *   import { testivai } from '@testivai/witness-webdriverio';
+ *   await testivai.witness(browser, 'homepage');
+ *
+ * Captures a full-page screenshot via `browser.takeScreenshot()` and the
+ * page DOM via `browser.execute(() => document.documentElement.outerHTML)`,
+ * then writes both into `.testivai/temp/<name>/` using the same
+ * BaselineStore layout as @testivai/witness-playwright. The TestivaiService
+ * (registered in wdio.conf.ts) runs `compareAll` + `generateReport` after
+ * all tests finish.
+ *
+ * Architectural choice: we rely on WebdriverIO's native `takeScreenshot`
+ * and `execute` APIs rather than opening a CDP session. This is the whole
+ * point of the per-framework adapter — using the framework's stable public
+ * API instead of fighting Chrome-launch coordination.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.witness = witness;
+const witness_1 = require("@testivai/witness");
+/**
+ * Capture a screenshot + DOM and write them as a temp snapshot.
+ *
+ * @param browser WebdriverIO browser-like object (must expose
+ *   `takeScreenshot()` and `execute()`).
+ * @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(browser, name, options = {}) {
+    if (!name || typeof name !== 'string') {
+        throw new Error('testivai.witness: snapshot name is required and must be a non-empty string');
+    }
+    if (!browser || typeof browser.takeScreenshot !== 'function') {
+        throw new Error('testivai.witness: browser argument must expose takeScreenshot()');
+    }
+    // 1. Capture screenshot (base64 PNG → Buffer)
+    const base64 = await browser.takeScreenshot();
+    if (typeof base64 !== 'string' || base64.length === 0) {
+        throw new Error(`testivai.witness("${name}"): browser.takeScreenshot() returned an empty value`);
+    }
+    const screenshot = Buffer.from(base64, 'base64');
+    // 2. Capture DOM (best-effort — never break the screenshot path)
+    let dom;
+    if (!options.skipDom && typeof browser.execute === 'function') {
+        try {
+            const result = await browser.execute(
+            // Inline string form for maximum WDIO sync/async compatibility.
+            // The function-form across WDIO 8/9 has subtle typing differences;
+            // the string form is stable.
+            'return document.documentElement.outerHTML;');
+            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,75 @@
+{
+  "name": "@testivai/witness-webdriverio",
+  "version": "0.1.1",
+  "description": "WebdriverIO 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"
+    },
+    "./service": {
+      "types": "./dist/service.d.ts",
+      "default": "./dist/service.js"
+    }
+  },
+  "keywords": [
+    "webdriverio",
+    "wdio",
+    "wdio-service",
+    "visual-regression",
+    "testing",
+    "testivai"
+  ],
+  "author": "TestivAI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcbuddy/testivai-oss.git",
+    "directory": "packages/webdriverio"
+  },
+  "bugs": {
+    "url": "https://github.com/mcbuddy/testivai-oss/issues"
+  },
+  "homepage": "https://github.com/mcbuddy/testivai-oss/tree/main/packages/webdriverio#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "webdriverio": ">=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "webdriverio": {
+      "optional": false
+    }
+  },
+  "dependencies": {
+    "@testivai/witness": "1.0.3"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.0.0",
+    "webdriverio": "^9.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "test:unit": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  }
+}