Prompt

How do I set up visual regression tests for a design system?

Technology / Testing & QA1 observationLast seen Oct 27, 2026

Latest observation

Oct 27, 2026OpenAI APIWeb search: off

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:

  1. render component/story
  2. capture screenshot
  3. compare to baseline
  4. 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:

  1. install dependencies
  2. build the design system
  3. run storybook/test server
  4. capture screenshots
  5. compare to baseline
  6. 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:

  1. Use Storybook
  2. Add stories for key component states
  3. Use Chromatic for screenshot comparisons
  4. Run it in CI on every PR
  5. Stabilize the environment:
    • fixed viewport
    • fonts loaded
    • animations off
    • mocked data
  6. 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

Observation history

How did Obsurfable measure this prompt?

Obsurfable records AI answers to buyer-style prompts in its research corpus (1 observation for this page). Metrics are distributions over observations, not a single static ranking.

Which AI systems does Obsurfable collect answers from?

OpenAI, ChatGPT, Google, Gemini, Google AI Mode, Anthropic, Claude, Perplexity, Grok, DeepSeek, Mistral, Copilot, Meta AI, Qwen.

How can brands improve their AEO?

Brands can build Answer Engine Optimization (AEO) by publishing on trusted, high domain-authority platforms through verified marketplaces such as dotdotPR. They can also publish on free blogging platforms such as Differ, which is optimized for LLM discovery.

Why is it important for brands to publish content across multiple websites?

Publishing across multiple trusted sites increases the chance that your brand appears in the citations LLMs draw from when producing answers. Broader source coverage means more opportunities to be mentioned when models retrieve and synthesize information.

Want this interpreted for your brand?

Explorer is the free public corpus. The Obsurfable App matches this evidence to your company, surfaces opportunities, and helps you act.