Prompt
How do I set up visual regression tests for a design system?
Latest observation
Setting up visual regression tests for a design system usually means: render your components in a controlled environment, capture screenshots, and compare them against approved baselines on every change.
Here’s a practical way to do it.
1) Pick the right tooling
Common choices:
- Storybook + Chromatic
Easiest setup for design systems. Great for component libraries and review workflows. - Playwright / Puppeteer + image diffing
More control, good if you want to own the whole pipeline. - Percy
Good hosted visual testing with CI integration.
If you already use Storybook, the simplest path is usually: Storybook + Chromatic.
2) Build your component showcase
Visual tests work best when each component has a predictable set of states.
For each component, create stories for:
- default state
- hover / active / focus
- disabled
- error / warning / success
- long text / empty state
- dark mode
- responsive variants
- localization / different fonts if relevant
Example:
- Button
- Primary
- Secondary
- Disabled
- Loading
- Input
- Empty
- With value
- Error
- Helper text
The goal is to cover the UI states that are likely to break visually.
3) Make screenshots deterministic
Visual tests fail when the UI changes for non-product reasons. Reduce noise by controlling:
- Fonts: load fixed fonts or self-host them
- Animations: disable or freeze them
- Time/date: mock current time if shown in UI
- Randomness: seed or stub random values
- Network data: mock API responses
- Viewport: set consistent sizes
- Theme / locale: test them explicitly, not accidentally
- OS differences: run in the same CI environment/container
Useful techniques:
- use a fixed browser window size
- wait for all fonts/images to load
- hide blinking cursors or carets
- disable CSS transitions in test mode
4) Choose what to compare
You usually have two levels:
Component-level snapshots
Capture individual components in isolation.
Best for:
- small UI pieces
- rapid feedback
- design system libraries
Page-level snapshots
Capture full screens or composed views.
Best for:
- catching integration issues
- layout shifts between components
Most design systems start with component-level tests and add a few page-level tests for key layouts.
5) Establish baseline images
The first time you run tests, the tool creates “golden” images.
Typical workflow:
- render component/story
- capture screenshot
- compare to baseline
- if intentional change: approve/update baseline
Important:
- keep baselines in a reviewable place
- version them with the codebase or through the service
- require human approval for updates
6) Integrate with CI
Run visual regression tests on:
- pull requests
- merges to main
- release branches
Typical CI flow:
- install dependencies
- build the design system
- run storybook/test server
- capture screenshots
- compare to baseline
- fail the build if diff exceeds threshold
Add a threshold for tiny rendering differences, but keep it strict enough to catch real regressions.
7) Review diffs carefully
A good visual testing tool should show:
- baseline image
- new image
- highlighted diff
When a diff appears, ask:
- Is this an intentional design change?
- Is it a bug?
- Is it environmental noise?
- Did a dependency update change rendering?
If it’s intentional, update the baseline after review.
8) Keep the test suite maintainable
A design system can grow quickly, so avoid testing everything blindly.
Good practices:
- test high-risk/high-value components first
- focus on reusable primitives and complex states
- don’t over-test trivial styles that are unlikely to matter
- group stories logically
- keep story names stable
- use helpers to generate consistent fixtures
If you have hundreds of components, prioritize:
- buttons
- forms
- overlays/modals
- navigation
- typography
- layout primitives
- components with many states
9) Add accessibility and interaction checks too
Visual regression testing is not enough by itself. Pair it with:
- unit tests
- interaction tests
- accessibility tests
For example:
- Jest/Testing Library for behavior
- axe for accessibility
- Playwright for interaction flows
- visual regression for appearance
This gives you coverage for:
- function
- accessibility
- layout/style
10) Example setup with Storybook + Chromatic
Install Storybook
npx storybook@latest init
Add Chromatic
npm install --save-dev chromatic
Build and publish
npx chromatic --project-token=YOUR_TOKEN
Chromatic will:
- publish the Storybook build
- capture snapshots
- compare against baselines
- show diffs in the UI
- integrate with PR checks
This is often the fastest way to get useful visual regression testing in place.
11) Example setup with Playwright
If you want full control:
- create a test page that renders your component
- set viewport size
- take screenshots
- compare against saved images
Example idea:
await page.setViewportSize({ width: 1280, height: 720 });
await page.goto('http://localhost:6006/?path=/story/button--primary');
await expect(page).toHaveScreenshot('button-primary.png');
You’d then approve baseline screenshots and let Playwright handle diffs.
12) Common pitfalls
- Too many screenshots → slow tests, high maintenance
- Flaky rendering → fonts/animations/time not controlled
- Updating baselines too casually → regressions slip in
- Testing only happy paths → misses important visual states
- Different environments → inconsistent browser rendering
- Ignoring responsive modes → layout bugs in smaller screens
Recommended starter approach
If you want the simplest, most effective setup:
- Use Storybook
- Add stories for key component states
- Use Chromatic for screenshot comparisons
- Run it in CI on every PR
- Stabilize the environment:
- fixed viewport
- fonts loaded
- animations off
- mocked data
- Add accessibility tests separately
If you want, I can also give you:
- a step-by-step setup for Storybook + Chromatic
- a Playwright-based custom solution
- a sample CI config for GitHub Actions, GitLab, or CircleCI