How to Build a Visual Regression Testing Pipeline

// scripts/capture.mjs
// Usage: node scripts/capture.mjs <url> <output-path>
// Requires: RENDEX_API_KEY env var
import { writeFileSync } from "fs";

const [, , url, outputPath] = process.argv;
if (!url || !outputPath) {
  console.error("Usage: node capture.mjs <url> <output>");
  process.exit(1);
}

const API_KEY = process.env.RENDEX_API_KEY;
if (!API_KEY) {
  console.error("RENDEX_API_KEY is not set — get one at https://rendex.dev/login");
  process.exit(1);
}

const res = await fetch("https://api.rendex.dev/v1/screenshot", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url,
    format: "png",
    width: 1280,
    height: 800,
    fullPage: true,
    waitUntil: "networkidle2",
    deviceScaleFactor: 1, // keep 1x for diff accuracy
    blockAds: true,
  }),
});

if (!res.ok) {
  const text = await res.text();
  console.error(`Capture failed (${res.status}): ${text}`);
  process.exit(1);
}

const buffer = Buffer.from(await res.arrayBuffer());
writeFileSync(outputPath, buffer);
console.log(`Saved ${buffer.length} bytes → ${outputPath}`);

npm install pixelmatch pngjs

// scripts/diff.mjs
// Usage: node scripts/diff.mjs <before.png> <after.png> <diff.png>
// Exits with code 1 if pixel mismatch exceeds threshold
import { readFileSync, writeFileSync } from "fs";
import { PNG } from "pngjs";
import pixelmatch from "pixelmatch";

const [, , beforePath, afterPath, diffPath] = process.argv;

const THRESHOLD = 0.1;       // 0.0–1.0 per-pixel color threshold
const MAX_DIFF_RATIO = 0.02; // fail if >2% of pixels differ

function loadPng(path) {
  return PNG.sync.read(readFileSync(path));
}

const before = loadPng(beforePath);
const after = loadPng(afterPath);

// Resize if dimensions differ (preview deploy may have different height)
const width = Math.min(before.width, after.width);
const height = Math.min(before.height, after.height);

const diff = new PNG({ width, height });
const mismatch = pixelmatch(
  before.data,
  after.data,
  diff.data,
  width,
  height,
  { threshold: THRESHOLD, includeAA: false },
);

const totalPixels = width * height;
const ratio = mismatch / totalPixels;
writeFileSync(diffPath, PNG.sync.write(diff));

console.log(
  `Mismatch: ${mismatch} / ${totalPixels} pixels (${(ratio * 100).toFixed(2)}%)`,
);

if (ratio > MAX_DIFF_RATIO) {
  console.error(
    `FAIL: ${(ratio * 100).toFixed(2)}% exceeds threshold ${MAX_DIFF_RATIO * 100}%`,
  );
  process.exit(1);
}

console.log("PASS: diff within threshold");

name: Visual Regression

on:
  pull_request:
    branches: [main]

jobs:
  visual-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install diff dependencies
        run: npm install pixelmatch pngjs

      - name: Wait for preview deploy
        id: preview
        # Replace this with your preview URL resolver.
        # Vercel sets VERCEL_PREVIEW_URL in PR environments.
        # For Netlify, parse the deploy-preview URL from PR comments.
        run: |
          # Example: hard-code preview URL pattern for Vercel
          PREVIEW_URL="https://${{ github.event.repository.name }}-git-${{ github.head_ref }}-${{ github.repository_owner }}.vercel.app"
          echo "url=${PREVIEW_URL}" >> "$GITHUB_OUTPUT"

      - name: Capture production screenshot
        env:
          RENDEX_API_KEY: ${{ secrets.RENDEX_API_KEY }}
        run: |
          node scripts/capture.mjs https://yoursite.com before.png

      - name: Capture preview screenshot
        env:
          RENDEX_API_KEY: ${{ secrets.RENDEX_API_KEY }}
        run: |
          node scripts/capture.mjs ${{ steps.preview.outputs.url }} after.png

      - name: Diff images
        run: node scripts/diff.mjs before.png after.png diff.png

      - name: Upload screenshots as artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: visual-regression-${{ github.sha }}
          path: |
            before.png
            after.png
            diff.png

// scripts/batch-capture.mjs
// Captures multiple pages in one batch request and polls until complete.
import { writeFileSync } from "fs";

const PAGES = [
  { url: process.env.BASE_URL + "/", name: "home" },
  { url: process.env.BASE_URL + "/pricing", name: "pricing" },
  { url: process.env.BASE_URL + "/docs", name: "docs" },
];

const API_KEY = process.env.RENDEX_API_KEY;
const captureDefaults = {
  format: "png",
  width: 1280,
  height: 800,
  fullPage: true,
  waitUntil: "networkidle2",
  deviceScaleFactor: 1,
};

// Submit batch
const batchRes = await fetch("https://api.rendex.dev/v1/screenshot/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: PAGES.map((p) => ({ url: p.url })),
    defaults: captureDefaults,
  }),
});

const { batchId } = await batchRes.json();
console.log("Batch submitted:", batchId);

// Poll until complete
let batch;
do {
  await new Promise((r) => setTimeout(r, 3000));
  const statusRes = await fetch(
    `https://api.rendex.dev/v1/batches/${batchId}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } },
  );
  batch = await statusRes.json();
  console.log(`Status: ${batch.status} (${batch.completedJobs}/${batch.totalJobs})`);
} while (batch.status !== "completed" && batch.status !== "failed");

// Download images
for (let i = 0; i < batch.jobs.length; i++) {
  const job = batch.jobs[i];
  if (job.status !== "completed") continue;
  const imgRes = await fetch(job.imageUrl);
  const buf = Buffer.from(await imgRes.arrayBuffer());
  writeFileSync(`${PAGES[i].name}.png`, buf);
  console.log(`Saved ${PAGES[i].name}.png`);
}