What is visual regression testing?
Visual regression testing compares screenshots of a user interface against previously approved baseline images to catch unintended visual changes. It finds bugs that code tests miss, like a shifted button, overflowing text or a broken mobile layout.
How it works
The method has four steps, repeated with every change.
- Baseline: take screenshots of pages in their approved state.
- Compare: after a change, capture the same pages at the same sizes and compare them pixel by pixel.
- Threshold: set a limit on the share of changed pixels so tiny differences don’t count as failures.
- Approve: if the change is intended, the new image becomes the baseline; if not, fix the bug.
Why you need it
Unit tests tell you a function returns the right value, not that the page looks right. A CSS change can break the layout on a page nobody touched. These side effects are more common when coding agents change the UI, because the agent usually works without seeing the screen.
Reducing false positives
A noisy test soon gets ignored, so a stable setup matters.
- Turn off animations and transitions.
- Freeze changing data such as dates, times and random content.
- Wait for fonts to load, and always capture on the same browser and operating system.
- Test at several sizes, such as mobile, tablet and desktop.
Tools
Common choices include Playwright’s toHaveScreenshot assertion, open-source tools such as BackstopJS, and hosted services such as Percy or Chromatic. They all rest on the same idea: a baseline image, a new image and a diff image that highlights what changed.
Visual comparison in AgentVera
AgentVera’s Preview tab runs visual comparisons against the dev server of the project and of each worktree.
- Full-page screenshots of the pages you choose are taken at Mobile (375×812), Tablet (768×1024) and Desktop (1440×900); up to 6 sizes can be set.
- You set a baseline; later shots are compared pixel by pixel and changed pixels are marked in red. The default threshold is 0.1% of pixels.
- The test-with-agent button opens a Claude agent in that worktree with the AgentVera browser; it opens every page at each breakpoint and looks for overflow, broken layout, console errors and dead links.
FAQ
Is visual regression testing the same as snapshot testing?
Similar idea, different target. Snapshot tests usually compare a component’s HTML or text output; visual regression tests compare actual screenshots.
Why do pixel comparisons give false failures?
Font rendering, anti-aliasing, animations and changing content can shift a few pixels. A threshold and a stable environment cut that noise.
Which pages should I test?
Start with the most used and most fragile ones: the home page, sign-in, checkout or form flows. Capture each at several screen sizes.