Visual regression testing with a screenshot API.

A visual regression workflow.

1. Your codeBaselineApproved captures, committed with your code
2. Your codeDeployA preview or staging build
3. urlshot.ioNew captureSame pages, same options
4. Your codeImage diffpixelmatch in your CI job
5. Your codePass or failFail the build, attach the diff

Run it in CI.

The script below takes screenshots of 3 pages at 2 widths on the deployment you name, and compares each one with its baseline. Here it is in 4 parts, one step at a time. The whole file is at the end, to copy in one go.

1. 1. Settings

   The deployment to check, read from PREVIEW_URL; the pages and widths to compare; and CSS that stops animations, so that two screenshots of an unchanged page match exactly.

   visual-check.mjs, part 1 of 4

   // visual-check.mjs: compare a preview deployment with approved screenshots.
   // npm install pixelmatch pngjs
   import { existsSync } from 'node:fs';
   import { mkdir, readFile, writeFile } from 'node:fs/promises';
   import pixelmatch from 'pixelmatch';
   import { PNG } from 'pngjs';
   
   const site = process.env.PREVIEW_URL; // the deployment to check
   const pages = ['/', '/pricing', '/signup'];
   const widths = [1440, 390]; // desktop and phone
   
   // Stops animations and the blinking text cursor, so that two screenshots
   // of an unchanged page are exactly the same.
   const freeze = `*, *::before, *::after {
     animation: none !important;
     transition: none !important;
     caret-color: transparent !important;
   }`;

2. 2. Take a screenshot

   One request for each page and width. The options are sent as a JSON body, so the CSS needs no URL encoding. If a screenshot fails, the run stops with the error code and the request id.

   visual-check.mjs, part 2 of 4

   // Takes a full-page PNG of the url at the given width.
   async function capture(url, width) {
     const response = await fetch('https://api.urlshot.io/v1/screenshot', {
       method: 'POST',
       headers: {
         Authorization: `Bearer ${process.env.URLSHOT_API_KEY}`,
         'Content-Type': 'application/json',
       },
       body: JSON.stringify({
         url,
         viewport_width: width,
         full_page: true,
         format: 'png',
         wait_until: 'networkidle0',
         custom_css: freeze,
       }),
     });
   
     if (!response.ok) {
       const { error } = await response.json();
       throw new Error(`${url}: ${error.code} (request ${error.requestId})`);
     }
     return Buffer.from(await response.arrayBuffer());
   }

3. 3. Compare it with the baseline

   pixelmatch counts the pixels that differ, and draws them in red in a third image, saved in diffs/. Two images of different sizes can’t be compared pixel by pixel, so a page that got taller or shorter is reported as a change on its own.

   visual-check.mjs, part 3 of 4

   // Compares a screenshot with its baseline. Returns what changed, or null if
   // nothing did, and saves the changes as an image.
   async function compare(baselineFile, screenshot, diffFile) {
     const before = PNG.sync.read(await readFile(baselineFile));
     const after = PNG.sync.read(screenshot);
   
     // Images of different sizes can't be compared pixel by pixel; keep the new one.
     if (before.width !== after.width || before.height !== after.height) {
       await writeFile(diffFile, screenshot);
       return `size changed from ${before.width}×${before.height} to ${after.width}×${after.height}`;
     }
   
     // Count the pixels that differ, and draw them in red in a third image.
     const diff = new PNG({ width: after.width, height: after.height });
     const changed = pixelmatch(before.data, after.data, diff.data, after.width, after.height, {
       threshold: 0.1, // how different one pixel must be to count, from 0 to 1
     });
     if (changed === 0) return null;
   
     await writeFile(diffFile, PNG.sync.write(diff));
     return `${changed} pixels changed`;
   }

4. 4. Check every page

   The first run has nothing to compare with, so it saves each screenshot in baselines/. Every later run compares, and exits with code 1 if anything changed, which fails the CI job. To approve an intended change, delete that page’s baseline and run the script again.

   visual-check.mjs, part 4 of 4

   // Check every page at every width. The first run saves the baselines.
   await mkdir('baselines', { recursive: true });
   await mkdir('diffs', { recursive: true });
   let failed = false;
   
   for (const page of pages) {
     for (const width of widths) {
       const name = `${page === '/' ? 'home' : page.slice(1)}-${width}.png`; // e.g. pricing-1440.png
       const screenshot = await capture(new URL(page, site).href, width);
   
       if (!existsSync(`baselines/${name}`)) {
         await writeFile(`baselines/${name}`, screenshot);
         console.log(`${name}: saved as the baseline`);
         continue;
       }
   
       const change = await compare(`baselines/${name}`, screenshot, `diffs/${name}`);
       if (change) {
         console.error(`${name}: ${change}, see diffs/${name}`);
         failed = true;
       } else {
         console.log(`${name}: unchanged`);
       }
     }
   }
   
   process.exitCode = failed ? 1 : 0;

