Storybook Testing — Storybook 10
Overview
Storybook 10 unifies component testing into a single workflow: interaction tests via play() functions, visual regression via Chromatic TurboSnap, and accessibility audits via the a11y addon — all running through Vitest. Stories are executable test specifications, not just documentation.
What's new in Storybook 10 (vs 9):
- ESM-only enforced — the single breaking change; Node 20.16+ / 22.19+ / 24+ required; 29% smaller install
- Module automocking (
sb.mock) — build-time module mocking, scoped per-project in preview.ts
- CSF factories (React, preview) —
defineMain → definePreview → preview.meta() → meta.story() chain
- Essential addons in core — viewport, controls, interactions, actions no longer separate deps
- Import path changes —
@storybook/test → storybook/test (old paths still work as aliases)
- React Server Component story support — test RSC in isolation
- Vitest 4 support —
experimental-addon-test renamed to addon-vitest
When to use this skill:
- Writing component stories in CSF3 format with TypeScript
- Setting up interaction tests with
play() functions
- Configuring Chromatic visual regression with TurboSnap
- Using module automocking at the story level
- Running accessibility tests in CI via the a11y addon
- Generating living documentation with autodocs
- Migrating from Storybook 9 to 10
Quick Reference
| Rule |
Impact |
Description |
storybook-csf3-factories |
HIGH |
Typesafe CSF3 story factories with satisfies Meta |
storybook-play-functions |
CRITICAL |
Interaction testing with play() and @storybook/test |
storybook-vitest-integration |
HIGH |
Run stories as Vitest tests via @storybook/addon-vitest |
storybook-chromatic-turbosnap |
HIGH |
TurboSnap reduces snapshot cost 60-90% |
storybook-sb-mock |
HIGH |
Story-level module mocking with sb.mock |
storybook-a11y-testing |
CRITICAL |
Automated axe-core accessibility scans in CI |
storybook-autodocs |
MEDIUM |
Auto-generated docs from stories |
Storybook Testing Pyramid
┌──────────────┐
│ Visual │ Chromatic TurboSnap
│ Regression │ (snapshot diffs)
├──────────────┤
│ Accessibility│ @storybook/addon-a11y
│ (a11y) │ (axe-core scans)
├──────────────┤
│ Interaction │ play() functions
│ Tests │ (@storybook/test)
├──────────────┤
│ Unit Tests │ Vitest + storybookTest
│ (stories) │ plugin
└──────────────┘
Each layer catches different defects: unit tests validate logic, interaction tests verify user flows, a11y tests catch accessibility violations, and visual tests catch unintended UI regressions.
Quick Start
CSF3 Story with Play Function
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { expect, fn, userEvent, within } from 'storybook/test'
import { Button } from './Button'
const meta = {
component: Button,
args: {
onClick: fn(),
},
} satisfies Meta<typeof Button>
export default meta
type Story = StoryObj<typeof meta>
export const Primary: Story = {
args: {
label: 'Click me',
variant: 'primary',
},
play: async ({ canvasElement, args }) => {
const canvas = within(canvasElement)
const button = canvas.getByRole('button', { name: /click me/i })
await userEvent.click(button)
await expect(args.onClick).toHaveBeenCalledOnce()
await expect(button).toHaveStyle({ backgroundColor: 'rgb(37, 99, 235)' })
},
}
Vitest Configuration
// vitest.config.ts
import { storybookTest } from '@storybook/addon-vitest/vitest-plugin'
import { defineConfig } from 'vitest/config'
export default defineConfig({
plugins: [storybookTest()],
test: {
setupFiles: ['./vitest.setup.ts'],
},
})
Key Principles
- Stories are tests. Every story with a
play() function is an executable interaction test that runs in Vitest.
- CSF3 +
satisfies for type safety. Use satisfies Meta<typeof Component> for full type inference on args and play functions.
- Module automocking (SB 10). Register
sb.mock(import(...)) in .storybook/preview.ts, configure per-story with mocked() in beforeEach. Never use vi.mock in story files. No factory functions — sb.mock is build-time, not runtime.
- TurboSnap for CI speed. Only snapshot stories affected by code changes — reduces Chromatic usage by 60-90%.
- Accessibility is not optional. The a11y addon runs axe-core scans on every story and gates CI on violations.
- Living documentation. Autodocs generates prop tables and usage examples directly from stories — no separate docs site needed.
Anti-Patterns (FORBIDDEN)
| Anti-Pattern |
Why It Fails |
Use Instead |
CSF2 Template.bind({}) |
Deprecated, no type inference, will be removed in SB 11 |
CSF3 object stories with satisfies |
@storybook/test-runner package |
Deprecated since Storybook 9 |
@storybook/addon-vitest |
vi.mock() in story files |
Leaks between stories, breaks isolation |
Register sb.mock(import(...)) in preview.ts, configure with mocked() in beforeEach |
| Full Chromatic snapshots on every PR |
Expensive and slow |
TurboSnap with onlyChanged: true |
| Manual accessibility checking |
Misses violations, not repeatable |
@storybook/addon-a11y in CI pipeline |
| Separate documentation site |
Drifts from actual component behavior |
Autodocs with tags: ['autodocs'] |
| Testing implementation details |
Brittle, breaks on refactors |
Test user-visible behavior via play() |
| CJS imports in stories |
ESM-only since SB 9/10 |
Use ESM imports, set "module": "ESNext" in tsconfig |
Storybook MCP Integration (addon-mcp)
When @storybook/addon-mcp is installed, agents can run tests and preview stories via MCP instead of CLI. This enables the generate → test → self-heal loop.
MCP Tools for Testing
| Tool |
Purpose |
run-story-tests |
Run component + a11y tests via MCP, returns pass/fail + violation details |
preview-stories |
Returns preview URLs for visual verification in chat |
get-storybook-story-instructions |
Guidance on writing effective stories + interaction tests |
Agent Testing Loop
# 1. Generate component + CSF3 story
# 2. Run tests via MCP
results = run-story-tests(
stories=[{ "storyId": "button--primary" }],
a11y=True
)
# 3. If failures: read violations, fix, retry (max 3)
# 4. Preview in chat for visual confirmation
preview-stories(stories=[{ "storyId": "button--primary" }])
Setup
npx storybook add @storybook/addon-mcp # current: 0.6.0, Apr 2026
# Enable docs toolset in .storybook/main.ts:
# componentsManifest: true # was experimentalComponentsManifest (SB 10.3 rename, default-on)
npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project
See storybook-mcp-integration skill for full tool reference and patterns.
References
references/storybook-migration-guide.md — Migration path from Storybook 9 to 10
references/storybook-ci-strategy.md — CI pipeline configuration for visual, interaction, and a11y testing
references/storybook-addon-ecosystem.md — Essential addons for Storybook 10 in 2026
Related Skills
storybook-mcp-integration — Storybook MCP tools: component discovery, testing, previews
react-server-components-framework — React 19 + Next.js 16 patterns (component architecture)
accessibility — Broader accessibility patterns beyond Storybook
devops-deployment — CI/CD pipeline patterns for automated testing
1---2name: storybook-testing3license: MIT4compatibility: "Claude Code 2.1.277+."5description: "Storybook 10 testing: Vitest integration, CSF3 factories, play() interaction tests, Chromatic TurboSnap, automocking, a11y addon, autodocs. Use when writing component stories, setting up visual regression, Storybook CI, or migrating from Storybook 9."6user-invocable: false7# Reference skill: fenced Storybook MCP names teach CSF/testing patterns; this8# skill never invokes those tools (disable-model-invocation: true).9tool-coverage: illustrative10targets:11 - library: storybook12 version: ">=10.6.1"13metadata:14 source: https://skillmd.com/skills/yonatangross/storybook-testing15 owner-agent: "frontend-ui-developer"16 category: document-asset-creation17 storybook-version: "10.3"18 version: "2.0.0"19 author: "OrchestKit"20 complexity: "medium"21 tags: "storybook, vitest, csf3, chromatic, turbosnap, visual-regression, play-functions, component-testing, a11y-testing, autodocs, esm-only, module-automocking"22allowed-tools: "Read Glob Grep WebFetch WebSearch"23---2425# Storybook Testing — Storybook 102627## Overview2829Storybook 10 unifies component testing into a single workflow: **interaction tests** via `play()` functions, **visual regression** via Chromatic TurboSnap, and **accessibility audits** via the a11y addon — all running through Vitest. Stories are executable test specifications, not just documentation.3031**What's new in Storybook 10** (vs 9):32- **ESM-only enforced** — the single breaking change; Node 20.16+ / 22.19+ / 24+ required; 29% smaller install33- **Module automocking (`sb.mock`)** — build-time module mocking, scoped per-project in preview.ts34- **CSF factories (React, preview)** — `defineMain` → `definePreview` → `preview.meta()` → `meta.story()` chain35- **Essential addons in core** — viewport, controls, interactions, actions no longer separate deps36- **Import path changes** — `@storybook/test` → `storybook/test` (old paths still work as aliases)37- **React Server Component story support** — test RSC in isolation38- **Vitest 4 support** — `experimental-addon-test` renamed to `addon-vitest`3940**When to use this skill:**41- Writing component stories in CSF3 format with TypeScript42- Setting up interaction tests with `play()` functions43- Configuring Chromatic visual regression with TurboSnap44- Using module automocking at the story level45- Running accessibility tests in CI via the a11y addon46- Generating living documentation with autodocs47- Migrating from Storybook 9 to 104849---5051## Quick Reference5253| Rule | Impact | Description |54|------|--------|-------------|55| `storybook-csf3-factories` | HIGH | Typesafe CSF3 story factories with `satisfies Meta` |56| `storybook-play-functions` | CRITICAL | Interaction testing with `play()` and `@storybook/test` |57| `storybook-vitest-integration` | HIGH | Run stories as Vitest tests via `@storybook/addon-vitest` |58| `storybook-chromatic-turbosnap` | HIGH | TurboSnap reduces snapshot cost 60-90% |59| `storybook-sb-mock` | HIGH | Story-level module mocking with `sb.mock` |60| `storybook-a11y-testing` | CRITICAL | Automated axe-core accessibility scans in CI |61| `storybook-autodocs` | MEDIUM | Auto-generated docs from stories |6263---6465## Storybook Testing Pyramid6667```68 ┌──────────────┐69 │ Visual │ Chromatic TurboSnap70 │ Regression │ (snapshot diffs)71 ├──────────────┤72 │ Accessibility│ @storybook/addon-a11y73 │ (a11y) │ (axe-core scans)74 ├──────────────┤75 │ Interaction │ play() functions76 │ Tests │ (@storybook/test)77 ├──────────────┤78 │ Unit Tests │ Vitest + storybookTest79 │ (stories) │ plugin80 └──────────────┘81```8283Each layer catches different defects: unit tests validate logic, interaction tests verify user flows, a11y tests catch accessibility violations, and visual tests catch unintended UI regressions.8485---8687## Quick Start8889### CSF3 Story with Play Function9091```tsx92// Button.stories.tsx93import type { Meta, StoryObj } from '@storybook/react'94import { expect, fn, userEvent, within } from 'storybook/test'95import { Button } from './Button'9697const meta = {98 component: Button,99 args: {100 onClick: fn(),101 },102} satisfies Meta<typeof Button>103104export default meta105type Story = StoryObj<typeof meta>106107export const Primary: Story = {108 args: {109 label: 'Click me',110 variant: 'primary',111 },112 play: async ({ canvasElement, args }) => {113 const canvas = within(canvasElement)114 const button = canvas.getByRole('button', { name: /click me/i })115116 await userEvent.click(button)117 await expect(args.onClick).toHaveBeenCalledOnce()118 await expect(button).toHaveStyle({ backgroundColor: 'rgb(37, 99, 235)' })119 },120}121```122123### Vitest Configuration124125```ts126// vitest.config.ts127import { storybookTest } from '@storybook/addon-vitest/vitest-plugin'128import { defineConfig } from 'vitest/config'129130export default defineConfig({131 plugins: [storybookTest()],132 test: {133 setupFiles: ['./vitest.setup.ts'],134 },135})136```137138---139140## Key Principles141142- **Stories are tests.** Every story with a `play()` function is an executable interaction test that runs in Vitest.143- **CSF3 + `satisfies` for type safety.** Use `satisfies Meta<typeof Component>` for full type inference on args and play functions.144- **Module automocking (SB 10).** Register `sb.mock(import(...))` in `.storybook/preview.ts`, configure per-story with `mocked()` in `beforeEach`. Never use `vi.mock` in story files. No factory functions — `sb.mock` is build-time, not runtime.145- **TurboSnap for CI speed.** Only snapshot stories affected by code changes — reduces Chromatic usage by 60-90%.146- **Accessibility is not optional.** The a11y addon runs axe-core scans on every story and gates CI on violations.147- **Living documentation.** Autodocs generates prop tables and usage examples directly from stories — no separate docs site needed.148149---150151## Anti-Patterns (FORBIDDEN)152153| Anti-Pattern | Why It Fails | Use Instead |154|-------------|-------------|-------------|155| CSF2 `Template.bind({})` | Deprecated, no type inference, will be removed in SB 11 | CSF3 object stories with `satisfies` |156| `@storybook/test-runner` package | Deprecated since Storybook 9 | `@storybook/addon-vitest` |157| `vi.mock()` in story files | Leaks between stories, breaks isolation | Register `sb.mock(import(...))` in preview.ts, configure with `mocked()` in beforeEach |158| Full Chromatic snapshots on every PR | Expensive and slow | TurboSnap with `onlyChanged: true` |159| Manual accessibility checking | Misses violations, not repeatable | `@storybook/addon-a11y` in CI pipeline |160| Separate documentation site | Drifts from actual component behavior | Autodocs with `tags: ['autodocs']` |161| Testing implementation details | Brittle, breaks on refactors | Test user-visible behavior via `play()` |162| CJS imports in stories | ESM-only since SB 9/10 | Use ESM imports, set `"module": "ESNext"` in tsconfig |163164---165166## Storybook MCP Integration (addon-mcp)167168When `@storybook/addon-mcp` is installed, agents can run tests and preview stories via MCP instead of CLI. This enables the **generate → test → self-heal** loop.169170### MCP Tools for Testing171172| Tool | Purpose |173|------|---------|174| `run-story-tests` | Run component + a11y tests via MCP, returns pass/fail + violation details |175| `preview-stories` | Returns preview URLs for visual verification in chat |176| `get-storybook-story-instructions` | Guidance on writing effective stories + interaction tests |177178### Agent Testing Loop179180```python181# 1. Generate component + CSF3 story182# 2. Run tests via MCP183results = run-story-tests(184 stories=[{ "storyId": "button--primary" }],185 a11y=True186)187# 3. If failures: read violations, fix, retry (max 3)188# 4. Preview in chat for visual confirmation189preview-stories(stories=[{ "storyId": "button--primary" }])190```191192### Setup193194```bash195npx storybook add @storybook/addon-mcp # current: 0.6.0, Apr 2026196# Enable docs toolset in .storybook/main.ts:197# componentsManifest: true # was experimentalComponentsManifest (SB 10.3 rename, default-on)198npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project199```200201See `storybook-mcp-integration` skill for full tool reference and patterns.202203---204205## References206207- `references/storybook-migration-guide.md` — Migration path from Storybook 9 to 10208- `references/storybook-ci-strategy.md` — CI pipeline configuration for visual, interaction, and a11y testing209- `references/storybook-addon-ecosystem.md` — Essential addons for Storybook 10 in 2026210211## Related Skills212213- `storybook-mcp-integration` — Storybook MCP tools: component discovery, testing, previews214- `react-server-components-framework` — React 19 + Next.js 16 patterns (component architecture)215- `accessibility` — Broader accessibility patterns beyond Storybook216- `devops-deployment` — CI/CD pipeline patterns for automated testing