{"slug":"uiverify-storybook-visual-testing","name":"storybook-visual-testing","description":"Make Storybook stories deterministic for UI Verify so captures stop coming back \"changed\" without a real change (flaky diffs). Use when setting up story-level visual tests or debugging a story that diffs every run. Focuses only on the run-to-run variation the capturer can't neutralize from outside your app — the clock, infinite JS animations, live data, and non-Math.random randomness — and deliberately skips what UI Verify already handles for you.","long_description":"---\nname: storybook-visual-testing\ndescription: Make Storybook stories deterministic for UI Verify so captures stop coming back \"changed\" without a real change (flaky diffs). Use when setting up story-level visual tests or debugging a story that diffs every run. Focuses only on the run-to-run variation the capturer can't neutralize from outside your app — the clock, infinite JS animations, live data, and non-Math.random randomness — and deliberately skips what UI Verify already handles for you.\n---\n\n# Deterministic Storybook stories\n\n## Mental model — Storybook already removed most of the flake\n\nUI Verify renders each **story** as a baseline. Because a story is an isolated component in a controlled\nharness, you get for free the things that make real-page capture hard: no page scroll, no A/B / analytics\n/ chat / consent scripts, no lazy-load-on-scroll races. That isolation is the point — the determinism\nwork here is **narrow**. If you reach for scroll-settling or third-party stubbing, you're fighting a\nproblem Storybook already removed; that's a real-page concern (see `playwright-visual-testing`).\n\n**UI Verify's capturer also neutralizes these automatically — do NOT hand-fix them:**\n\n- CSS animations & transitions (killed at render), and the Web Animations API (disabled).\n- `prefers-reduced-motion: reduce` — **emulated**, so any component that honors it renders its calm state.\n- `Math.random` — **seeded** before your app code runs (a shuffle/jitter driven by `Math.random` is\n already stable).\n- Web fonts and `![]()
` loading — **waited for** before capture.\n- **Finite** JS animations (a Recharts entry draw, react-smooth) — captured at their settled final frame.\n You don't need to disable these.\n\nSo the checklist below is only the remainder — what lives *inside your app* and can't be fixed from\noutside it. And like Vitest browser mode (`vitest-visual-testing`) and unlike a real page, a story has\n**no SSR** — no server-rendered random pick to reconcile.\n\n**The headline: freeze the data.** Once the list above is off the table, the one thing left that floods a\nstory suite with false \"changes\" is **live/dynamic data** — star counts, follower counts, contributor\nlists, tiles, timestamps. Give every story **static args / fixtures** and that entire class disappears at\nthe source: static data can't churn run-to-run, so there is nothing to diff. This is the single\nhighest-value determinism step here — do it first (step 1), and most stories need nothing else.\n\nPoint UI Verify at your built stories:\n```bash\nnpm run build-storybook && uiverify upload --static-dir storybook-static\n```\n\n## The checklist (only what the tool can't do for you)\n\n### 1. Freeze the data — the one that actually matters\n\nA story fed live/dynamic data is flaky by construction: the stars, followers, contributor list, tile\norder, and timestamps move between runs, so the diff lights up with no code change. **Give every story\nstatic args/fixtures and the whole class is gone.** Never let a story hit a real backend.\n\nConcrete — fixed, ordered, complete data:\n- fixed **counts** (stars, followers, downloads) — literal args, not a live fetch;\n- a fixed **contributor/author list**: fixed names **and** avatar URLs (or inlined avatars), in a fixed\n order;\n- a fixed set of **tiles/rows in a fixed order** (a live \"trending\" sort reorders every run);\n- fixed **timestamps** (pair with the clock, step 2).\n\nTwo ways to inject them, both fine:\n- **args** — the Storybook-native path: pass the component's data as fixed `args` on the story;\n- **mock the fetch** — when a story fetches internally, [MSW via `msw-storybook-addon`](https://storybook.js.org/addons/msw-storybook-addon)\n returns the **same** response every time.\n\n**One component per story file, every variant × state in one story** where you can — cheaper and easier\nto eyeball than N near-identical stories. Keep each in its own file so `--only-changed` carries the\nuntouched ones forward, and add a path filter so the visual job only runs on UI PRs.\n\n### 2. Freeze the clock\n\nThe one thing the capturer deliberately does **not** do (freezing time breaks entry animations). Any\ncomponent that reads the clock — a relative timestamp, a date picker defaulting to \"today\", a chart's day\naxis — drifts every run. Pin it with\n[`storybook-addon-mock-date`](https://www.npmjs.com/package/storybook-addon-mock-date) (Storybook 10+),\nwhich mocks `Date` per story:\n\n```ts\n// .storybook/main.ts\naddons: ['storybook-addon-mock-date'],\n```\n```ts\n// .storybook/preview.ts — a fixed date for every story (meta- or story-level overrides it)\nexport default { parameters: { mockingDate: new Date('2020-01-01T00:00:00Z') } };\n```\n\nPass a `Date`, a millisecond timestamp, or an ISO string as `mockingDate`; the most specific value\n(story > meta > preview) wins, so a single story can pin its own \"today\". On older Storybook, install\n[`@sinonjs/fake-timers`](https://github.com/sinonjs/fake-timers) in a decorator instead\n(`install({ now: FROZEN_NOW })`) — it covers `Date`, `Date.now`, and timers in one call.\n\n### 3. Infinite JS animations\n\nA CSS/WAAPI/finite animation is handled for you (above). What's left is an **infinite** JS loop that\nnever has a final frame — framer-motion pulsing dots, a Lottie loop, an autoplay spinner, or a\n`