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

- name: SnapDrift Baseline
  uses: ranacseruet/snapdrift/actions/[email protected]
  with:
    repo-config-path: .github/snapdrift.json

This captures screenshots of every configured route and uploads them as a GitHub artifact. Every subsequent PR will be compared against this baseline.

Step 3 — Run Drift Detection on Pull Requests

In your PR workflow, add the diff step:

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

- name: SnapDrift Report
  uses: ranacseruet/snapdrift/actions/[email protected]
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    repo-config-path: .github/snapdrift.json

That’s the entire integration. SnapDrift downloads the latest baseline artifact, captures the PR’s state, runs the pixel comparison, and posts a comment on the PR with the results. If you’re using fail-on-changes or strict mode, it’ll also fail the workflow run when drift is detected.

💡 Pro Tip: Security-conscious teams can pin the action to a specific commit SHA instead of the tag. Resolve v0.1.0 to its SHA and use that directly — uses: ranacseruet/snapdrift/actions/baseline@<commit-sha>.

Understanding Drift Modes

SnapDrift ships with four enforcement levels. Pick the one that matches your team’s tolerance for visual changes:

My recommendation: start with report-only for the first week or two. Let baselines accumulate, make sure the routes are stable, and review a few PR reports to calibrate the threshold. Then move to fail-on-changes once you trust the signal. strict is for teams that want zero ambiguity — any anomaly at all blocks the merge.

What SnapDrift Doesn’t Do (On Purpose)

I want to be upfront about current constraints. SnapDrift is deliberately scoped:

• Ubuntu runners only — Playwright Chromium needs Ubuntu’s system dependencies. macOS and Windows runners aren’t supported yet.
• Full-page capture only — no element-level or component-level screenshot targeting. You’re comparing entire pages.
• Fixed viewport presets — desktop (1440×900) and mobile (390×844). Custom viewports aren’t configurable yet.
• One global threshold — the diff.threshold in your config applies to all routes. Per-route thresholds are on the roadmap.
• Dimension shifts are separate — if a page’s height changes (say, a new section was added), that’s flagged differently from pixel-level color drift.

These aren’t accidents — they’re deliberate scope cuts for v0.1.0. The goal was to ship something that solves the 80% case reliably rather than trying to cover every edge case on day one.

Why I Built This

There are paid tools in this space — Percy, Chromatic, Applitools. They’re good products. But they all share the same problem: they’re external services with per-screenshot pricing that adds up fast, especially on active repos with lots of routes. And for open-source projects or small teams, that pricing model just doesn’t work.

I wanted something that runs entirely inside GitHub Actions, stores artifacts using GitHub’s own infrastructure, and costs nothing beyond your existing CI minutes. SnapDrift is that tool. It’s MIT-licensed, open source, and designed to be composed into whatever CI workflow you already have.

What’s Next

SnapDrift is at v0.1.0 — it’s functional and ready for production use, but there’s a lot more I want to build:

• Custom viewport dimensions
• Per-route thresholds
• Component-level capture targeting
• Visual diff image generation (overlay/side-by-side in PR comments)
• Support for non-Ubuntu runners

If you’re dealing with visual regression headaches in your CI pipeline, give SnapDrift a try. The setup takes 10 minutes, and the worst case is you run report-only for a week and decide it’s not for you.

GitHub: github.com/ranacseruet/snapdrift

Star it if you find it useful, and open an issue if something breaks. Contributions are welcome — the Contributing Guide has everything you need to get started. 🚀