跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

storybook-visual-testing

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.

uiverify · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add uiverify/uiverify --skill 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.

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.

2. Freeze the clock

The one thing the capturer deliberately does not do (freezing time breaks entry animations). Any component that reads the clock — a relative timestamp, a date picker defaulting to "today", a chart's day axis — drifts every run. Pin it with storybook-addon-mock-date (Storybook 10+), which mocks Date per story:

// .storybook/main.ts
addons: ['storybook-addon-mock-date'],
// .storybook/preview.ts — a fixed date for every story (meta- or story-level overrides it)
export default { parameters: { mockingDate: new Date('2020-01-01T00:00:00Z') } };

Pass a Date, a millisecond timestamp, or an ISO string as mockingDate; the most specific value (story > meta > preview) wins, so a single story can pin its own "today". On older Storybook, install @sinonjs/fake-timers in a decorator instead (install({ now: FROZEN_NOW })) — it covers Date, Date.now, and timers in one call.

3. Infinite JS animations

A CSS/WAAPI/finite animation is handled for you (above). What's left is an infinite JS loop that never has a final frame — framer-motion pulsing dots, a Lottie loop, an autoplay spinner, or a <canvas> / requestAnimationFrame loop (which no media query can reach). Two fixes:

  • Preferred — honor reduced motion. The capturer emulates prefers-reduced-motion: reduce, so make the component respect it. framer-motion ignores it by default (reducedMotion: "never"); opt in:

    // .storybook/preview.tsx decorator
    <MotionConfig reducedMotion="user"><Story /></MotionConfig>
    

    or gate the loop yourself with useReducedMotion(). One line, and it's good app behavior anyway.

  • Escape hatch — detect the capture and render the end state. UI Verify flags every capture with a UIVerify marker on the user-agent and a window.__UI_VERIFY__ global, so a component can branch:

阅读完整来源 ↗