Storybook Visual Testing

Deterministic Storybook stories

Mental model — Storybook already removed most of the flake

UI Verify renders each story as a baseline. Because a story is an isolated component in a controlled harness, you get for free the things that make real-page capture hard: no page scroll, no A/B / analytics / chat / consent scripts, no lazy-load-on-scroll races. That isolation is the point — the determinism work here is narrow. If you reach for scroll-settling or third-party stubbing, you're fighting a problem Storybook already removed; that's a real-page concern (see playwright-visual-testing).

UI Verify's capturer also neutralizes these automatically — do NOT hand-fix them:

• CSS animations & transitions (killed at render), and the Web Animations API (disabled).
• prefers-reduced-motion: reduce — emulated, so any component that honors it renders its calm state.
• Math.random — seeded before your app code runs (a shuffle/jitter driven by Math.random is already stable).
• Web fonts and <img> loading — waited for before capture.
• Finite JS animations (a Recharts entry draw, react-smooth) — captured at their settled final frame. You don't need to disable these.

So the checklist below is only the remainder — what lives inside your app and can't be fixed from outside it. And like Vitest browser mode (vitest-visual-testing) and unlike a real page, a story has no SSR — no server-rendered random pick to reconcile.

The headline: freeze the data. Once the list above is off the table, the one thing left that floods a story suite with false "changes" is live/dynamic data — star counts, follower counts, contributor lists, tiles, timestamps. Give every story static args / fixtures and that entire class disappears at the source: static data can't churn run-to-run, so there is nothing to diff. This is the single highest-value determinism step here — do it first (step 1), and most stories need nothing else.

Point UI Verify at your built stories:

npm run build-storybook && uiverify upload --static-dir storybook-static

The checklist (only what the tool can't do for you)

1. Freeze the data — the one that actually matters

A story fed live/dynamic data is flaky by construction: the stars, followers, contributor list, tile order, and timestamps move between runs, so the diff lights up with no code change. Give every story static args/fixtures and the whole class is gone. Never let a story hit a real backend.

Concrete — fixed, ordered, complete data:

• fixed counts (stars, followers, downloads) — literal args, not a live fetch;
• a fixed contributor/author list: fixed names and avatar URLs (or inlined avatars), in a fixed order;
• a fixed set of tiles/rows in a fixed order (a live "trending" sort reorders every run);
• fixed timestamps (pair with the clock, step 2).

Two ways to inject them, both fine:

• args — the Storybook-native path: pass the component's data as fixed args on the story;
• mock the fetch — when a story fetches internally, MSW via msw-storybook-addon returns the same response every time.

One component per story file, every variant × state in one story where you can — cheaper and easier to eyeball than N near-identical stories. Keep each in its own file so --only-changed carries the untouched ones forward, and add a path filter so the visual job only runs on UI PRs.