snapdrift 0.4.0 → 0.5.1

package/lib/snap-provider.mjs

@@ -3,12 +3,13 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
+import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 
 import { makeMarkdown, buildReportCommentBody } from '@snapdrift/adapter-report-md';
-import { loadSnapdriftConfig } from '@snapdrift/adapter-fs';
-import { selectConfiguredRoutes, splitCommaList, determineDriftStatus } from '@snapdrift/manifest';
+import { loadSnapdriftConfig, runBaselineCapture } from '@snapdrift/adapter-fs';
+import { selectConfiguredRoutes, splitCommaList, determineDriftStatus, VIEWPORT_PRESETS } from '@snapdrift/manifest';
 
 /** @typedef {import('../types/visual-diff-types').VisualProvider} VisualProvider */
 /** @typedef {import('../types/visual-diff-types').ProviderCaptureOptions} CaptureOptions */
@@ -30,7 +31,37 @@ const MAX_RETRY_TOTAL_MS = 30000;
 const POLL_INTERVAL_MS = 2000;
 const MAX_POLL_DURATION_MS = 10 * 60 * 1000;
 
-const TERMINAL_RUN_STATUSES = new Set(['pass', 'fail', 'error']);
+// Snap reports a run as "new" when it has no baseline to compare against (first
+// capture for a project, or any baseline-publish run that intentionally omits a
+// baseline). It is a terminal state — the run never advances past it — so the
+// client must stop polling on it just like pass/fail/error.
+const TERMINAL_RUN_STATUSES = new Set(['pass', 'fail', 'error', 'new']);
+
+/**
+ * @param {string | undefined} baseUrl
+ * @returns {boolean}
+ */
+export function isLocalBaseUrl(baseUrl) {
+  if (!baseUrl) {
+    return false;
+  }
+
+  let hostname;
+  try {
+    hostname = new URL(baseUrl).hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+
+  const normalized = hostname.replace(/^\[/, '').replace(/\]$/, '');
+  if (normalized === 'localhost' || normalized.endsWith('.localhost')) {
+    return true;
+  }
+  if (normalized === '::1' || normalized === '0.0.0.0') {
+    return true;
+  }
+  return net.isIP(normalized) === 4 && normalized.startsWith('127.');
+}
 
 /**
  * @param {string} repoSlug
@@ -67,6 +98,8 @@ export class SnapProvider {
   #fetchFn;
   /** @type {(ms: number) => Promise<void>} */
   #sleepFn;
+  /** @type {(options?: { configPath?: string, routeIds?: Iterable<string>, outDir?: string }) => Promise<CaptureResult>} */
+  #localCaptureFn;
   /** @type {string} */
   #apiKey;
   /** @type {string} */
@@ -76,12 +109,17 @@ export class SnapProvider {
 
   /**
    * @param {SnapConfig} snapConfig — validated snap section from config
-   * @param {{ fetchFn?: typeof globalThis.fetch, sleepFn?: (ms: number) => Promise<void> }} [options]
+   * @param {{
+   *   fetchFn?: typeof globalThis.fetch,
+   *   sleepFn?: (ms: number) => Promise<void>,
+   *   localCaptureFn?: (options?: { configPath?: string, routeIds?: Iterable<string>, outDir?: string }) => Promise<CaptureResult>
+   * }} [options]
    */
   constructor(snapConfig, options = {}) {
     this.#snapConfig = snapConfig;
     this.#fetchFn = options.fetchFn ?? globalThis.fetch;
     this.#sleepFn = options.sleepFn ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    this.#localCaptureFn = options.localCaptureFn ?? runBaselineCapture;
     this.#apiUrl = (snapConfig.apiUrl || DEFAULT_API_URL).replace(/\/+$/, '');
     this.#apiKey = this.#resolveApiKey(snapConfig);
     this.#projectId = this.#resolveProjectId(snapConfig);
@@ -107,29 +145,67 @@ export class SnapProvider {
       ? [...options.routeIds]
       : splitCommaList(process.env.SNAPDRIFT_ROUTE_IDS);
     const { routes, selectedRouteIds } = selectConfiguredRoutes(config, requestedRouteIds);
+    const purpose = options.purpose ?? 'diff';
+
+    if (isLocalBaseUrl(config.baseUrl)) {
+      return this.#captureLocalAndUpload({
+        configPath: options.configPath,
+        routeIds: requestedRouteIds,
+        outDir: options.outDir,
+        config,
+        routes,
+        selectedRouteIds,
+        purpose
+      });
+    }
 
     const idempotencyKey = this.#generateIdempotencyKey();
-    const runResponse = await this.#request('POST', `/v1/visual/projects/${this.#projectId}/runs`, {
-      idempotencyKey,
-      routes: routes.map((r) => ({
-        id: r.id,
-        path: r.path,
-        viewport: r.viewport,
-        changePaths: r.changePaths
-      })),
-      captureProfile: this.#buildCaptureProfile()
+    const runId = `run_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
+
+    // For a diff run, resolve the latest accepted baseline so the Snap backend
+    // can attach it to this run's captures. Without a baselineId the server has
+    // nothing to diff against and short-circuits every capture to "diffed" with
+    // no comparison data, leaving the dashboard baseline + diff panes empty.
+    //
+    // For a baseline run we deliberately omit the baselineId: the run is
+    // establishing new ground truth, not comparing against the old baseline.
+    // Attaching one would make the backend diff the fresh captures against the
+    // prior baseline — wasteful at best, and on a dimension mismatch it errors
+    // the run and fails the publish.
+    const baselineId = purpose === 'baseline' ? null : await this.#resolveLatestBaselineId();
+
+    // We intentionally do NOT send captureProfileJson on run creation. SnapDrift
+    // submits routes for server-side rendering, so the render environment
+    // (browser/platform/fonts/viewport) is owned by Snap's render worker, not
+    // this client. When a baselineId is attached, the run-creation endpoint
+    // compares the run's capture profile against the baseline's, dereferencing
+    // nested fields (browser, platform, fonts, viewport) that our minimal
+    // profile does not populate — which crashes the server with a 500. The
+    // render worker already defaults locale/timezone/viewport when no profile
+    // is present, so omitting it here is behaviour-preserving.
+    await this.#request('POST', `/v1/visual/projects/${this.#projectId}/runs`, {
+      id: runId,
+      baseUrl: config.baseUrl,
+      trigger: 'ci',
+      ...(baselineId ? { baselineId } : {}),
+      // A baseline run must not be diffed. Suppress the server's
+      // auto-resolve-by-branch so no prior baseline is attached.
+      ...(purpose === 'baseline' ? { skipBaselineResolution: true } : {}),
+      ...this.#gitRunContext(),
     }, idempotencyKey);
 
-    const runId = runResponse.id;
-
     // Submit each route as a capture with its own idempotency key
     for (const route of routes) {
       const captureKey = this.#generateIdempotencyKey();
+      const captureId = `cap_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
+      const viewportDescriptor = typeof route.viewport === 'string'
+        ? (VIEWPORT_PRESETS[route.viewport] ?? { width: 1280, height: 720 })
+        : route.viewport;
       await this.#request('POST', `/v1/visual/runs/${runId}/captures`, {
-        idempotencyKey: captureKey,
+        id: captureId,
         routeId: route.id,
         routePath: route.path,
-        viewport: route.viewport
+        viewportDescriptorJson: JSON.stringify(viewportDescriptor),
       }, captureKey);
     }
 
@@ -199,21 +275,102 @@ export class SnapProvider {
   /**
    * Publish a baseline to Snap.
    *
+   * When called with a `resultsPath` that contains a `runId` (written by
+   * `capture()`), this method polls the run until all renders complete, then
+   * creates a snap baseline from the captured S3 keys. This is the primary
+   * path used by the baseline action with `provider: "snap"`.
+   *
    * @param {PublishBaselineOptions} options
    * @returns {Promise<PublishBaselineResult>}
    */
   async publishBaseline(options) {
+    const resultsPath = options.resultsPath
+      ?? (options.bundleDir ? path.join(path.resolve(options.bundleDir), 'results.json') : undefined);
+
+    // Snap-native baseline: poll the run that capture() submitted, then
+    // create a baseline from the rendered S3 keys.
+    if (resultsPath) {
+      let metadata;
+      try {
+        metadata = JSON.parse(await fs.readFile(resultsPath, 'utf-8'));
+      } catch { /* fall through to legacy path */ }
+
+      if (metadata?.runId) {
+        const { runId } = metadata;
+        const idempotencyKey = `baseline-${runId}`;
+
+        // Poll until the run reaches a terminal state (renders + auto-diffs finish)
+        const run = await this.#pollRun(runId);
+
+        if (run.status === 'error') {
+          throw new Error(
+            `Snap baseline run ${runId} ended with status "error" — cannot publish baseline. ` +
+            `Check the snap dashboard for capture error details.`
+          );
+        }
+
+        const captures = run.captures ?? [];
+        const rendered = captures.filter((c) => c.currentObjectKey);
+
+        if (rendered.length === 0) {
+          throw new Error(
+            `Snap baseline run ${runId} completed but no captures produced a screenshot ` +
+            `(${captures.length} capture(s) found, 0 rendered). Cannot publish an empty baseline.`
+          );
+        }
+
+        if (rendered.length < captures.length) {
+          const failed = captures.length - rendered.length;
+          process.stderr.write(
+            `[SnapDrift] Warning: ${failed} of ${captures.length} capture(s) did not produce ` +
+            `a screenshot and will be excluded from the baseline.\n`
+          );
+        }
+
+        // Build a manifest from the rendered captures
+        const routes = rendered.map((c) => ({
+            routeId: c.routeId,
+            routePath: c.routePath,
+            viewportDescriptorJson: c.viewportDescriptorJson,
+            objectKey: c.currentObjectKey
+          }));
+
+        const manifestJson = JSON.stringify({
+          schemaVersion: 1,
+          sourceRunId: runId,
+          routes
+        });
+
+        const baselineId = `bsl_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
+        await this.#request(
+          'POST',
+          `/v1/visual/projects/${this.#projectId}/baselines`,
+          {
+            id: baselineId,
+            refBranch: process.env.GITHUB_REF_NAME || process.env.GITHUB_HEAD_REF || 'main',
+            refSha: process.env.GITHUB_SHA || 'unknown',
+            manifestJson,
+            captureProfileJson: JSON.stringify(this.#buildCaptureProfile())
+          },
+          idempotencyKey
+        );
+
+        const bundleDir = await fs.mkdtemp(path.join(os.tmpdir(), 'snapdrift-snap-baseline-'));
+        return { bundleDir };
+      }
+    }
+
+    // Legacy / migration path: bundle dir with pre-built results/manifest
     const idempotencyKey = this.#generateIdempotencyKey();
     const body = { idempotencyKey };
 
