vitest-image-snapshot 0.6.39 → 0.6.40

package/src/DiffReport.ts

@@ -1,8 +1,14 @@
 import { exec } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ComparisonResult } from "./ImageComparison.ts";
 
+const templatesDir = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "templates",
+);
+
 /** Failed image snapshot with comparison results and file paths. */
 export interface ImageSnapshotFailure {
   testName: string;
@@ -23,38 +29,61 @@ export 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. */
+export async function clearDiffReport(reportDir: string): Promise<void> {
+  if (fs.existsSync(reportDir)) {
+    await fs.promises.rm(reportDir, { recursive: true });
+  }
+}
+
+/** Generate HTML diff report for image snapshot results. */
 export async function generateDiffReport(
   failures: ImageSnapshotFailure[],
   config: DiffReportConfig,
 ): Promise<void> {
-  const { autoOpen = false, reportDir, configRoot } = config;
-
-  if (failures.length === 0) return;
+  const {
+    autoOpen = false,
+    reportDir,
+    configRoot,
+    liveReload = false,
+  } = config;
 
+  // Clear old report before generating new one to remove stale images
+  await clearDiffReport(reportDir);
   await fs.promises.mkdir(reportDir, { recursive: true });
 
-  const withCopiedImages = await copyImagesToReport(
-    failures,
-    reportDir,
-    configRoot,
-  );
-  const html = createReportHTML(withCopiedImages);
+  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 withCopiedImages =
+    failures.length > 0
+      ? await copyImagesToReport(failures, reportDir, configRoot)
+      : [];
+  const html = createReportHTML(withCopiedImages, liveReload);
   const outputPath = path.join(reportDir, "index.html");
 
   await fs.promises.writeFile(outputPath, html, "utf-8");
 
-  console.log(`\n📊 Image diff report: ${outputPath}`);
+  // Only log file path if not using live reload server (which logs its own URL)
+  if (failures.length > 0 && !liveReload) {
+    console.log(`\n Image diff report: ${outputPath}`);
+  }
 
   if (autoOpen) {
-    const cmd =
-      process.platform === "darwin"
-        ? "open"
-        : process.platform === "win32"
-          ? "start"
-          : "xdg-open";
+    const commands: Record<string, string> = { darwin: "open", win32: "start" };
+    const cmd = commands[process.platform] ?? "xdg-open";
     exec(`${cmd} "${outputPath}"`);
   }
 }
@@ -67,28 +96,17 @@ async function copyImagesToReport(
 ): Promise<ImageSnapshotFailure[]> {
   return Promise.all(
     failures.map(async failure => {
-      const copiedPaths = await copyImageSet(
-        failure.paths,
-        reportDir,
-        configRoot,
-      );
+      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 };
     }),
   );
 }
 
