vitest-image-snapshot 0.6.39 → 0.6.40

package/README.md

@@ -169,6 +169,14 @@ interface MatchImageOptions {
 }
 ```
 
+### How Comparison Works
+
+Image comparison uses [pixelmatch](https://github.com/mapbox/pixelmatch), which converts RGB to **YIQ color space** for perceptually-weighted comparison. YIQ separates luminance (Y) from chrominance (I, Q), making the comparison more aligned with human perception than raw RGB byte comparison.
+
+The `threshold` option (0-1) controls sensitivity to color differences in YIQ space.
+
+**Color space note**: Images are compared as raw RGBA bytes. If using `display-p3` (supported in WebGPU via `GPUCanvasConfiguration.colorSpace`), ensure both reference and actual images use the same color space.
+
 ## Examples
 
 ### WebGPU Shaders

package/dist/ImageSnapshotReporter-BdJsioWe.js

@@ -0,0 +1,236 @@
+import { exec } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as http from "node:http";
+
+//#region src/DiffReport.ts
+const templatesDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "templates");
+/** Clear the diff report directory if it exists. */
+async function clearDiffReport(reportDir) {
+	if (fs.existsSync(reportDir)) await fs.promises.rm(reportDir, { recursive: true });
+}
+/** Generate HTML diff report for image snapshot results. */
+async function generateDiffReport(failures, config) {
+	const { autoOpen = false, reportDir, configRoot, liveReload = false } = config;
+	await clearDiffReport(reportDir);
+	await fs.promises.mkdir(reportDir, { recursive: true });
+	const cssSource = path.join(templatesDir, "report.css");
+	await fs.promises.copyFile(cssSource, path.join(reportDir, "report.css"));
+	if (liveReload) {
+		const jsSource = path.join(templatesDir, "live-reload.js");
+		await fs.promises.copyFile(jsSource, path.join(reportDir, "live-reload.js"));
+	}
+	const html = createReportHTML(failures.length > 0 ? await copyImagesToReport(failures, reportDir, configRoot) : [], liveReload);
+	const outputPath = path.join(reportDir, "index.html");
+	await fs.promises.writeFile(outputPath, html, "utf-8");
+	if (failures.length > 0 && !liveReload) console.log(`\n Image diff report: ${outputPath}`);
+	if (autoOpen) exec(`${{
+		darwin: "open",
+		win32: "start"
+	}[process.platform] ?? "xdg-open"} "${outputPath}"`);
+}
+/** Copy images to report dir, preserving directory structure relative to configRoot */
+async function copyImagesToReport(failures, reportDir, configRoot) {
+	return Promise.all(failures.map(async (failure) => {
+		const { paths } = failure;
+		const copiedPaths = {
+			reference: await copyImage(paths.reference, reportDir, configRoot),
+			actual: await copyImage(paths.actual, reportDir, configRoot),
+			diff: await copyImage(paths.diff, reportDir, configRoot)
+		};
+		return {
+			...failure,
+			paths: copiedPaths
+		};
+	}));
+}
+/** Copy single image to report dir, preserving directory structure relative to configRoot */
+async function copyImage(sourcePath, reportDir, configRoot) {
+	if (!fs.existsSync(sourcePath)) return "";
+	const relativePath = path.relative(configRoot, sourcePath);
+	const destPath = path.join(reportDir, relativePath);
+	const destDir = path.dirname(destPath);
+	await fs.promises.mkdir(destDir, { recursive: true });
+	await fs.promises.copyFile(sourcePath, destPath);
+	return relativePath;
+}
+function loadTemplate(name) {
+	return fs.readFileSync(path.join(templatesDir, name), "utf-8");
+}
+/** Replace all {{key}} placeholders in template with values from data object. */
+function renderTemplate(template, data) {
+	let result = template;
+	for (const [key, value] of Object.entries(data)) result = result.replaceAll(`{{${key}}}`, value);
+	const unreplaced = result.match(/\{\{(\w+)\}\}/g);
+	if (unreplaced) {
+		const keys = unreplaced.map((m) => m.slice(2, -2)).join(", ");
+		throw new Error(`Template has unreplaced placeholders: ${keys}`);
+	}
+	return result;
+}
+function createReportHTML(failures, liveReload) {
+	const timestamp = (/* @__PURE__ */ new Date()).toLocaleString();
+	const totalFailures = failures.length;
+	const script = liveReload ? `<script src="live-reload.js"><\/script>` : "";
+	if (totalFailures === 0) return renderTemplate(loadTemplate("report-success.hbs"), {
+		timestamp: escapeHtml(timestamp),
+		script
+	});
+	const rows = failures.map((failure) => createRowHTML(failure)).join("\n");
+	return renderTemplate(loadTemplate("report-failure.hbs"), {
+		totalFailures: String(totalFailures),
+		testPlural: totalFailures === 1 ? "test" : "tests",
+		timestamp: escapeHtml(timestamp),
+		rows,
+		script
+	});
+}
+function createRowHTML(failure) {
+	const { testName, snapshotName, comparison, paths } = failure;
+	const { mismatchedPixels, mismatchedPixelRatio } = comparison;
+	return `
+      <tr>
+        <td class="test-name">
+          <strong>${escapeHtml(testName)}</strong><br>
+          <code>${escapeHtml(snapshotName)}</code>
+        </td>
+        <td class="image-cell">
+          <a href="${paths.reference}" target="_blank">
+            <img src="${paths.reference}" alt="Expected" />
+          </a>
+          <div class="label">Expected</div>
+        </td>
+        <td class="image-cell">
+          <a href="${paths.actual}" target="_blank">
+            <img src="${paths.actual}" alt="Actual" />
+          </a>
+          <div class="label">Actual</div>
+        </td>
+        <td class="image-cell">
+          ${diffCellHTML(paths.diff)}
+        </td>
+        <td class="stats">
+          <div><strong>${mismatchedPixels}</strong> pixels</div>
+          <div><strong>${(mismatchedPixelRatio * 100).toFixed(2)}%</strong></div>
+        </td>
+      </tr>`;
+}
+function escapeHtml(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+}
+function diffCellHTML(diffPath) {
+	if (!diffPath) return `<div class="no-diff">No diff image<br/>(dimension mismatch)</div>`;
+	return `<a href="${diffPath}" target="_blank">
+            <img src="${diffPath}" alt="Diff" />
+          </a>
+          <div class="label">Diff</div>`;
+}
+
+//#endregion
+//#region src/ImageSnapshotReporter.ts
+/** Vitest reporter that generates HTML diff reports for image snapshot failures */
+var ImageSnapshotReporter = class {
+	failuresByFile = /* @__PURE__ */ new Map();
+	vitest;
+	reportPath;
+	autoOpen;
+	port;
+	serverStarted = false;
+	constructor(options = {}) {
+		this.reportPath = options.reportPath;
+		this.autoOpen = options.autoOpen ?? process.env.IMAGE_DIFF_AUTO_OPEN === "true";
+		this.port = options.port ?? 4343;
+	}
+	onInit(vitest) {
+		this.vitest = vitest;
+		if (this.port > 0) this.startServer();
+	}
+	startServer() {
+		const reportDir = this.resolveReportDir();
+		const server = http.createServer((req, res) => {
+			const url = req.url === "/" ? "/index.html" : req.url || "/index.html";
+			const filePath = path.join(reportDir, url);
+			fs.stat(filePath, (statErr, stats) => {
+				if (statErr) {
+					res.writeHead(404);
+					res.end("Not found");
+					return;
+				}
+				const ext = path.extname(filePath);
+				const contentType = ext === ".html" ? "text/html" : ext === ".css" ? "text/css" : ext === ".png" ? "image/png" : "application/octet-stream";
+				const headers = {
+					"Content-Type": contentType,
+					"Last-Modified": stats.mtime.toUTCString()
+				};
+				if (req.method === "HEAD") {
+					res.writeHead(200, headers);
+					res.end();
+					return;
+				}
+				fs.readFile(filePath, (err, data) => {
+					if (err) {
+						res.writeHead(500);
+						res.end("Error reading file");
+						return;
+					}
+					res.writeHead(200, headers);
+					res.end(data);
+				});
+			});
+		});
+		server.listen(this.port, () => {
+			this.serverStarted = true;
+			console.log(`\n Image diff report: http://localhost:${this.port}`);
+		});
+		server.unref();
+	}
+	onTestRunStart(specifications) {
+		for (const spec of specifications) this.failuresByFile.delete(spec.moduleId);
+	}
+	onTestCaseResult(testCase) {
+		const result = testCase.result();
+		if (result?.state !== "failed") return;
+		const meta = testCase.meta();
+		if (!meta.imageSnapshotFailure) return;
+		const error = result.errors?.[0];
+		const failure = captureFailure(testCase, meta.imageSnapshotFailure, error?.message || "");
+		const moduleId = testCase.module.moduleId;
+		const existing = this.failuresByFile.get(moduleId) || [];
+		this.failuresByFile.set(moduleId, [...existing, failure]);
+	}
+	async onTestRunEnd() {
+		await generateDiffReport([...this.failuresByFile.values()].flat(), {
+			autoOpen: this.autoOpen,
+			reportDir: this.resolveReportDir(),
+			configRoot: this.vitest.config.root,
+			liveReload: this.serverStarted
+		});
+	}
+	resolveReportDir() {
+		const configRoot = this.vitest.config.root;
+		if (!this.reportPath) return path.join(configRoot, "__image_diff_report__");
+		return path.isAbsolute(this.reportPath) ? this.reportPath : path.join(configRoot, this.reportPath);
+	}
+};
+function captureFailure(testCase, data, message) {
+	const snapshotName = data.actualPath.match(/([^/]+)\.png$/)?.[1] || "unknown";
+	return {
+		testName: testCase.fullName || testCase.name,
+		snapshotName,
+		comparison: {
+			pass: false,
+			message,
+			mismatchedPixels: data.mismatchedPixels,
+			mismatchedPixelRatio: data.mismatchedPixelRatio
+		},
+		paths: {
+			reference: data.expectedPath,
+			actual: data.actualPath,
+			diff: data.diffPath
+		}
+	};
+}
+
+//#endregion
+export { clearDiffReport as n, generateDiffReport as r, ImageSnapshotReporter as t };

