Visual regression in your CI pipeline

Overview

snapdrift is a free, open-source visual-regression runner for GitHub Actions: a config file and two workflow jobs capture each route on a PR, diff it against a baseline, and post the result as a PR comment. Snap is the hosted upgrade — the same workflow, but rendering moves off your CI runner, baselines live in durable storage, and you get a triage dashboard.

How it works

Every pull request runs the same four-step loop:

Start free — snapdrift local mode

No Snap account needed. snapdrift starts Playwright inside your GitHub Actions runner, captures each configured route against your running app, and diffs the result against a stored baseline. Baselines live as workflow artifacts — free for open-source and small teams.

Step 1 — Add a config file

Create .github/snapdrift.json in your repo. baseUrl is the address of your app once it's started in the CI runner:

{
  "baselineArtifactName": "my-app-snapdrift-baseline",
  "baseUrl": "http://127.0.0.1:3000",
  "routes": [
    { "id": "home-desktop", "path": "/",         "viewport": "desktop" },
    { "id": "home-mobile",  "path": "/",         "viewport": "mobile"  },
    { "id": "dashboard",    "path": "/dashboard","viewport": "desktop" }
  ],
  "diff": { "threshold": 0.01, "mode": "report-only" }
}

Step 2 — Add two workflow jobs

One job publishes a baseline when you merge to main. The other runs the diff on every pull request. You own app startup — snapdrift takes over once the app is reachable.

name: Visual Regression
on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read
  actions: read
  issues: write
  pull-requests: write

jobs:
  baseline:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: npm
      - run: npm ci && npm run build

      - name: Start app
        run: |
          npm start &
          for i in $(seq 1 45); do
            curl -sf http://127.0.0.1:3000 && break || sleep 1
          done

      - name: SnapDrift Baseline
        uses: ranacseruet/snapdrift/actions/baseline@v0.2.1
        with:
          repo-config-path: .github/snapdrift.json

  pr-diff:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: npm
      - run: npm ci && npm run build

      - name: Start app
        run: |
          npm start &
          for i in $(seq 1 45); do
            curl -sf http://127.0.0.1:3000 && break || sleep 1
          done

      - name: SnapDrift Report
        uses: ranacseruet/snapdrift/actions/pr-diff@v0.2.1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          repo-config-path: .github/snapdrift.json

snapdrift installs Playwright, captures each route against your running app, diffs against the latest baseline artifact, and posts results to the PR.

Drift enforcement modes

Set diff.mode in your config to control what happens when drift is detected:

Upgrade to Snap

When GH artifact retention (~90 days) becomes a problem, rendering inside the CI runner is too slow, or you want a triage dashboard — Snap is the upgrade. snapdrift's provider: "snap" integration is in active development; once available, switching will require one config change and a Snap API key.

Snap is designed as a drop-in backend for snapdrift. When provider: snap is set, snapdrift hands off rendering to Snap's Lambda fleet — your app no longer needs to run in the CI runner, baselines move to S3 with durable retention, and you get access to the triage dashboard. The same routes, the same diff modes, the same PR comment shape.

What you get with Snap

In the meantime, you can already call Snap's screenshot API directly from CI via POST /v1/screenshots for single-shot captures. See the API reference.

snapdrift vs Snap