SnapDrift — free visual regression
testing for GitHub Actions

What SnapDrift is

SnapDrift is a free, MIT-licensed visual regression testing runner for GitHub Actions. It captures full-page frames of your application, compares them against a known baseline, and reports drift directly on the pull request. It is the open-source client behind Snap's hosted Visual CI, and it runs the same comparison engine as the free in-browser visual diff tool.

You keep ownership of checkout, build, startup, readiness, and teardown. SnapDrift takes over once your app is reachable — so it fits the CI you already have instead of asking you to reorganize it.

How it works

Every pull request runs the same loop, driven by two workflow jobs and a single config file:

Quickstart

Two files get you from zero to a reviewed visual run. First, add .github/snapdrift.json:

{
  "baselineArtifactName": "my-app-snapdrift-baseline",
  "workingDirectory": ".",
  "baseUrl": "http://127.0.0.1:8080",
  "resultsFile": "qa-artifacts/snapdrift/baseline/current/results.json",
  "manifestFile": "qa-artifacts/snapdrift/baseline/current/manifest.json",
  "screenshotsRoot": "qa-artifacts/snapdrift/baseline/current",
  "routes": [
    { "id": "home-desktop", "path": "/", "viewport": "desktop" },
    { "id": "home-mobile",  "path": "/", "viewport": "mobile"  }
  ],
  "diff": { "threshold": 0.01, "mode": "report-only" }
}

Then wire up the two jobs — one publishes the baseline from main, the other runs on every pull request. Both are pinned to the immutable SnapDrift v0.13.0 release commit:

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

# pr-diff posts its report as a PR comment, so the token needs write access
# to issues and pull requests.
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
      # ... check out, build and start your app ...
      - name: SnapDrift Baseline
        uses: ranacseruet/snapdrift/actions/baseline@3967590687d420479ba5ec351e1394de174c1838 # v0.13.0
        with:
          repo-config-path: .github/snapdrift.json

  pr-diff:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # ... check out, build and start your app ...
      - name: SnapDrift Report
        uses: ranacseruet/snapdrift/actions/pr-diff@3967590687d420479ba5ec351e1394de174c1838 # v0.13.0
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          repo-config-path: .github/snapdrift.json

The full walkthrough — permissions, route scoping, and the hosted provider — is in the Visual CI guide.

Enforcement modes

Set diff.mode to control what a drifting run does. Start permissive and tighten once the signal is stable:

What it handles

Local CLI

SnapDrift also ships a CLI for running captures, diffs, and migrations locally against a running app — useful for validating a change before you push:

# Establish a local-provider baseline
snapdrift baseline

# Capture screenshots without publishing anything
snapdrift capture

# Compare against the baseline after making UI changes
snapdrift diff --open

# Export hosted baselines back to the local layout
snapdrift migrate-baselines --to local --from snap

Current constraints

• Ubuntu runners for the actions; the local CLI runs on any OS Node 22+ supports.
• Full-page capture only.
• Viewport presets desktop (1440×900) and mobile (390×844), or a custom { width, height }.
• One global diff.threshold.
• Unequal dimensions compare on a top-left-aligned union canvas, so a size change still produces a reviewable diff instead of failing outright.

Free forever, or scale without the runner

SnapDrift is free because it runs on your infrastructure. When running Playwright inside CI starts to cost more than it is worth, Snap's hosted provider is a drop-in upgrade: change provider to "snap" and Snap renders your preview deploy on its Lambda fleet, keeps baselines in S3 that don't expire, and adds a review dashboard — the same routes, the same diff config, no workflow rewrite.

Try the engine for free first. The in-browser visual diff tool uses the same comparison engine as SnapDrift — drop in two images and see exactly what a run reports. Need raw captures instead of diffs? The free screenshot API captures any public URL with no signup.

Frequently asked questions