@uiverify/vitest 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UI Verify
+
+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,81 @@
+# @uiverify/vitest
+
+Vitest browser-mode capture SDK for [UI Verify](https://uiverify.ai) - visual regression testing for agent-written UI, and an alternative to Chromatic and Percy.
+
+Add one plugin to your Vitest config and every browser-mode test archives its final DOM (the serialized DOM plus the bytes of every resource the page loaded). UI Verify re-renders and pixel-diffs that archive in the cloud, so you get deterministic, cross-browser visual tests from the component tests you already have - no Storybook required.
+
+## Requirements
+
+- Vitest 4 in **browser mode** on the Playwright provider (`@vitest/browser-playwright`) with Chromium.
+
+## Install
+
+```bash
+npm i -D @uiverify/vitest @vitest/browser-playwright
+```
+
+## Configure
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import { playwright } from "@vitest/browser-playwright";
+import { uiverifyPlugin } from "@uiverify/vitest/plugin";
+
+export default defineConfig({
+  plugins: [uiverifyPlugin()],
+  test: {
+    browser: {
+      enabled: true,
+      provider: playwright(),
+      instances: [{ browser: "chromium" }],
+    },
+  },
+});
+```
+
+That is the whole setup. Every browser-mode test now archives its final rendered DOM.
+
+## Capture points
+
+```ts
+import { test } from "vitest";
+import { render } from "vitest-browser-react"; // or your framework's browser render helper
+import { takeSnapshot, disableAutoSnapshot } from "@uiverify/vitest";
+
+test("menu", async () => {
+  render(<Menu />);
+  await takeSnapshot("closed"); // optional named checkpoint
+  // the final state is archived automatically at the end of the test
+});
+```
+
+- `takeSnapshot(name?)` - archive the current DOM as a named checkpoint mid-test.
+- `disableAutoSnapshot()` - opt the current test out of the automatic end-of-test snapshot (or pass `disableAutoSnapshot: true` to `uiverifyPlugin()` to turn it off for every test).
+
+## Upload
+
+Archives are written to `./uiverify-archive` (override with `UIVERIFY_ARCHIVE_DIR` or the plugin's `outDir`). After your run, upload with the [`uiverify`](https://www.npmjs.com/package/uiverify) CLI:
+
+```bash
+npx playwright install --with-deps   # one-time: browsers for Vitest browser mode
+npx vitest run
+UIVERIFY_API_KEY=your_key npx -y uiverify@latest upload --static-dir ./uiverify-archive
+```
+
+## Options
+
+```ts
+uiverifyPlugin({
+  outDir: "./uiverify-archive", // where archives are written
+  disableAutoSnapshot: false,   // capture only via takeSnapshot() when true
+});
+```
+
+## How it works
+
+In Vitest browser mode the test runs inside the page, so the DOM is serialized in the same realm with [`rrweb-snapshot`](https://www.npmjs.com/package/rrweb-snapshot); the resources the page loaded are fetched and base64-encoded; and the assembled archive is written to disk by a Vitest browser command. Nothing runs at runtime beyond your test - the archive is a plain JSON bundle the CLI uploads.
+
+## License
+
+MIT

package/dist/browser-setup.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The setup file `uiverifyPlugin()` injects into every browser-mode test run. It is what turns the bare
+ * plugin install into "each test archives its final DOM": a `beforeEach` marks the current test, and an
+ * `afterEach` takes the automatic snapshot. It carries no per-test boilerplate for the user.
+ */
+declare module "vitest" {
+    interface ProvidedContext {
+        __uiverify: {
+            disableAutoSnapshot: boolean;
+        };
+    }
+}

package/dist/browser-setup.js

@@ -0,0 +1,22 @@
+import {
+  autoSnapshot,
+  beginTest
+} from "./chunk-ZCABESWT.js";
+
+// src/browser-setup.ts
+import { afterEach, beforeEach, inject } from "vitest";
+function globalAutoDisabled() {
+  try {
+    return Boolean(inject("__uiverify")?.disableAutoSnapshot);
+  } catch {
+    return false;
+  }
+}
+beforeEach((ctx) => {
+  beginTest(ctx.task);
+});
+afterEach(async (ctx) => {
+  if (globalAutoDisabled()) return;
+  const passed = ctx.task.result?.state !== "fail";
+  await autoSnapshot(passed);
+});

package/dist/chunk-ZCABESWT.js

@@ -0,0 +1,127 @@
+// src/capture.ts
+import { commands } from "@vitest/browser/context";
+import { snapshot } from "rrweb-snapshot";
+
+// src/snapshot-id.ts
+function snapshotIdParts(task) {
+  const file = task.file;
+  const suites = [];
+  let cur = task.suite;
+  while (cur && cur !== file) {
+    if (cur.name) suites.unshift(cur.name);
+    cur = cur.suite;
+  }
+  const parts = [];
+  if (file?.name) parts.push(file.name);
+  parts.push(...suites, task.name);
+  return parts;
+}
+function snapshotIds(task, name) {
+  const parts = snapshotIdParts(task);
+  const idBase = parts.join(" > ");
+  const title = parts.length > 1 ? parts.slice(0, -1).join(" > ") : parts[0] ?? "";
+  return { id: name ? `${idBase}::${name}` : idBase, title };
+}
+
+// src/capture.ts
+var MAX_RESOURCE_BYTES = 10 * 1024 * 1024;
+function isArchivableContentType(contentType) {
+  if (!contentType) return false;
+  const ct = contentType.toLowerCase();
+  return ct.startsWith("image/") || ct.startsWith("font/") || ct.startsWith("audio/") || ct.startsWith("video/") || ct.startsWith("text/css") || ct.startsWith("application/font") || ct.startsWith("application/x-font") || ct.startsWith("application/vnd.ms-fontobject");
+}
+function isModuleOrData(url) {
+  if (/^(data|blob):/.test(url)) return true;
+  const path = url.split("?")[0];
+  if (/\.(m?js|cjs|ts|tsx|jsx|json|map|html)$/i.test(path)) return true;
+  return /\/(@vite|@id|@fs)\//.test(url) || url.includes("/node_modules/.vite/");
+}
+function toBase64(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  const chunk = 32768;
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+  }
+  return btoa(binary);
+}
+async function collectResources() {
+  const urls = /* @__PURE__ */ new Set();
+  for (const entry of performance.getEntriesByType("resource")) {
+    if (/^https?:/.test(entry.name) && !isModuleOrData(entry.name)) urls.add(entry.name);
+  }
+  const out = {};
+  await Promise.all(
+    [...urls].map(async (url) => {
+      try {
+        const resp = await fetch(url);
+        const contentType = resp.headers.get("content-type");
+        if (!isArchivableContentType(contentType)) return;
+        const buffer = await resp.arrayBuffer();
+        if (buffer.byteLength > MAX_RESOURCE_BYTES) return;
+        out[url] = { contentType, status: resp.status, body: toBase64(buffer) };
+      } catch {
+      }
+    })
+  );
+  return out;
+}
+async function capture(task, name) {
+  const { id, title } = snapshotIds(task, name);
+  const serialize = (recordCanvas) => snapshot(document, { inlineStylesheet: true, recordCanvas, slimDOM: { script: true } });
+  let dom;
+  try {
+    dom = serialize(true);
+  } catch {
+    dom = serialize(false);
+  }
+  if (!dom) throw new Error(`@uiverify/vitest: rrweb failed to serialize the DOM for "${id}"`);
+  const resources = await collectResources();
+  const deviceScaleFactor = window.devicePixelRatio || void 0;
+  const colorScheme = matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  const archived = {
+    id,
+    title,
+    name,
+    viewport: { width: window.innerWidth, height: window.innerHeight },
+    ...deviceScaleFactor ? { deviceScaleFactor } : {},
+    colorScheme,
+    dom,
+    resources
+  };
+  await commands.__uiverifyWriteSnapshot(archived);
+  return id;
+}
+
+// src/runtime.ts
+var currentTask = null;
+var manualCount = 0;
+var autoDisabledForTest = false;
+function beginTest(task) {
+  currentTask = task;
+  manualCount = 0;
+  autoDisabledForTest = false;
+}
+async function takeSnapshot(name = "") {
+  if (!currentTask) {
+    throw new Error(
+      "@uiverify/vitest: takeSnapshot() was called outside a test. Add uiverifyPlugin() to your vitest.config so the setup hooks run."
+    );
+  }
+  manualCount++;
+  return capture(currentTask, name);
+}
+function disableAutoSnapshot() {
+  autoDisabledForTest = true;
+}
+async function autoSnapshot(passed) {
+  if (!currentTask || autoDisabledForTest || manualCount > 0 || !passed) return;
+  await capture(currentTask, "");
+}
+
+export {
+  beginTest,
+  takeSnapshot,
+  disableAutoSnapshot,
+  autoSnapshot
+};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { U as UiverifyPluginOptions } from './options-BJ_jO0NW.js';
+
+/** Archive the page's current DOM as a named snapshot mid-test. Counts as a manual snapshot, so the
+ *  automatic end-of-test snapshot is suppressed (the test is capturing deliberately). */
+declare function takeSnapshot(name?: string): Promise<string>;
+/** Turn off the automatic end-of-test snapshot for the current test only. */
+declare function disableAutoSnapshot(): void;
+
+export { disableAutoSnapshot, takeSnapshot };

package/dist/index.js

@@ -0,0 +1,8 @@
+import {
+  disableAutoSnapshot,
+  takeSnapshot
+} from "./chunk-ZCABESWT.js";
+export {
+  disableAutoSnapshot,
+  takeSnapshot
+};

package/dist/options-BJ_jO0NW.d.ts

@@ -0,0 +1,11 @@
+/** Options for {@link uiverifyPlugin}. */
+interface UiverifyPluginOptions {
+    /** Directory archives are written to. Defaults to `UIVERIFY_ARCHIVE_DIR` or `./uiverify-archive` - the
+     *  same directory the `uiverify` CLI uploads, so no extra wiring is needed. */
+    outDir?: string;
+    /** Turn off the automatic end-of-test snapshot for every test, so capture happens only where you call
+     *  `takeSnapshot()`. Off by default (every browser-mode test archives its final DOM). */
+    disableAutoSnapshot?: boolean;
+}
+
+export type { UiverifyPluginOptions as U };

package/dist/plugin.d.ts

@@ -0,0 +1,24 @@
+import { Plugin } from 'vitest/config';
+import { U as UiverifyPluginOptions } from './options-BJ_jO0NW.js';
+
+/**
+ * `uiverifyPlugin()` — the Node side of @uiverify/vitest. Added to `plugins` in a Vitest config, it wires
+ * capture into a browser-mode run with no per-test code:
+ *
+ *  - injects the setup file that auto-snapshots each test (`browser-setup`),
+ *  - registers the `__uiverifyWriteSnapshot` browser command that writes each snapshot to disk (the
+ *    browser has no filesystem, so the in-page capture hands the assembled snapshot to this Node command),
+ *  - passes the global `disableAutoSnapshot` option through to the setup file via provide/inject.
+ *
+ * The archive lands in the same `./uiverify-archive` directory the `uiverify` CLI uploads.
+ */
+declare module "vitest" {
+    interface ProvidedContext {
+        __uiverify: {
+            disableAutoSnapshot: boolean;
+        };
+    }
+}
+declare function uiverifyPlugin(options?: UiverifyPluginOptions): Plugin;
+
+export { uiverifyPlugin };

package/dist/plugin.js

@@ -0,0 +1,54 @@
+// ../archive-core/src/snapshot-file.ts
+import { createHash } from "crypto";
+function snapshotFileName(id) {
+  const slug = id.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+  const hash = createHash("sha1").update(id).digest("hex").slice(0, 10);
+  return `${slug || "snapshot"}-${hash}.json`;
+}
+
+// ../archive-core/src/out-dir.ts
+import path from "path";
+function resolveOutDir() {
+  return process.env.UIVERIFY_ARCHIVE_DIR ?? path.resolve(process.cwd(), "uiverify-archive");
+}
+
+// ../archive-core/src/write.ts
+import fs from "fs";
+import path2 from "path";
+function writeSnapshot(outDir, snapshot) {
+  const dir = path2.join(outDir, "snapshots");
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path2.join(dir, snapshotFileName(snapshot.id));
+  fs.writeFileSync(file, JSON.stringify(snapshot));
+  return file;
+}
+
+// ../archive-core/src/finalize.ts
+import fs2 from "fs";
+import path3 from "path";
+
+// src/plugin.ts
+var SETUP_MODULE = "@uiverify/vitest/browser-setup";
+function uiverifyPlugin(options = {}) {
+  const outDir = options.outDir ?? resolveOutDir();
+  const config = {
+    test: {
+      setupFiles: [SETUP_MODULE],
+      provide: { __uiverify: { disableAutoSnapshot: options.disableAutoSnapshot ?? false } },
+      browser: {
+        commands: {
+          __uiverifyWriteSnapshot: async (_ctx, snapshot) => {
+            writeSnapshot(outDir, snapshot);
+          }
+        }
+      }
+    }
+  };
+  return {
+    name: "uiverify",
+    config: () => config
+  };
+}
+export {
+  uiverifyPlugin
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@uiverify/vitest",
+  "version": "0.1.0",
+  "description": "Vitest browser-mode capture SDK for UI Verify (uiverify.ai): add uiverifyPlugin() to your Vitest config and each browser-mode test archives its final DOM (serialized DOM + resource bytes) to be replayed + visually diffed by UI Verify. Produces an archive the uiverify CLI uploads; talks to nothing at runtime.",
+  "keywords": [
+    "visual-testing",
+    "visual-regression",
+    "vitest",
+    "vitest-browser",
+    "screenshot-testing",
+    "rrweb",
+    "uiverify"
+  ],
+  "homepage": "https://uiverify.ai",
+  "bugs": "https://github.com/uiverify/uiverify/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uiverify/uiverify.git",
+    "directory": "packages/vitest"
+  },
+  "license": "MIT",
+  "author": "UI Verify",
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./browser-setup": {
+      "types": "./dist/browser-setup.d.ts",
+      "default": "./dist/browser-setup.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@vitest/browser": ">=3.0.0",
+    "vitest": ">=3.0.0"
+  },
+  "dependencies": {
+    "rrweb-snapshot": "^2.1.0"
+  },
+  "devDependencies": {
+    "@rrweb/types": "^2.0.0",
+    "@types/node": "^24.0.0",
+    "@vitest/browser": "^4.1.8",
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "vitest": "^4.1.8",
+    "@uiverify/archive-core": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}