storybook-testing

What this skill does

# 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

```tsx
// 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

```ts
// 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

```python
# 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

```bash
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