vitest-screenshot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Houston
+
+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,32 @@
+# vitest-screenshot
+
+`expect(image).toMatchScreenshot(name)`: pixel-diff an RGBA image against a PNG baseline committed
+next to your tests. Backend-agnostic: feed it `canvas.getImageData()` from
+[`vitest-environment-webgl-node`](../vitest-environment-webgl-node), a WebGPU texture readback, or
+pixels from a real browser.
+
+## Install
+
+```sh
+pnpm add -D vitest vitest-screenshot
+```
+
+## Usage
+
+```ts
+import { extendMatchers } from 'vitest-screenshot';
+extendMatchers();
+
+it('renders the knot', () => {
+  renderer.render(scene, camera);
+  expect(canvas.getImageData()).toMatchScreenshot('knot', { maxDiffRatio: 0.01 });
+});
+```
+
+- Baselines live in `__screenshots__/<name>.png` beside the test file (override with `baselineDir`).
+- A missing baseline is written on first run, except when `CI` is set, where it fails.
+- `UPDATE_SCREENSHOTS=1 vitest` (or `update: true`) rewrites baselines.
+- On failure `<name>.actual.png` and `<name>.diff.png` are written beside the baseline. Gitignore them.
+- `threshold` is pixelmatch's per-pixel colour tolerance (default 0.1); `maxDiffRatio` is the fraction
+  of pixels allowed to differ (default 0.001). GPUs and drivers rasterize slightly differently, so loosen
+  `maxDiffRatio` for baselines shared across platforms.

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/** Anything with RGBA8 pixels, top row first: `ImageData`, node-webgl's `canvas.getImageData()`, or a WebGPU readback. */
+export type RgbaImage = {
+    width: number;
+    height: number;
+    data: Uint8Array | Uint8ClampedArray;
+};
+export type ScreenshotOptions = {
+    /** Directory holding baseline PNGs. Default: `__screenshots__` beside the test file. */
+    baselineDir?: string;
+    /** Per-pixel colour distance (0..1) tolerated by pixelmatch. Default 0.1. */
+    threshold?: number;
+    /** Fraction (0..1) of pixels allowed to differ. Default 0.001. */
+    maxDiffRatio?: number;
+    /** Overwrite the baseline. Default: `UPDATE_SCREENSHOTS` env var is set. */
+    update?: boolean;
+};
+declare module 'vitest' {
+    interface Assertion {
+        toMatchScreenshot(name: string, options?: ScreenshotOptions): void;
+    }
+}
+export declare function extendMatchers(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,0HAA0H;AAC1H,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAEhG,MAAM,MAAM,iBAAiB,GAAG;IAC9B,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,OAAO,QAAQ,QAAQ,CAAC;IACtB,UAAU,SAAS;QACjB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;KACpE;CACF;AAUD,wBAAgB,cAAc,IAAI,IAAI,CAoCrC"}

package/dist/index.js

@@ -0,0 +1,44 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+import { expect } from 'vitest';
+const result = (pass, message) => ({ pass, message: () => message });
+const toPng = ({ width, height, data }) => {
+    const png = new PNG({ width, height });
+    png.data = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    return png;
+};
+export function extendMatchers() {
+    expect.extend({
+        toMatchScreenshot(received, name, options = {}) {
+            const dir = options.baselineDir ?? join(dirname(this.testPath ?? ''), '__screenshots__');
+            const file = join(dir, `${name}.png`);
+            const actual = toPng(received);
+            const update = options.update ?? Boolean(process.env.UPDATE_SCREENSHOTS);
+            if (update || (!existsSync(file) && !process.env.CI)) {
+                mkdirSync(dir, { recursive: true });
+                writeFileSync(file, PNG.sync.write(actual));
+                return result(true, `wrote baseline ${file}`);
+            }
+            if (!existsSync(file))
+                return result(false, `missing baseline ${file}; run with UPDATE_SCREENSHOTS=1`);
+            const baseline = PNG.sync.read(readFileSync(file));
+            if (baseline.width !== actual.width || baseline.height !== actual.height) {
+                return result(false, `size mismatch: baseline ${baseline.width}x${baseline.height}, actual ${actual.width}x${actual.height}`);
+            }
+            const diff = new PNG({ width: actual.width, height: actual.height });
+            const count = pixelmatch(baseline.data, actual.data, diff.data, actual.width, actual.height, {
+                threshold: options.threshold ?? 0.1,
+            });
+            const ratio = count / (actual.width * actual.height);
+            const pass = ratio <= (options.maxDiffRatio ?? 0.001);
+            if (!pass) {
+                writeFileSync(join(dir, `${name}.actual.png`), PNG.sync.write(actual));
+                writeFileSync(join(dir, `${name}.diff.png`), PNG.sync.write(diff));
+            }
+            return result(pass, `${basename(file)}: ${count} pixels (${(ratio * 100).toFixed(3)}%) differ; see ${name}.diff.png`);
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "vitest-screenshot",
+  "version": "0.1.0",
+  "description": "toMatchScreenshot(): pixel-diff an RGBA image against a committed PNG baseline in Vitest",
+  "keywords": [
+    "matcher",
+    "pixelmatch",
+    "screenshot",
+    "visual-regression",
+    "vitest",
+    "webgl",
+    "webgpu"
+  ],
+  "homepage": "https://github.com/bhouston/vitest-gpu#readme",
+  "bugs": {
+    "url": "https://github.com/bhouston/vitest-gpu/issues"
+  },
+  "license": "MIT",
+  "author": "Ben Houston <ben@ben3d.ca> (https://ben3d.ca)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bhouston/vitest-gpu.git",
+    "directory": "packages/vitest-screenshot"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "tsc": "tsc -b"
+  },
+  "dependencies": {
+    "pixelmatch": "^7.1.0",
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/pngjs": "^6.0.5"
+  },
+  "peerDependencies": {
+    "vitest": ">=3 <5"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}