snapdrift 0.2.0

package/lib/capture-routes.mjs

@@ -0,0 +1,370 @@
+// @ts-check
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { chromium } from 'playwright';
+import pngjs from 'pngjs';
+
+import {
+  loadSnapdriftConfig,
+  readFirstDefinedEnv,
+  resolveFromWorkingDirectory,
+  selectConfiguredRoutes,
+  splitCommaList,
+  SNAPDRIFT_VIEWPORT_PRESETS,
+  SNAPDRIFT_NAVIGATION_TIMEOUT_MS,
+  SNAPDRIFT_SETTLE_DELAY_MS
+} from './snapdrift-config.mjs';
+
+const { PNG } = pngjs;
+
+/** @typedef {import('../types/visual-diff-types').VisualBaselineResults} BaselineResults */
+/** @typedef {import('../types/visual-diff-types').VisualBaselineRouteResult} BaselineRouteResult */
+/** @typedef {import('../types/visual-diff-types').VisualRegressionRouteConfig} SnapdriftRouteConfig */
+/** @typedef {import('../types/visual-diff-types').VisualScreenshotManifest} ScreenshotManifest */
+
+/**
+ * @param {string} targetPath
+ * @returns {Promise<void>}
+ */
+async function ensureParentDirectory(targetPath) {
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+}
+
+/**
+ * @param {string} targetPath
+ * @returns {Promise<void>}
+ */
+async function ensureDirectory(targetPath) {
+  await fs.mkdir(targetPath, { recursive: true });
+}
+
+/**
+ * Strips characters that could cause path traversal or produce invalid filenames.
+ * @param {string} id
+ * @returns {string}
+ */
+function sanitizeRouteId(id) {
+  return id
+    .replace(/\.\./g, '_')
+    .replace(/[/\\]/g, '_')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1f\x7f]/g, '');
+}
+
+/** @typedef {import('../types/visual-diff-types').VisualViewport} VisualViewport */
+
+/**
+ * Returns a stable string key for a viewport value (preset name or custom dimensions).
+ * @param {VisualViewport} viewport
+ * @returns {string}
+ */
+function viewportKey(viewport) {
+  return typeof viewport === 'string' ? viewport : `custom:${viewport.width}x${viewport.height}`;
+}
+
+/**
+ * Returns a human-readable label for a viewport.
+ * @param {VisualViewport} viewport
+ * @returns {string}
+ */
+function viewportLabel(viewport) {
+  return typeof viewport === 'string' ? viewport : `${viewport.width}x${viewport.height}`;
+}
+
+/**
+ * Returns Playwright context options for a viewport.
+ * @param {VisualViewport} viewport
+ * @returns {import('playwright').BrowserContextOptions}
+ */
+function viewportContextOptions(viewport) {
+  if (typeof viewport === 'string') {
+    const preset = SNAPDRIFT_VIEWPORT_PRESETS[viewport];
+    return {
+      viewport: { width: preset.width, height: preset.height },
+      deviceScaleFactor: preset.deviceScaleFactor,
+      isMobile: preset.isMobile,
+      hasTouch: preset.hasTouch
+    };
+  }
+  return {
+    viewport: { width: viewport.width, height: viewport.height },
+    deviceScaleFactor: 1,
+    isMobile: false,
+    hasTouch: false
+  };
+}
+
+/**
+ * @param {import('playwright').Browser} browser
+ * @returns {Promise<Map<'desktop' | 'mobile', import('playwright').BrowserContext>>}
+ */
+async function createViewportContexts(browser) {
+  return new Map([
+    ['desktop', await browser.newContext({
+      viewport: { width: SNAPDRIFT_VIEWPORT_PRESETS.desktop.width, height: SNAPDRIFT_VIEWPORT_PRESETS.desktop.height },
+      deviceScaleFactor: SNAPDRIFT_VIEWPORT_PRESETS.desktop.deviceScaleFactor,
+      isMobile: SNAPDRIFT_VIEWPORT_PRESETS.desktop.isMobile,
+      hasTouch: SNAPDRIFT_VIEWPORT_PRESETS.desktop.hasTouch
+    })],
+    ['mobile', await browser.newContext({
+      viewport: { width: SNAPDRIFT_VIEWPORT_PRESETS.mobile.width, height: SNAPDRIFT_VIEWPORT_PRESETS.mobile.height },
+      deviceScaleFactor: SNAPDRIFT_VIEWPORT_PRESETS.mobile.deviceScaleFactor,
+      isMobile: SNAPDRIFT_VIEWPORT_PRESETS.mobile.isMobile,
+      hasTouch: SNAPDRIFT_VIEWPORT_PRESETS.mobile.hasTouch
+    })]
+  ]);
+}
+
+/**
+ * @param {import('playwright').BrowserContext} context
+ * @param {SnapdriftRouteConfig} route
+ * @param {string} baseUrl
+ * @param {string} screenshotsRoot
+ * @returns {Promise<BaselineRouteResult & { manifestEntry?: ScreenshotManifest['screenshots'][number] }>}
+ */
+async function captureRoute(context, route, baseUrl, screenshotsRoot) {
+  const startedAt = Date.now();
+
+  const page = await context.newPage();
+  try {
+    const targetUrl = new URL(route.path, baseUrl).toString();
+    await page.goto(targetUrl, {
+      waitUntil: 'networkidle',
+      timeout: SNAPDRIFT_NAVIGATION_TIMEOUT_MS
+    });
+    await page.waitForTimeout(SNAPDRIFT_SETTLE_DELAY_MS);
+
+    const imagePath = path.join('screenshots', `${sanitizeRouteId(route.id)}.png`);
+    const absoluteImagePath = path.join(screenshotsRoot, imagePath);
+    await ensureParentDirectory(absoluteImagePath);
+    const screenshotBuffer = await page.screenshot({
+      path: absoluteImagePath,
+      fullPage: true
+    });
+    const screenshot = PNG.sync.read(screenshotBuffer);
+
+    return {
+      id: route.id,
+      path: route.path,
+      viewport: route.viewport,
+      status: 'passed',
+      durationMs: Date.now() - startedAt,
+      imagePath,
+      width: screenshot.width,
+      height: screenshot.height,
+      manifestEntry: {
+        id: route.id,
+        path: route.path,
+        viewport: route.viewport,
+        imagePath,
+        width: screenshot.width,
+        height: screenshot.height
+      }
+    };
+  } catch (error) {
+    return {
+      id: route.id,
+      path: route.path,
+      viewport: route.viewport,
+      status: 'failed',
+      durationMs: Date.now() - startedAt,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  } finally {
+    await page.close();
+  }
+}
+
+const CAPTURE_MAX_RETRIES = 1;
+
+/**
+ * @param {import('playwright').BrowserContext} context
+ * @param {SnapdriftRouteConfig} route
+ * @param {string} baseUrl
+ * @param {string} screenshotsRoot
+ * @returns {Promise<BaselineRouteResult & { manifestEntry?: ScreenshotManifest['screenshots'][number] }>}
+ */
+async function captureRouteWithRetry(context, route, baseUrl, screenshotsRoot) {
+  let result = await captureRoute(context, route, baseUrl, screenshotsRoot);
+  for (let attempt = 1; attempt <= CAPTURE_MAX_RETRIES && result.status !== 'passed'; attempt++) {
+    console.log(`[SnapDrift] Retrying route ${route.id} (attempt ${attempt + 1}/${CAPTURE_MAX_RETRIES + 1})...`);
+    result = await captureRoute(context, route, baseUrl, screenshotsRoot);
+  }
+  return result;
+}
+
+/**
+ * Captures all routes for a single viewport context sequentially, logging progress.
+ *
+ * @param {import('playwright').BrowserContext} context
+ * @param {Array<{ route: SnapdriftRouteConfig, originalIndex: number }>} entries
+ * @param {string} baseUrl
+ * @param {string} screenshotsRoot
+ * @param {number} totalRoutes
+ * @param {Array<BaselineRouteResult & { manifestEntry?: ScreenshotManifest['screenshots'][number] }>} out
+ * @returns {Promise<void>}
+ */
+async function captureViewportRoutes(context, entries, baseUrl, screenshotsRoot, totalRoutes, out) {
+  for (const { route, originalIndex } of entries) {
+    console.log(`[SnapDrift] Capturing route ${originalIndex + 1}/${totalRoutes}: ${route.id} (${viewportLabel(route.viewport)})`);
+    out[originalIndex] = await captureRouteWithRetry(context, route, baseUrl, screenshotsRoot);
+  }
+}
+
+/**
+ * @param {{
+ *   configPath?: string,
+ *   routeIds?: Iterable<string>,
+ *   outDir?: string
+ * }} [options]
+ * @returns {Promise<{ resultsPath: string, manifestPath: string, screenshotsRoot: string, selectedRouteIds: string[] }>}
+ */
+export async function runBaselineCapture(options = {}) {
+  const requestedRouteIds = [...(
+    options.routeIds || splitCommaList(readFirstDefinedEnv(['SNAPDRIFT_ROUTE_IDS']))
+  )];
+  const { config, configPath } = await loadSnapdriftConfig(options.configPath);
+  const { routes, selectedRouteIds } = selectConfiguredRoutes(config, requestedRouteIds);
+
+  // When outDir is provided (e.g. by the local CLI), store all outputs flat inside that directory
+  // using just the basename of each configured path.  Otherwise, use the config-resolved paths.
+  const localOutDir = options.outDir ? path.resolve(options.outDir) : null;
+  const resultsPath = localOutDir
+    ? path.join(localOutDir, path.basename(config.resultsFile))
+    : resolveFromWorkingDirectory(config, config.resultsFile);
+  const manifestPath = localOutDir
+    ? path.join(localOutDir, path.basename(config.manifestFile))
+    : resolveFromWorkingDirectory(config, config.manifestFile);
+  const screenshotsRoot = localOutDir || resolveFromWorkingDirectory(config, config.screenshotsRoot);
+
+  // Screenshots are written to a `screenshots/` subdirectory inside screenshotsRoot,
+  // i.e. the actual PNG files land at `{screenshotsRoot}/screenshots/{id}.png`.
+  await Promise.all([
+    ensureParentDirectory(resultsPath),
+    ensureParentDirectory(manifestPath),
+    ensureDirectory(path.join(screenshotsRoot, 'screenshots'))
+  ]);
+
+  /** @type {BaselineResults} */
+  const results = {
+    startedAt: new Date().toISOString(),
+    baseUrl: config.baseUrl,
+    suite: 'snapdrift-capture',
+    configPath: path.relative(path.resolve('.'), configPath),
+    manifestPath: path.relative(path.resolve('.'), manifestPath),
+    screenshotsRoot: path.relative(path.resolve('.'), screenshotsRoot),
+    routes: []
+  };
+
+  /** @type {ScreenshotManifest} */
+  const manifest = {
+    generatedAt: new Date().toISOString(),
+    baseUrl: config.baseUrl,
+    screenshots: []
+  };
+
+  const browser = await chromium.launch({ headless: true });
+  // Pre-create contexts for the two standard presets; custom viewports are created on demand below.
+  const presetContexts = await createViewportContexts(browser);
+  /** @type {Map<string, import('playwright').BrowserContext>} */
+  const allContexts = new Map(presetContexts);
+  let failures = 0;
+
+  try {
+    // Group routes by viewport key, preserving each route's original index for result ordering.
+    /** @type {Map<string, Array<{ route: SnapdriftRouteConfig, originalIndex: number }>>} */
+    const byViewport = new Map();
+    for (const [i, route] of routes.entries()) {
+      const key = viewportKey(route.viewport);
+      const existing = byViewport.get(key);
+      if (existing) {
+        existing.push({ route, originalIndex: i });
+      } else {
+        byViewport.set(key, [{ route, originalIndex: i }]);
+      }
+    }
+
+    // Create browser contexts for any custom viewports not covered by presets.
+    for (const [key, entries] of byViewport) {
+      if (!allContexts.has(key)) {
+        try {
+          allContexts.set(key, await browser.newContext(viewportContextOptions(entries[0].route.viewport)));
+        } catch (err) {
+          const message = `Failed to create browser context: ${err instanceof Error ? err.message : String(err)}`;
+          for (const { route } of entries) {
+            results.routes.push({ id: route.id, path: route.path, viewport: route.viewport, status: 'failed', durationMs: 0, error: message });
+            failures += 1;
+          }
+          throw err;
+        }
+      }
+    }
+
+    // Pre-allocate results array; captureViewportRoutes fills slots by originalIndex.
+    /** @type {Array<BaselineRouteResult & { manifestEntry?: ScreenshotManifest['screenshots'][number] }>} */
+    const captureResults = new Array(routes.length);
+
+    // Run each viewport group concurrently; routes within a group stay sequential.
+    await Promise.all([...byViewport.entries()].map(([key, entries]) => {
+      const context = allContexts.get(key);
+      if (!context) {
+        throw new Error(`No browser context for viewport: ${key}`);
+      }
+      return captureViewportRoutes(context, entries, config.baseUrl, screenshotsRoot, routes.length, captureResults);
+    }));
+
+    // Merge results in original route order.
+    for (const capture of captureResults) {
+      results.routes.push({
+        id: capture.id,
+        path: capture.path,
+        viewport: capture.viewport,
+        status: capture.status,
+        durationMs: capture.durationMs,
+        imagePath: capture.imagePath,
+        width: capture.width,
+        height: capture.height,
+        error: capture.error
+      });
+      if (capture.manifestEntry) {
+        manifest.screenshots.push(capture.manifestEntry);
+      }
+      if (capture.status !== 'passed') {
+        failures += 1;
+      }
+    }
+  } finally {
+    await Promise.all([...allContexts.values()].map((context) => context.close()));
+    await browser.close();
+    results.finishedAt = new Date().toISOString();
+    results.passed = failures === 0;
+    manifest.generatedAt = new Date().toISOString();
+
+    await Promise.all([
+      fs.writeFile(resultsPath, JSON.stringify(results, null, 2)),
+      fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2))
+    ]);
+  }
+
+  if (failures > 0) {
+    throw new Error(`SnapDrift capture failed for ${failures} route(s).`);
+  }
+
+  return {
+    resultsPath,
+    manifestPath,
+    screenshotsRoot,
+    selectedRouteIds
+  };
+}
+
+const isDirectRun = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;
+
+if (isDirectRun) {
+  runBaselineCapture().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}

