SnapDrift: Free Auto Visual Regression Testing On GitHub Actions

If your CI pipeline doesn’t catch visual regressions, you’re shipping UI bugs with your eyes closed. I’ve lost count of how many times a “safe” CSS refactor nuked a hero section on mobile, and nobody noticed until a customer screenshot landed in Slack. Unit tests don’t catch layout drift. Integration tests don’t catch it either. You need pixel-level proof that what shipped still looks right.

That’s exactly why I built SnapDrift — an free and open-source visual regression tool that captures full-page screenshots, compares them against a known baseline, and reports drift directly inside your GitHub pull requests. No external services, no SaaS dashboards, no vendor lock-in. Just two GitHub Actions and a JSON config.

In this post, I’ll walk you through what SnapDrift does, why it exists, and how to integrate it into your project in under 10 minutes.

The Problem: UX Changes Are Invisible Until They’re Not

Here’s the scenario every frontend developer knows too well. You update a shared utility class, maybe tweak some padding or swap a font weight. Your unit tests pass. Your integration tests pass. You merge the PR with confidence. Then three days later someone notices the checkout button is overlapping the footer on mobile.

Visual bugs are uniquely painful because they’re almost impossible to catch in code review. A reviewer staring at a diff of padding: 12px → 16px has no way of knowing that change causes a layout break on a different page. What you need is automated, pixel-level diffing — and that’s where SnapDrift comes in.

What Is SnapDrift?

SnapDrift is a set of composable GitHub Actions that handle visual regression testing inside your existing CI workflows. You own the checkout, build, and startup. SnapDrift takes over once your app is reachable.

Here’s what it handles end to end:

• Baseline capture on main — every push to your default branch saves a fresh set of full-page screenshots as a GitHub artifact.
• Pull request drift detection — on every PR, SnapDrift captures the same routes, downloads the latest baseline, and runs a pixel-level comparison.
• Route scoping from changed files — if you’ve configured file-to-route mappings, SnapDrift only captures the routes affected by the PR’s changeset. Fewer screenshots, faster runs.
• PR report upserts — SnapDrift posts (and updates) a comment on the PR with comparison results, including which routes drifted and by how much.
• Drift enforcement — configurable modes from report-only (just inform) to strict (fail the build on any visual change).

The entire thing runs on GitHub-hosted Ubuntu runners using Playwright Chromium under the hood. No Docker images to manage, no external screenshot services.

💡 Pro Tip: Start with report-only mode while your baselines stabilize. Once you trust the signal, switch to fail-on-changes or strict to make visual regressions a hard gate.

Quickstart: Full Integration in 3 Steps

The setup is intentionally minimal. One config file, two workflow steps.

Step 1 — Add the Config File

Create .github/snapdrift.json in your repository root:

{
  "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" }
}

{
  "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" }
}

A few things to note here. The baseUrl is wherever your app starts during CI — if you’re using Next.js on port 3000, change it to http://127.0.0.1:3000. The routes array defines what SnapDrift captures: each route gets an id, a URL path, and a viewport preset (desktop at 1440×900 or mobile at 390×844). And diff.threshold controls sensitivity — 0.01 means even 1% pixel drift gets flagged.

Step 2 — Capture Baselines on Push to main

In your main branch CI workflow (e.g., .github/workflows/ci.yml), add the baseline step after your app is built and running:

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