-async function copyImageSet(
-  paths: { reference: string; actual: string; diff: string },
-  reportDir: string,
-  configRoot: string,
-): Promise<{ reference: string; actual: string; diff: string }> {
-  return {
-    reference: await copyImage(paths.reference, reportDir, configRoot),
-    actual: await copyImage(paths.actual, reportDir, configRoot),
-    diff: await copyImage(paths.diff, reportDir, configRoot),
-  };
-}
-
 /** Copy single image to report dir, preserving directory structure relative to configRoot */
 async function copyImage(
   sourcePath: string,
@@ -106,16 +124,61 @@ async function copyImage(
   return relativePath;
 }
 
-function createReportHTML(failures: ImageSnapshotFailure[]): string {
+function loadTemplate(name: string): string {
+  return fs.readFileSync(path.join(templatesDir, name), "utf-8");
+}
+
+/** Replace all {{key}} placeholders in template with values from data object. */
+function renderTemplate(
+  template: string,
+  data: Record<string, string>,
+): string {
+  let result = template;
+  for (const [key, value] of Object.entries(data)) {
+    result = result.replaceAll(`{{${key}}}`, value);
+  }
+
+  // Check for any unreplaced placeholders
+  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: ImageSnapshotFailure[],
+  liveReload: boolean,
+): string {
   const timestamp = new Date().toLocaleString();
   const totalFailures = failures.length;
+  const script = liveReload ? `<script src="live-reload.js"></script>` : "";
 
-  const rows = failures
-    .map(failure => {
-      const { testName, snapshotName, comparison, paths } = failure;
-      const { mismatchedPixels, mismatchedPixelRatio } = comparison;
+  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: ImageSnapshotFailure): string {
+  const { testName, snapshotName, comparison, paths } = failure;
+  const { mismatchedPixels, mismatchedPixelRatio } = comparison;
 
-      return `
+  return `
       <tr>
         <td class="test-name">
           <strong>${escapeHtml(testName)}</strong><br>
@@ -140,176 +203,7 @@ function createReportHTML(failures: ImageSnapshotFailure[]): string {
           <div><strong>${mismatchedPixels}</strong> pixels</div>
           <div><strong>${(mismatchedPixelRatio * 100).toFixed(2)}%</strong></div>
         </td>
-      </tr>
-    `;
-    })
-    .join("\n");
-
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Image Snapshot Failures - ${totalFailures} failed</title>
-  <style>
-    * { margin: 0; padding: 0; box-sizing: border-box; }
-    body {
-      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-      padding: 20px;
-      background: #f5f5f5;
-    }
-    header {
-      background: white;
-      padding: 20px;
-      border-radius: 8px;
-      margin-bottom: 20px;
-      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
-    }
-    h1 {
-      color: #d73027;
-      margin-bottom: 10px;
-    }
-    .meta {
-      color: #666;
-      font-size: 14px;
-    }
-    .update-hint {
-      background: #fff3cd;
-      border: 1px solid #ffc107;
-      border-radius: 4px;
-      padding: 12px;
-      margin: 15px 0;
-    }
-    .update-hint code {
-      background: #f8f9fa;
-      padding: 2px 6px;
-      border-radius: 3px;
-      font-family: 'Monaco', 'Courier New', monospace;
-    }
-    table {
-      width: 100%;
-      border-collapse: collapse;
-      background: white;
-      border-radius: 8px;
-      overflow: hidden;
-      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
-    }
-    th, td {
-      padding: 15px;
-      text-align: left;
-      border-bottom: 1px solid #e0e0e0;
-    }
-    th {
-      background: #f8f9fa;
-      font-weight: 600;
-      color: #333;
-      text-align: center;
-    }
-    tr:last-child td {
-      border-bottom: none;
-    }
-    tr:hover {
-      background: #fafafa;
-    }
-    .test-name {
-      min-width: 200px;
-      vertical-align: top;
-    }
-    .test-name strong {
-      color: #333;
-    }
-    .test-name code {
-      color: #666;
-      font-size: 12px;
-      background: #f5f5f5;
-      padding: 2px 6px;
-      border-radius: 3px;
-    }
-    .image-cell {
-      text-align: center;
-      vertical-align: top;
-      width: 25%;
-    }
-    .image-cell a {
-      display: block;
-      text-decoration: none;
-    }
-    .image-cell img {
-      max-width: 100%;
-      height: auto;
-      max-height: 300px;
-      border: 1px solid #ddd;
-      border-radius: 4px;
-      cursor: pointer;
-      transition: transform 0.2s;
-    }
-    .image-cell img:hover {
-      transform: scale(1.02);
-      box-shadow: 0 4px 12px rgba(0,0,0,0.15);
-    }
-    .label {
-      margin-top: 8px;
-      font-size: 12px;
-      color: #666;
-      font-weight: 500;
-    }
-    .no-diff {
-      color: #999;
-      font-size: 13px;
-      font-style: italic;
-      padding: 20px;
-      text-align: center;
-    }
-    .stats {
-      text-align: center;
-      color: #d73027;
-      font-size: 14px;
-      vertical-align: top;
-    }
-    .stats div {
-      margin: 5px 0;
-    }
-    footer {
-      margin-top: 20px;
-      text-align: center;
-      color: #999;
-      font-size: 12px;
-    }
-  </style>
-</head>
-<body>
-  <header>
-    <h1>🔴 Image Snapshot Failures</h1>
-    <div class="meta">
-      <strong>${totalFailures}</strong> test${totalFailures === 1 ? "" : "s"} failed •
-      Generated: ${escapeHtml(timestamp)}
-    </div>
-    <div class="update-hint">
-      💡 <strong>To update snapshots:</strong> Run <code>pnpm test -- -u</code> or <code>vitest -u</code>
-    </div>
-  </header>
-
-  <table>
-    <thead>
-      <tr>
-        <th>Test</th>
-        <th>Expected</th>
-        <th>Actual</th>
-        <th>Diff</th>
-        <th>Mismatch</th>
-      </tr>
-    </thead>
-    <tbody>
-      ${rows}
-    </tbody>
-  </table>
-
-  <footer>
-    Click images to view full size •
-    Diff images highlight mismatched pixels in yellow/red
-  </footer>
-</body>
-</html>`;
+      </tr>`;
 }
 
 function escapeHtml(text: string): string {

package/src/ImageSnapshotReporter.ts

@@ -1,8 +1,15 @@
+import * as fs from "node:fs";
+import * as http from "node:http";
 import * as path from "node:path";
-import type { Reporter, TestCase, Vitest } from "vitest/node";
+import type {
+  Reporter,
+  TestCase,
+  TestSpecification,
+  Vitest,
+} from "vitest/node";
 import { generateDiffReport, type ImageSnapshotFailure } from "./DiffReport.ts";
 
-/** metadata saved at failure for future report */
+/** Metadata captured when image snapshot test fails, used to generate HTML report. */
 interface ImageSnapshotFailureData {
   actualPath: string;
   expectedPath: string;
@@ -15,23 +22,92 @@ export 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 */
 export class ImageSnapshotReporter implements Reporter {
-  private failures: ImageSnapshotFailure[] = [];
+  private failuresByFile = new Map<string, ImageSnapshotFailure[]>();
   private vitest!: Vitest;
   private reportPath?: string;
   private autoOpen: boolean;
+  private port: number;
+  private serverStarted = false;
 
   constructor(options: ImageSnapshotReporterOptions = {}) {
     this.reportPath = options.reportPath;
     this.autoOpen =
       options.autoOpen ?? process.env.IMAGE_DIFF_AUTO_OPEN === "true";
+    this.port = options.port ?? 4343;
   }
 
   onInit(vitest: Vitest) {
     this.vitest = vitest;
+    if (this.port > 0) {
+      this.startServer();
+    }
+  }
+
+  private 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(),
+        };
+
+        // For HEAD requests (used by live reload), just send headers
+        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(); // Don't keep process alive just for this server
+  }
+
+  onTestRunStart(specifications: ReadonlyArray<TestSpecification>) {
+    // Clear failures only for files that are about to run
+    for (const spec of specifications) {
+      this.failuresByFile.delete(spec.moduleId);
+    }
   }
 
   onTestCaseResult(testCase: TestCase) {
@@ -49,17 +125,18 @@ export class ImageSnapshotReporter implements Reporter {
       meta.imageSnapshotFailure,
       error?.message || "",
     );
-    this.failures.push(failure);
+    const moduleId = testCase.module.moduleId;
+    const existing = this.failuresByFile.get(moduleId) || [];
+    this.failuresByFile.set(moduleId, [...existing, failure]);
   }
 
   async onTestRunEnd() {
-    if (this.failures.length === 0) return;
-
-    const reportDir = this.resolveReportDir();
-    await generateDiffReport(this.failures, {
+    const allFailures = [...this.failuresByFile.values()].flat();
+    await generateDiffReport(allFailures, {
       autoOpen: this.autoOpen,
-      reportDir,
+      reportDir: this.resolveReportDir(),
       configRoot: this.vitest.config.root,
+      liveReload: this.serverStarted,
     });
   }
 

package/src/templates/live-reload.js

@@ -0,0 +1,9 @@
+let lastModified;
+setInterval(async () => {
+  try {
+    const res = await fetch(location.href, { method: "HEAD" });
+    const modified = res.headers.get("last-modified");
+    if (lastModified && modified !== lastModified) location.reload();
+    lastModified = modified;
+  } catch {}
+}, 500);

package/src/templates/report-failure.hbs

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Image Snapshots - {{totalFailures}} failed</title>
+  <link rel="stylesheet" href="report.css">
+</head>
+<body>
+  <header>
+    <h1>Image Snapshot Failures</h1>
+    <div class="meta">
+      <strong>{{totalFailures}}</strong> {{testPlural}} failed |
+      Generated: {{timestamp}}
+    </div>
+    <div class="update-hint">
+      <strong>To update snapshots:</strong> Run <code>vitest -u</code>
+    </div>
+  </header>
+
+  <table>
+    <thead>
+      <tr>
+        <th>Test</th>
+        <th>Expected</th>
+        <th>Actual</th>
+        <th>Diff</th>
+        <th>Mismatch</th>
+      </tr>
+    </thead>
+    <tbody>
+      {{rows}}
+    </tbody>
+  </table>
+
+  <footer>
+    Click images to view full size |
+    Diff images highlight mismatched pixels in yellow/red
+  </footer>
+{{script}}
+</body>
+</html>

package/src/templates/report-success.hbs

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Image Snapshots - All Passing</title>
+  <link rel="stylesheet" href="report.css">
+</head>
+
+<body>
+  <header class="success">
+    <h1>All Image Snapshots Passing</h1>
+    <div class="meta">Generated: {{timestamp}}</div>
+  </header>
+  {{script}}
+</body>
+
+</html>