package/lib/cli.mjs

@@ -0,0 +1,241 @@
+// @ts-check
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { runBaselineCapture } from './capture-routes.mjs';
+import { generateDriftReport, shouldFailDriftCheck } from './compare-results.mjs';
+import { generateHtmlReport } from './report.mjs';
+import { loadSnapdriftConfig } from './snapdrift-config.mjs';
+
+/** @typedef {import('../types/visual-diff-types').VisualDiffSummary} DriftSummary */
+
+export const LOCAL_SNAPDRIFT_DIR = '.snapdrift';
+export const LOCAL_BASELINE_SUBDIR = 'baseline';
+export const LOCAL_CURRENT_SUBDIR = 'current';
+export const LOCAL_DIFF_SUBDIR = 'diff';
+
+/**
+ * @typedef {{
+ *   command: string,
+ *   open: boolean,
+ *   configPath?: string,
+ *   routes: string[],
+ *   baselineDir: string,
+ *   currentDir: string,
+ *   diffDir: string
+ * }} CliOptions
+ */
+
+/**
+ * Parse CLI arguments from process.argv (or a provided argv array).
+ * Supported commands: capture, diff
+ * Supported flags:
+ *   --open              Open the HTML report after diff
+ *   --config <path>     Path to snapdrift.json (default: .github/snapdrift.json)
+ *   --routes <ids>      Comma-separated route IDs to run
+ *   --baseline-dir <p>  Override local baseline directory (default: .snapdrift/baseline)
+ *   --current-dir <p>   Override local current-capture directory (default: .snapdrift/current)
+ *   --diff-dir <p>      Override local diff-output directory (default: .snapdrift/diff)
+ *
+ * @param {string[]} argv - process.argv
+ * @returns {CliOptions}
+ */
+export function parseArgs(argv) {
+  const args = argv.slice(2);
+  const command = args[0] || 'diff';
+  let open = false;
+  /** @type {string | undefined} */
+  let configPath;
+  /** @type {string[]} */
+  const routes = [];
+  let baselineDir = path.resolve(LOCAL_SNAPDRIFT_DIR, LOCAL_BASELINE_SUBDIR);
+  let currentDir = path.resolve(LOCAL_SNAPDRIFT_DIR, LOCAL_CURRENT_SUBDIR);
+  let diffDir = path.resolve(LOCAL_SNAPDRIFT_DIR, LOCAL_DIFF_SUBDIR);
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--open') {
+      open = true;
+    } else if (arg === '--config' && i + 1 < args.length) {
+      configPath = args[++i];
+    } else if (arg === '--routes' && i + 1 < args.length) {
+      routes.push(
+        ...args[++i]
+          .split(',')
+          .map((r) => r.trim())
+          .filter(Boolean)
+      );
+    } else if (arg === '--baseline-dir' && i + 1 < args.length) {
+      baselineDir = path.resolve(args[++i]);
+    } else if (arg === '--current-dir' && i + 1 < args.length) {
+      currentDir = path.resolve(args[++i]);
+    } else if (arg === '--diff-dir' && i + 1 < args.length) {
+      diffDir = path.resolve(args[++i]);
+    }
+  }
+
+  return { command, open, configPath, routes, baselineDir, currentDir, diffDir };
+}
+
+/**
+ * Format and print a drift summary to stdout.
+ *
+ * @param {DriftSummary} summary
+ * @returns {void}
+ */
+export function printSummary(summary) {
+  const total = summary.totalScreenshots ?? summary.selectedRoutes?.length ?? 0;
+  const matched = summary.matchedScreenshots ?? 0;
+  const changed = summary.changedScreenshots ?? 0;
+  const missing = (summary.missingInBaseline ?? 0) + (summary.missingInCurrent ?? 0);
+  const errors = summary.errors?.length ?? 0;
+  const dimensionChanges = summary.dimensionChanges?.length ?? 0;
+
+  const statusIcon =
+    summary.status === 'clean'
+      ? '\u2705' // ✅
+      : summary.status === 'changes-detected'
+        ? '\uD83D\uDFE1' // 🟡
+        : '\u274C'; // ❌
+  const statusLabel =
+    summary.status === 'clean'
+      ? 'Clean'
+      : summary.status === 'changes-detected'
+        ? 'Drift detected'
+        : summary.status ?? 'Unknown';
+
+  process.stdout.write(`\n${statusIcon}  SnapDrift \u2014 ${statusLabel}\n`);
+  process.stdout.write(`   Routes:   ${total}\n`);
+  process.stdout.write(`   Matched:  ${matched}\n`);
+  if (changed > 0) process.stdout.write(`   Changed:  ${changed}\n`);
+  if (missing > 0) process.stdout.write(`   Missing:  ${missing}\n`);
+  if (errors > 0) process.stdout.write(`   Errors:   ${errors}\n`);
+  if (dimensionChanges > 0) process.stdout.write(`   Dim diff: ${dimensionChanges}\n`);
+
+  if (summary.changed?.length) {
+    process.stdout.write('\n   Changed routes:\n');
+    for (const item of summary.changed) {
+      const pct = ((item.mismatchRatio ?? 0) * 100).toFixed(2);
+      process.stdout.write(`     \u2022 ${item.id} (${pct}% diff)\n`);
+    }
+  }
+
+  process.stdout.write('\n');
+}
+
+/**
+ * Open a file with the OS default viewer.
+ *
+ * @param {string} filePath
+ * @returns {void}
+ */
+function openFile(filePath) {
+  const cmd =
+    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    execSync(`${cmd} "${filePath}"`);
+  } catch {
+    process.stderr.write(`Could not open file: ${filePath}\n`);
+  }
+}
+
+/**
+ * Run the `capture` command — capture screenshots to a local baseline directory.
+ *
+ * @param {CliOptions} opts
+ * @returns {Promise<void>}
+ */
+export async function runCaptureCommand(opts) {
+  process.stdout.write(`Capturing baseline to ${opts.baselineDir} ...\n`);
+  const { selectedRouteIds } = await runBaselineCapture({
+    configPath: opts.configPath,
+    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+    outDir: opts.baselineDir
+  });
+  process.stdout.write(`Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
+}
+
+/**
+ * Run the `diff` command — capture current screenshots, compare against the local baseline,
+ * write a summary + HTML report, and optionally open it.
+ *
+ * @param {CliOptions} opts
+ * @returns {Promise<void>}
+ */
+export async function runDiffCommand(opts) {
+  process.stdout.write(`Capturing current screenshots to ${opts.currentDir} ...\n`);
+  const { config } = await loadSnapdriftConfig(opts.configPath);
+
+  const currentCapture = await runBaselineCapture({
+    configPath: opts.configPath,
+    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+    outDir: opts.currentDir
+  });
+
+  process.stdout.write('Comparing against baseline ...\n');
+
+  const baselineResultsPath = path.join(opts.baselineDir, path.basename(config.resultsFile));
+  const baselineManifestPath = path.join(opts.baselineDir, path.basename(config.manifestFile));
+
+  await fs.mkdir(opts.diffDir, { recursive: true });
+  const summaryPath = path.join(opts.diffDir, 'summary.json');
+  const markdownPath = path.join(opts.diffDir, 'summary.md');
+  const htmlPath = path.join(opts.diffDir, 'report.html');
+
+  const { summary, markdown } = await generateDriftReport({
+    configPath: opts.configPath,
+    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+    baselineResultsPath,
+    baselineManifestPath,
+    currentResultsPath: currentCapture.resultsPath,
+    currentManifestPath: currentCapture.manifestPath,
+    baselineRunDir: opts.baselineDir,
+    currentRunDir: currentCapture.screenshotsRoot
+  });
+
+  const html = await generateHtmlReport(summary, {
+    baselineRunDir: opts.baselineDir,
+    currentRunDir: currentCapture.screenshotsRoot
+  });
+
+  await Promise.all([
+    fs.writeFile(summaryPath, JSON.stringify(summary, null, 2)),
+    fs.writeFile(markdownPath, markdown),
+    fs.writeFile(htmlPath, html)
+  ]);
+
+  printSummary(summary);
+
+  if (opts.open) {
+    openFile(htmlPath);
+  } else if (summary.status !== 'clean') {
+    process.stdout.write(`Report: ${htmlPath}\n`);
+  }
+
+  if (shouldFailDriftCheck(summary)) {
+    process.exitCode = 1;
+  }
+}
+
+/**
+ * Main CLI entry point — parse args and dispatch to the appropriate command.
+ *
+ * @param {string[]} argv
+ * @returns {Promise<void>}
+ */
+export async function main(argv) {
+  const opts = parseArgs(argv);
+
+  if (opts.command === 'capture') {
+    await runCaptureCommand(opts);
+  } else if (opts.command === 'diff') {
+    await runDiffCommand(opts);
+  } else {
+    process.stderr.write(
+      `Unknown command: ${opts.command}\nUsage: snapdrift <capture|diff> [options]\n`
+    );
+    process.exitCode = 1;
+  }
+}