package/dist/{ImageSnapshotReporter-BthcwBqW.d.ts → ImageSnapshotReporter-CRXQpaQz.d.ts}

@@ -1,19 +1,25 @@
-import { Reporter, TestCase, Vitest } from "vitest/node";
+import { Reporter, TestCase, TestSpecification, Vitest } from "vitest/node";
 
 //#region src/ImageSnapshotReporter.d.ts
 interface ImageSnapshotReporterOptions {
   /** Report directory (relative to config.root or absolute) */
   reportPath?: string;
   autoOpen?: boolean;
+  /** Port for live-reload server. Set to 0 to disable. Default: 4343 */
+  port?: number;
 }
 /** Vitest reporter that generates HTML diff reports for image snapshot failures */
 declare class ImageSnapshotReporter implements Reporter {
-  private failures;
+  private failuresByFile;
   private vitest;
   private reportPath?;
   private autoOpen;
+  private port;
+  private serverStarted;
   constructor(options?: ImageSnapshotReporterOptions);
   onInit(vitest: Vitest): void;
+  private startServer;
+  onTestRunStart(specifications: ReadonlyArray<TestSpecification>): void;
   onTestCaseResult(testCase: TestCase): void;
   onTestRunEnd(): Promise<void>;
   private resolveReportDir;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { n as ImageSnapshotReporterOptions, t as ImageSnapshotReporter } from "./ImageSnapshotReporter-BthcwBqW.js";
+import { n as ImageSnapshotReporterOptions, t as ImageSnapshotReporter } from "./ImageSnapshotReporter-CRXQpaQz.js";
 
 //#region src/ImageComparison.d.ts
 /** nodejs compatible interface to DOM ImageData */
@@ -48,8 +48,12 @@ interface DiffReportConfig {
   reportDir: string;
   /** Vitest config root for calculating relative paths when copying images */
   configRoot: string;
+  /** Enable live reload script in HTML. Default: false */
+  liveReload?: boolean;
 }
-/** Generate HTML diff report for all failed image snapshots. */
+/** Clear the diff report directory if it exists. */
+declare function clearDiffReport(reportDir: string): Promise<void>;
+/** Generate HTML diff report for image snapshot results. */
 declare function generateDiffReport(failures: ImageSnapshotFailure[], config: DiffReportConfig): Promise<void>;
 //#endregion
 //#region src/ImageSnapshotMatcher.d.ts
@@ -97,4 +101,4 @@ declare module "vitest" {
   }
 }
 //#endregion