// visual-check.mjs: compare a preview deployment with approved screenshots.
// npm install pixelmatch pngjs
import { existsSync } from 'node:fs';
import { mkdir, readFile, writeFile } from 'node:fs/promises';
import pixelmatch from 'pixelmatch';
import { PNG } from 'pngjs';

const site = process.env.PREVIEW_URL; // the deployment to check
const pages = ['/', '/pricing', '/signup'];
const widths = [1440, 390]; // desktop and phone

// Stops animations and the blinking text cursor, so that two screenshots
// of an unchanged page are exactly the same.
const freeze = `*, *::before, *::after {
  animation: none !important;
  transition: none !important;
  caret-color: transparent !important;
}`;

// Takes a full-page PNG of the url at the given width.
async function capture(url, width) {
  const response = await fetch('https://api.urlshot.io/v1/screenshot', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.URLSHOT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url,
      viewport_width: width,
      full_page: true,
      format: 'png',
      wait_until: 'networkidle0',
      custom_css: freeze,
    }),
  });

  if (!response.ok) {
    const { error } = await response.json();
    throw new Error(`${url}: ${error.code} (request ${error.requestId})`);
  }
  return Buffer.from(await response.arrayBuffer());
}

// Compares a screenshot with its baseline. Returns what changed, or null if
// nothing did, and saves the changes as an image.
async function compare(baselineFile, screenshot, diffFile) {
  const before = PNG.sync.read(await readFile(baselineFile));
  const after = PNG.sync.read(screenshot);

  // Images of different sizes can't be compared pixel by pixel; keep the new one.
  if (before.width !== after.width || before.height !== after.height) {
    await writeFile(diffFile, screenshot);
    return `size changed from ${before.width}×${before.height} to ${after.width}×${after.height}`;
  }

  // Count the pixels that differ, and draw them in red in a third image.
  const diff = new PNG({ width: after.width, height: after.height });
  const changed = pixelmatch(before.data, after.data, diff.data, after.width, after.height, {
    threshold: 0.1, // how different one pixel must be to count, from 0 to 1
  });
  if (changed === 0) return null;

  await writeFile(diffFile, PNG.sync.write(diff));
  return `${changed} pixels changed`;
}

// Check every page at every width. The first run saves the baselines.
await mkdir('baselines', { recursive: true });
await mkdir('diffs', { recursive: true });
let failed = false;

for (const page of pages) {
  for (const width of widths) {
    const name = `${page === '/' ? 'home' : page.slice(1)}-${width}.png`; // e.g. pricing-1440.png
    const screenshot = await capture(new URL(page, site).href, width);

    if (!existsSync(`baselines/${name}`)) {
      await writeFile(`baselines/${name}`, screenshot);
      console.log(`${name}: saved as the baseline`);
      continue;
    }

    const change = await compare(`baselines/${name}`, screenshot, `diffs/${name}`);
    if (change) {
      console.error(`${name}: ${change}, see diffs/${name}`);
      failed = true;
    } else {
      console.log(`${name}: unchanged`);
    }
  }
}

process.exitCode = failed ? 1 : 0;

• Baselines live in the repository, in baselines/, so an approved change and its new screenshots are reviewed in the same pull request as the code.
• The deployment must be public. The renderer cannot reach localhost or your CI runner’s network: point it at a preview or staging URL.
• One screenshot at a time, which stays within every plan’s limit on parallel renders. This run takes 6 screenshots, so it costs 6 credits.
• The capture step, not a test framework. urlshot.io takes the screenshots. Keeping baselines, comparing and approving happen in the script and your repository.

In a GitHub Actions workflow

Run it after the job that deploys the pull request’s preview, and keep the diffs when it fails:

# A job in the workflow that deploys your pull request's preview.
  visual-check:
    needs: deploy-preview
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4 # the repository, with baselines/ committed
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install pixelmatch pngjs
      - run: node visual-check.mjs
        env:
          # However your deploy job publishes the preview's address.
          PREVIEW_URL: ${{ needs.deploy-preview.outputs.url }}
          URLSHOT_API_KEY: ${{ secrets.URLSHOT_API_KEY }}
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: visual-diffs
          path: diffs/

Related use cases.

• Website monitoring

  Capture the same pages on a schedule and keep every image, so you can see when a page changed and what it looked like before.

  Explore website monitoring

• AI agents

  Give a vision model the page as a browser renders it: layout, charts and dialogs that extracted text leaves out.

  Explore screenshots for AI agents

Or see every use case, or the same requests in your own language in the code examples.