How to Use Screenshot APIs for Visual Regression Testing

const fs = require('fs');
const { PNG } = require('pngjs');
const pixelmatch = require('pixelmatch');

const API_KEY = process.env.SCREENSHOT_API_KEY;
const BASE_URL = 'https://screenshotapi-api-production.up.railway.app';

// Pages and viewports to test
const testCases = [
  { name: 'homepage-desktop', url: '/home', width: 1920, height: 1080 },
  { name: 'homepage-mobile', url: '/home', width: 375, height: 812 },
  { name: 'pricing-desktop', url: '/pricing', width: 1920, height: 1080 },
  { name: 'checkout-desktop', url: '/checkout', width: 1920, height: 1080 },
  { name: 'dashboard-desktop', url: '/dashboard', width: 1920, height: 1080 },
];

async function captureScreenshot(pageUrl, width, height) {
  const url = `${process.env.STAGING_URL}${pageUrl}`;
  const params = new URLSearchParams({
    url,
    width: String(width),
    height: String(height),
    format: 'png',
    wait: '2000',
    retries: '2',  // Auto-retry on transient failures
  });

  const res = await fetch(`${BASE_URL}/v1/screenshot?${params}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` },
  });

  if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
  return Buffer.from(await res.arrayBuffer());
}

async function compareImages(baselinePath, currentBuffer) {
  if (!fs.existsSync(baselinePath)) {
    // No baseline -- this is a new page, save and pass
    return { isNew: true, diffPercent: 0 };
  }

  const baseline = PNG.sync.read(fs.readFileSync(baselinePath));
  const current = PNG.sync.read(currentBuffer);

  // Handle size differences
  if (baseline.width !== current.width || baseline.height !== current.height) {
    return { isNew: false, diffPercent: 100, reason: 'size-mismatch' };
  }

  const diff = new PNG({ width: baseline.width, height: baseline.height });
  const mismatchedPixels = pixelmatch(
    baseline.data, current.data, diff.data,
    baseline.width, baseline.height,
    { threshold: 0.1 }
  );

  const totalPixels = baseline.width * baseline.height;
  const diffPercent = (mismatchedPixels / totalPixels) * 100;

  return { isNew: false, diffPercent, mismatchedPixels, diffImage: PNG.sync.write(diff) };
}

async function runVisualTests() {
  const results = [];
  const THRESHOLD = 0.5; // 0.5% pixel difference allowed

  for (const test of testCases) {
    console.log(`Capturing: ${test.name}...`);
    const screenshot = await captureScreenshot(test.url, test.width, test.height);

    const baselinePath = `./baselines/${test.name}.png`;
    const comparison = await compareImages(baselinePath, screenshot);

    const passed = comparison.isNew || comparison.diffPercent <= THRESHOLD;

    results.push({
      name: test.name,
      passed,
      ...comparison,
    });

    // Save current screenshot
    fs.writeFileSync(`./current/${test.name}.png`, screenshot);
    if (comparison.diffImage) {
      fs.writeFileSync(`./diffs/${test.name}-diff.png`, comparison.diffImage);
    }

    console.log(`  ${passed ? 'PASS' : 'FAIL'} - ${comparison.diffPercent.toFixed(2)}% diff`);
  }

  // Summary
  const failed = results.filter(r => !r.passed);
  if (failed.length > 0) {
    console.error(`\n${failed.length} visual regression(s) detected!`);
    process.exit(1);
  } else {
    console.log('\nAll visual tests passed.');
  }
}

runVisualTests();

# .github/workflows/visual-tests.yml
name: Visual Regression Tests

on:
  pull_request:
    branches: [main]

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

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

      - name: Install dependencies
        run: npm ci

      - name: Deploy to preview
        id: deploy
        run: |
          # Your preview deploy command here
          echo "STAGING_URL=https://preview-${{ github.sha }}.yourdomain.com" >> $GITHUB_OUTPUT

      - name: Run visual regression tests
        env:
          SCREENSHOT_API_KEY: ${{ secrets.SCREENSHOT_API_KEY }}
          STAGING_URL: ${{ steps.deploy.outputs.STAGING_URL }}
        run: node visual-tests.js

      - name: Upload diff artifacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: visual-diffs
          path: ./diffs/

// Test with dark mode CSS injection
await captureScreenshot('/home', 1920, 1080, {
  css: 'html { color-scheme: dark; }',
});

// Test with different locales (use JS injection)
await captureScreenshot('/pricing', 1920, 1080, {
  js: 'document.documentElement.lang = "sv";',
});

// Test with slow-loading content fully rendered
await captureScreenshot('/dashboard', 1920, 1080, {
  wait_for_selector: '.chart-container canvas',
  wait: 3000,
});