Screenshot Testing: How to Catch UI Regressions with Baseline Captures

Screenshot testing captures an image of your web UI in a known-good state, saves it as a baseline, and diffs every later build against it. When the new capture differs beyond a set tolerance, the test fails and hands you a visual diff. That is the whole idea, and it catches a class of bug that functional tests sail past: a functional test confirms a button exists in the DOM, but only a screenshot confirms the button is not sitting on top of the headline in white-on-white. This guide covers how the practice works for web apps and CI, the traps that make teams give up on it, and where a hosted render fits. (The same technique exists for native mobile UI via tools like Compose Preview screenshot tests, but the setup and tradeoffs below are the web ones.)

What screenshot testing actually checks

A functional test asserts behavior: the form submits, the count increments, the element is present. All of those can pass while the page looks broken. A screenshot test asserts appearance: it renders the UI, captures a pixel image, and compares that image to a stored baseline.

The loop is three steps:

1. Baseline. Render the UI in a known-good state and save the capture as the reference image. This is the "approved" look.
2. Compare. On the next run, capture a fresh image of the same state and diff it against the baseline, pixel by pixel or structurally.
3. Resolve. If the difference exceeds your tolerance, the test fails and produces a diff. You either fix the regression or, if the change was intentional, accept the new capture as the updated baseline.

Because the output is an image, screenshot testing catches things no assertion would think to check: a font that failed to load, a margin that collapsed, an icon that shifted two pixels, a dark-mode token that leaked into light mode. Those are the "looks done but is broken" bugs, and they are exactly the ones that reach users because every green test said the build was fine.

Screenshot testing vs snapshot testing

These get conflated, so it is worth pinning down. Snapshot testing serializes the rendered DOM or component tree to text and diffs the text. Screenshot testing captures a real rendered image and diffs the pixels.

The distinction matters because they catch different failures. A CSS change that shifts a layout can leave the markup byte-for-byte identical, so a snapshot test passes while the page is visibly broken. A screenshot test sees the shift because it looks at the rendered result, not the source. When people say "the snapshot test passed but the UI is wrong," a screenshot test is the missing layer.

The traps: why teams abandon screenshot suites

The failure mode is not too few bugs caught. It is too many false positives, until the team learns to click "approve" on every diff without looking. Two causes account for most of it.

Non-deterministic content. Anything that changes between runs will fail a pixel diff: the current date, a live feed, a rotating testimonial, a randomized hero image, a CSS animation caught mid-frame. Freeze it. Mock the clock, stub the data, disable animations, and mask regions you genuinely cannot control. A screenshot test is only as good as how deterministic you can make the thing you are capturing.

Environment drift. This is the classic "passes locally, fails in CI." A baseline captured on your Mac will not match a Linux CI runner, because fonts, sub-pixel anti-aliasing, and shadow rendering differ across operating systems. The fix is twofold: generate baselines in the same environment that runs the comparison, and set a small pixel tolerance so anti-aliasing noise does not fail the build. Start strict, loosen only as far as you must, or you will mask the real regressions you built the suite to catch.

Where the tools fit

The mechanism is generic; the tooling wraps it. On the web, the common options are:

• Playwright has it built in via toHaveScreenshot, which auto-waits for the page to settle and stores baselines alongside your tests. See our guide to Playwright visual regression testing for the full setup.
• Percy, Chromatic, and Lost Pixel are hosted services that add baseline storage, a review UI, and cross-browser infrastructure on top of the same capture-and-diff loop.
• Jest snapshots cover the text-serialization side (DOM structure), not the pixel side.

All of them own the diffing, the assertions, and the pass/fail. What they need is a consistent, reproducible capture to feed the comparison.

Where a hosted render fits

A screenshot API does not replace your test runner's diffing. It fits in two narrow, real spots:

• Consistent, environment-independent baselines. Capturing a URL through a hosted browser fleet gives you the same render every time, on the same OS and fonts, so CI drift stops producing phantom diffs. The baseline is stable because the environment is fixed.
• Capturing pages outside the test suite. A live production page, a staging deploy, or a third-party page you do not control is a capture job, not a unit test. You loop those URLs through the API and store the results as reference images.

Here is a baseline capture as a single request:

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "width": 1280,
    "full_page": true,
    "format": "png"
  }'

The response includes a hosted image you can store as the reference:

{
  "id": "grb_01jx...",
  "status": "done",
  "image_url": "https://cdn.grabbit.live/grabs/grb_01jx....png",
  "width": 1280,
  "format": "png",
  "bytes": 96420,
  "execution_ms": 1240
}

width accepts 320 to 1920, height 240 to 1080, full_page captures the whole page, and delay_ms (0 to 10000) lets content settle before the shot so lazy-loaded images and web fonts are in place when the capture fires. To be clear about scope: the API captures the images on a fixed, consistent render. The diffing, the tolerance, and the pass/fail stay in your test tool.

Putting it together

• Screenshot testing catches visual regressions functional tests miss, because it diffs the rendered image, not the DOM.
• Keep captures deterministic (freeze dates, data, and animations) and generate baselines in a consistent environment, or false positives will train your team to ignore the suite.
• Let your test runner own the diff; reach for a hosted render when you need a stable baseline source or need to capture pages that live outside the suite.

For the wider picture, see the practical guide to visual regression testing and the roundup of visual regression testing tools.