-export { ComparisonOptions, ComparisonResult, DiffReportConfig, ImageData, ImageSnapshotFailure, ImageSnapshotManager, ImageSnapshotReporter, ImageSnapshotReporterOptions, MatchImageOptions, SnapshotConfig, compareImages, generateDiffReport, imageMatcher, pngBuffer };
+export { ComparisonOptions, ComparisonResult, DiffReportConfig, ImageData, ImageSnapshotFailure, ImageSnapshotManager, ImageSnapshotReporter, ImageSnapshotReporterOptions, MatchImageOptions, SnapshotConfig, clearDiffReport, compareImages, generateDiffReport, imageMatcher, pngBuffer };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as generateDiffReport, t as ImageSnapshotReporter } from "./ImageSnapshotReporter-CEBGVm2_.js";
+import { n as clearDiffReport, r as generateDiffReport, t as ImageSnapshotReporter } from "./ImageSnapshotReporter-BdJsioWe.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import pixelmatch from "pixelmatch";
@@ -199,4 +199,4 @@ async function missingSnapshot(manager, actualBuffer, snapshotName) {
 }
 
 //#endregion
-export { ImageSnapshotManager, ImageSnapshotReporter, compareImages, generateDiffReport, imageMatcher, pngBuffer };
+export { ImageSnapshotManager, ImageSnapshotReporter, clearDiffReport, compareImages, generateDiffReport, imageMatcher, pngBuffer };

package/dist/reporter.d.ts

@@ -1,2 +1,2 @@
-import { t as ImageSnapshotReporter } from "./ImageSnapshotReporter-BthcwBqW.js";
+import { t as ImageSnapshotReporter } from "./ImageSnapshotReporter-CRXQpaQz.js";
 export { ImageSnapshotReporter as default };

package/dist/reporter.js

@@ -1,4 +1,4 @@
-import { t as ImageSnapshotReporter } from "./ImageSnapshotReporter-CEBGVm2_.js";
+import { t as ImageSnapshotReporter } from "./ImageSnapshotReporter-BdJsioWe.js";
 
 //#region src/reporter.ts
 var reporter_default = ImageSnapshotReporter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-image-snapshot",
-  "version": "0.6.39",
+  "version": "0.6.40",
   "type": "module",
   "files": [
     "dist",