Visual regression testing for a design system needs a pinned browser

Visual regression testing for a design system is a check that renders every component state, compares each picture with an approved baseline, and fails the pull request when pixels change that nobody meant to change. It catches what code review misses: a padding token edited for one button that moves forty other components, a font weight that drops after a dependency bump, a dark theme that loses a border.
At the end of this guide the library has one. Every story in Storybook is snapshotted on each pull request, in one pinned browser, with thresholds sized to the component. A clean run on an unchanged branch shows zero diffs, and a deliberate change shows exactly the stories it touches.
What you need before you start
- A component library with stories, one story per state worth protecting (variant, size, theme, disabled, error).
- A CI pipeline that runs on every pull request.
- Docker available in CI, or a hosted service that renders for you.
- One named person who approves baseline changes. Without an owner, every diff gets accepted by whoever is in a hurry.
Step 1: Make every state a story
The unit of a visual test is a story. The Storybook documentation says it directly: once visual testing is on, every story is automatically turned into a test. So coverage is decided when stories are written. A button with three variants, three sizes and two themes has 18 states, and a story that renders all 18 in a grid is cheaper to snapshot than 18 stories while still showing every one.
Keep pages out of the first pass. A full page mixes a dozen components with real content, so one diff can mean anything. Component stories fail with a name attached: Button/Primary/Dark changed, and the reviewer knows where to look.
A quick count sets the budget for Step 5. Forty components at an average of six stories each, in two themes, is 480 snapshots per full run.
Step 2: Pin the browser that draws the baseline
This is the step most flaky suites skip. Playwright's visual comparison guide warns that browser rendering varies with the host OS, version, settings, hardware, power source and headless mode, and that consistent screenshots need the same environment that produced the baseline. Font smoothing on macOS and Linux differs enough to fail every text-bearing story.
So the baseline is never generated on a laptop. It is generated in the same container CI uses. Playwright publishes an official image for this, pinned to the release (mcr.microsoft.com/playwright:v1.64.1-noble at the time of writing, per the Docker page). Locally, the update command runs inside that image too:
docker run --rm -v $(pwd):/work -w /work mcr.microsoft.com/playwright:v1.64.1-noble npx playwright test --update-snapshotsPlaywright also names each baseline after browser and platform (chromium-linux), so a Mac baseline and a Linux baseline cannot be confused. Bump the image tag in its own pull request, re-baseline in that same pull request, and nothing else changes in it.
Step 3: Freeze everything that moves
A snapshot has to be identical on two runs of the same code. Anything time-based, random or network-loaded breaks that. Playwright's toHaveScreenshot handles part of it by default, according to its assertion reference:
- Animations are disabled by default. Finite CSS animations and transitions are fast-forwarded to their end, infinite ones are reset to their initial state.
- The text caret is hidden by default.
- The assertion waits for two consecutive identical screenshots before it compares, which absorbs late layout shifts.
The rest is on the stories. Fix the date the component sees. Seed any random data. Serve avatars and images from local files. Wait for document.fonts.ready before the capture, so a fallback font never lands in a baseline. For content that has to stay live, such as a relative timestamp, the mask option paints a solid box over the locator. Use it sparingly: a masked area is an area the test no longer checks.
Step 4: Size the threshold to the component
Two numbers decide when a diff fails. threshold is how different one pixel must be to count, measured in the YIQ colour space from 0 (strict) to 1 (lax), with a default of 0.2. maxDiffPixels or maxDiffPixelRatio is how many counted pixels the test tolerates.
A ratio set once for the whole suite is the common mistake. A 1280 × 800 capture holds 1,024,000 pixels, so a 1% ratio tolerates 10,240 changed pixels. A 120 × 40 button is 4,800 pixels. That suite would let a button disappear from a page and still pass. Component stories cropped to the component keep the arithmetic honest: on a small capture, a low absolute maxDiffPixels (a few dozen pixels for anti-aliasing noise) catches a one-pixel border change and ignores subpixel jitter.
Raise the threshold on a single story only with a comment explaining why, the same way a lint rule is disabled on one line.
Step 5: Choose where the snapshots run
There are two honest options, and the snapshot count from Step 1 decides between them.
Hosted, through Chromatic. Storybook's own team runs it, the review happens in a web interface, and it tests Safari, Firefox and Edge on paid plans. Chromatic's pricing page lists a free plan with 5,000 snapshots a month, Starter at $179 a month for 35,000, and Pro at $399 for 85,000. TurboSnap snapshots only the stories a change affects, and the unaffected ones count at a fraction of a snapshot (the pricing page equates 35,000 billed snapshots with 175,000 turbosnaps, one fifth each). At 480 snapshots per full run, the free plan covers about ten full runs a month; with TurboSnap on, a typical pull request that touches two components costs far less.
Self-hosted, through Playwright. No per-snapshot bill. Baselines are PNG files committed to the repository, the review is Playwright's HTML report, and cross-browser coverage is whatever browsers the config lists. The cost moves to storage in git and to the time someone spends reading reports.
We default to self-hosted Playwright for libraries under a few hundred stories with one owner, and to a hosted service once several teams contribute and need a shared review queue. Neither choice changes Steps 1 to 4.
Step 6: Turn every diff into a decision
A failing visual test asks one question: was this change intended? The answer belongs in the pull request that caused it. If it was intended, the same pull request updates the baseline, and the owner approves the new picture next to the old one. If it was not, the code is fixed and the baseline stays.
Two rules keep the queue clean. Never batch baseline updates into a separate "update snapshots" commit, because that hides which code change moved which picture. And treat a diff in a shared component as a versioning question: a layout that moves for a consumer who upgraded without touching their code can be a breaking change, as we explain in design system versioning.
How to check the suite works
- Run the suite twice on an unchanged main branch. Both runs must report zero diffs. One flaky story here will be ignored forever after.
- Change one token on purpose, for example a radius from 6 to 8 pixels. The stories that use it must fail, and only those.
- Delete a component's border in a test branch. The diff must fail with the component's story name on it.
Common failures and how to fix them
- Every story fails in CI and passes locally. The baseline came from a different OS. Regenerate it inside the pinned container (Step 2).
- Every text story fails after an upgrade. The browser version changed with the test runner. Re-baseline in a pull request that contains only the upgrade.
- The same story fails one run in ten. Something still moves: a web font, a lazy image, an unseeded value. Find it before raising the threshold.
- A real regression passed. Check the mask list and the ratio. A large mask or a page-level ratio hides components (Step 4).
Visual tests are one layer of the drift checks we describe in how design systems decay. They see what changed on screen. They do not see why, which is what the review in Step 6 is for.
Sources
Frequently asked questions
It pays off from the day a second product consumes the library, because from then on one token edit reaches screens nobody on the library team opens. With fewer than 20 components and one consumer, a manual pass over Storybook before each release is often enough. Self-hosted Playwright costs nothing per snapshot, so the only real cost of starting early is writing stories for each state, which the library needs for its documentation anyway.
Chromatic suits teams that want a shared review interface, cross-browser rendering without maintaining it, and TurboSnap to snapshot only what a change affects; its free plan covers 5,000 snapshots a month and Starter costs $179 a month for 35,000. Playwright suits a single owner who prefers no per-snapshot bill and is fine reviewing an HTML report, with baselines stored as PNG files in git. Both depend on the same groundwork: one story per state, frozen data and thresholds sized per component.
No. A screenshot shows what a component looks like in one state; it says nothing about whether a screen reader announces it, whether focus moves correctly, or whether a click handler fires. A button can look identical while losing its accessible name. Run accessibility checks such as axe and interaction tests alongside the visual suite, on the same stories, so each state is covered by all three.
Related articles
September 1, 2026 · 8 min read
November 3, 2026 · 9 min read
June 21, 2026 · 7 min read