-    // If a bundle directory is provided, read files from it
     if (options.bundleDir) {
       const bundleDir = path.resolve(options.bundleDir);
-      const resultsPath = options.resultsPath || path.join(bundleDir, 'results.json');
+      const bResultsPath = options.resultsPath || path.join(bundleDir, 'results.json');
       const manifestPath = options.manifestPath || path.join(bundleDir, 'manifest.json');
 
       try {
-        const results = JSON.parse(await fs.readFile(resultsPath, 'utf-8'));
+        const results = JSON.parse(await fs.readFile(bResultsPath, 'utf-8'));
         body.results = results;
       } catch { /* results.json may not exist */ }
 
@@ -222,7 +379,6 @@ export class SnapProvider {
         body.manifest = manifest;
       } catch { /* manifest.json may not exist */ }
 
-      // If results contain a runId, use it for idempotency
       if (body.results?.runId) {
         body.idempotencyKey = `baseline-${body.results.runId}`;
       }
@@ -439,6 +595,38 @@ export class SnapProvider {
     };
   }
 
+  /**
+   * Resolve the id of the latest accepted baseline for this project so it can
+   * be attached to a new run. Returns null when no baseline exists yet (the
+   * legitimate first-run case), so capture can still proceed.
+   *
+   * @returns {Promise<string | null>}
+   */
+  async #resolveLatestBaselineId() {
+    try {
+      const baseline = await this.#request('GET', `/v1/visual/projects/${this.#projectId}/baselines/latest`);
+      return baseline?.id ?? null;
+    } catch (error) {
+      if (error instanceof SnapApiError && error.status === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Collect git ref context from the GitHub Actions environment so the Snap
+   * dashboard can attribute the run to a branch. Uses GITHUB_HEAD_REF (the
+   * source branch on pull_request events) and falls back to GITHUB_REF_NAME
+   * (the branch on push events).
+   *
+   * @returns {{ branch?: string }}
+   */
+  #gitRunContext() {
+    const branch = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME;
+    return branch ? { branch } : {};
+  }
+
   /**
    * @returns {string}
    */
@@ -446,6 +634,101 @@ export class SnapProvider {
     return crypto.randomUUID();
   }
 
+  /**
+   * @param {{
+   *   configPath?: string,
+   *   routeIds: string[],
+   *   outDir?: string,
+   *   config: VisualRegressionConfig,
+   *   routes: VisualRegressionConfig['routes'],
+   *   selectedRouteIds: string[],
+   *   purpose: 'baseline' | 'diff'
+   * }} options
+   * @returns {Promise<CaptureResult>}
+   */
+  async #captureLocalAndUpload(options) {
+    const localCapture = await this.#localCaptureFn({
+      configPath: options.configPath,
+      routeIds: options.routeIds,
+      outDir: options.outDir
+    });
+
+    const localResults = JSON.parse(await fs.readFile(localCapture.resultsPath, 'utf-8'));
+    const manifest = JSON.parse(await fs.readFile(localCapture.manifestPath, 'utf-8'));
+    // Route ids are unique per the v1 schema (one viewport per route), so keying
+    // the manifest by id is an unambiguous join against the configured routes.
+    const manifestById = new Map((manifest.screenshots || []).map((entry) => [entry.id, entry]));
+
+    // Resolve every selected route to its screenshot up front, before any server
+    // call. A missing local capture then fails fast instead of leaving an
+    // orphaned run on Snap that can never complete.
+    const uploads = options.routes.map((route) => {
+      const manifestEntry = manifestById.get(route.id);
+      if (!manifestEntry) {
+        throw new Error(`Local Snap capture did not produce a screenshot for route "${route.id}".`);
+      }
+      return { route, manifestEntry };
+    });
+
+    const runId = `run_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
+    // A baseline run establishes new ground truth and must not be diffed, so we
+    // omit the baselineId. Captures then settle to "new" server-side (no
+    // comparison), and publishBaseline harvests their object keys. A diff run
+    // attaches the latest baseline so the backend can compare against it.
+    const baselineId = options.purpose === 'baseline' ? null : await this.#resolveLatestBaselineId();
+
+    await this.#request('POST', `/v1/visual/projects/${this.#projectId}/runs`, {
+      id: runId,
+      baseUrl: options.config.baseUrl,
+      trigger: 'ci',
+      ...(baselineId ? { baselineId } : {}),
+      // A baseline run must not be diffed. Suppress the server's
+      // auto-resolve-by-branch so no prior baseline is attached.
+      ...(options.purpose === 'baseline' ? { skipBaselineResolution: true } : {}),
+      ...this.#gitRunContext()
+    }, this.#generateIdempotencyKey());
+
+    for (const { route, manifestEntry } of uploads) {
+      const captureId = `cap_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
+      const viewportDescriptor = typeof route.viewport === 'string'
+        ? (VIEWPORT_PRESETS[route.viewport] ?? { width: 1280, height: 720 })
+        : route.viewport;
+
+      await this.#request('POST', `/v1/visual/runs/${runId}/captures`, {
+        id: captureId,
+        routeId: route.id,
+        routePath: route.path,
+        viewportDescriptorJson: JSON.stringify(viewportDescriptor),
+        // The screenshot is captured locally and uploaded below, not rendered by
+        // Snap. This flag tells the backend to keep the capture out of the render
+        // worker's queue — without it the worker would try to render baseUrl
+        // (a client-only/loopback address it can't reach) and error the run.
+        localCapture: true,
+      }, this.#generateIdempotencyKey());
+
+      const imagePath = path.resolve(localCapture.screenshotsRoot, manifestEntry.imagePath);
+      const imageBytes = await fs.readFile(imagePath);
+
+      await this.#request('POST', `/v1/visual/captures/${captureId}/local-result`, {
+        imageBase64: imageBytes.toString('base64'),
+        width: manifestEntry.width,
+        height: manifestEntry.height
+      }, this.#generateIdempotencyKey());
+    }
+
+    const snapResults = {
+      ...localResults,
+      provider: 'snap',
+      captureMode: 'local-upload',
+      runId,
+      projectId: this.#projectId,
+      snapStartedAt: new Date().toISOString()
+    };
+    await fs.writeFile(localCapture.resultsPath, JSON.stringify(snapResults, null, 2));
+
+    return localCapture;
+  }
+
   /**
    * Make an HTTP request to the Snap API with retry logic.
    *
@@ -587,6 +870,11 @@ export class SnapProvider {
     let changedScreenshots = 0;
     let missingInBaseline = 0;
     let missingInCurrent = 0;
+    // Track real comparisons (a baseline was attached) and how many came back
+    // pixel-identical (0% drift) so we can flag the "captured a stale/wrong
+    // page" pattern below. See issue #93.
+    let comparedWithBaseline = 0;
+    let exactZeroMatches = 0;
 
     /** @type {import('../types/visual-diff-types').VisualDiffChangedItem[]} */
     const changed = [];
@@ -607,8 +895,36 @@ export class SnapProvider {
         continue;
       }
 
+      if (capture.status === 'new') {
+        // The backend rendered this capture but had no baseline to diff against
+        // (first run for the route). Surface it as a missing baseline rather than
+        // a silent match — there is nothing to compare yet.
+        missingInBaseline++;
+        missing.push({
+          id: capture.routeId || capture.id,
+          reason: 'no baseline capture found on Snap',
+          path: capture.routePath,
+          viewport: capture.viewport,
+          location: 'baseline'
+        });
+        continue;
+      }
+
       if (capture.status === 'diffed') {
-        if (capture.diffPct !== null && capture.diffPct > config.diff.threshold) {
+        if (!capture.baselineObjectKey) {
+          // No baseline was attached to this capture: the backend short-circuits
+          // to "diffed" with no comparison data (no diffPct / diff image). Surface
+          // it as a missing baseline instead of silently counting it as a match.
+          missingInBaseline++;
+          missing.push({
+            id: capture.routeId || capture.id,
+            reason: 'no baseline capture found on Snap',
+            path: capture.routePath,
+            viewport: capture.viewport,
+            location: 'baseline'
+          });
+        } else if (capture.diffPct != null && capture.diffPct > config.diff.threshold) {
+          comparedWithBaseline++;
           changedScreenshots++;
           changed.push({
             id: capture.routeId || capture.id,
@@ -624,22 +940,35 @@ export class SnapProvider {
             status: 'changed'
           });
         } else {
+          comparedWithBaseline++;
+          if (capture.diffPct === 0) {
+            exactZeroMatches++;
+          }
           matchedScreenshots++;
         }
-
-        if (capture.baselineObjectKey === null && capture.diffPct === null) {
-          missingInBaseline++;
-          missing.push({
-            id: capture.routeId || capture.id,
-            reason: 'no baseline capture found on Snap',
-            path: capture.routePath,
-            viewport: capture.viewport,
-            location: 'baseline'
-          });
-        }
       }
     }
 
+    // False-negative guard: when a diff run compared every route against a real
+    // baseline yet every single comparison came back pixel-identical (0% drift),
+    // the most likely explanation is that the client captured a stale or wrong
+    // page (baseUrl pointing at production instead of the PR preview, the
+    // preview not being deployed yet, or a caching layer) rather than a genuine
+    // "nothing changed". Warn so a real regression isn't silently missed. We
+    // only warn (never fail): a PR with no visual change legitimately produces
+    // this same shape. We require more than one compared route — a single
+    // pixel-identical route is indistinguishable from an ordinary clean diff,
+    // whereas several independent routes all landing at exactly 0% is the
+    // tell-tale signature of a single stale source page. See issue #93.
+    if (comparedWithBaseline > 1 && exactZeroMatches === comparedWithBaseline) {
+      process.stderr.write(
+        `[SnapDrift] Warning: all ${comparedWithBaseline} compared route(s) were pixel-identical ` +
+        `to the baseline (0% drift). If you expected a visual change, the captured page may be ` +
+        `stale or wrong — verify the resolved baseUrl points at the PR preview and that the ` +
+        `preview was deployed before capture ran. See issue #93.\n`
+      );
+    }
+
     /** @type {import('../types/visual-diff-types').VisualDiffSummary} */
     const summary = {
       startedAt: run.startedAt || new Date().toISOString(),
@@ -662,7 +991,7 @@ export class SnapProvider {
       missing,
       errors,
       dimensionChanges: [],
-      dashboardUrl: `${this.#apiUrl}/projects/${this.#projectId}/runs/${run.id}`
+      dashboardUrl: `${this.#apiUrl}/dashboard/visual/${this.#projectId}/runs/${run.id}`
     };
 
     summary.status = determineDriftStatus(summary);
@@ -731,4 +1060,4 @@ export class SnapSkipError extends Error {
     super(message);
     this.name = 'SnapSkipError';
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "private": false,
   "type": "module",
   "description": "SnapDrift captures, compares, and reports UI drift for Playwright-based app checks.",
@@ -41,7 +41,7 @@
     "@eslint/js": "^10.0.1",
     "@types/jest": "^30.0.0",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.3.5",
+    "@types/node": "^26.1.0",
     "@types/pngjs": "^6.0.5",
     "eslint": "^10.2.0",
     "globals": "^17.4.0",
@@ -95,11 +95,11 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@snapdrift/adapter-fs": "^1.0.0",
+    "@snapdrift/adapter-fs": "^1.0.1",
     "@snapdrift/adapter-report-md": "^1.1.0",
     "@snapdrift/compare-core": "^1.0.0",
-    "@snapdrift/manifest": "^1.1.0",
-    "js-yaml": "^4.1.0",
+    "@snapdrift/manifest": "^1.2.0",
+    "js-yaml": "^5.2.1",
     "playwright": "^1.59.1",
     "pngjs": "^7.0.0"
   }