Storybook tests
Each query ships with its own mock, so every story renders offline and runs as a test.
The problem
The usual setup keeps three copies of the same fake data: request handlers for Storybook, fixtures for tests, and whatever the real query returns. They drift apart. A story renders fine against data the test never sees, and adding a query means registering a handler in two places before anything works offline.
What I concluded
Put the mock next to the fetcher, and let one build flag pick between them. Then stories and tests are the same thing.
const OFFLINE = import.meta.env.VITE_OFFLINE_MODE === "true";
function queryOptions<T>({ key, fetcher, mock }: Def<T>) {
return {
queryKey: key,
queryFn: OFFLINE ? () => Promise.resolve(mock) : fetcher,
retry: OFFLINE ? false : undefined,
};
}
Every query definition carries a deterministic mock: no Date.now(), no randomness. It can be a value, or a function of the variables when different inputs need different shapes.
Storybook always runs offline. Its Vite config defines the flag as true, so every story renders against real-shaped data with no handlers and no per-story setup. One preview file wraps every story in the app’s real providers, including a mock session that defaults to full access. A story overrides only what it tests, like read-only permissions, so gated components show their real disabled states.
Vitest runs the stories. The Storybook Vitest addon turns each story into a test, built with Storybook’s own Vite config, so the offline flag applies in tests too. They run in browser mode through the Playwright provider (in Vitest 4 that’s playwright() from @vitest/browser-playwright). Every story becomes a smoke test that has to render, and any story with a play function becomes an interaction test.
The same run checks accessibility. With the a11y addon set to fail on violations, axe runs after every story renders. Writing play functions with getByRole and getByLabelText doubles as a labelling check: if the test can’t find the button by name, neither can a screen reader. Because the mocks never change, screenshot diffs on the same stories mean the UI changed.
Rules
- The mock lives with the query. One definition, one source of fake data.
- Mocks are deterministic. No clocks, no randomness, or tests and screenshots flake.
- Flip the flag at build time. Client code can’t see a plain shell variable, so define it in the Vite config.
- Stories default to full access. Each one overrides only the permission or flag it’s about.
- Query by role and label. The test finding the control is the accessibility check.
What you get
Every component is documented with realistic data, every story is a test, and CI never touches the network, so there are no network flakes. The trade: mocks can drift from the real API (typing them from the schema catches most of it), the real fetcher never runs here, and browser tests are slower than jsdom. I keep a thin layer of real-network tests for the fetcher.
Related: Data access, Access control, Canary deploys