Storybook Testing — Storybook 10 Skill

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
# Enable docs toolset in .storybook/main.ts:
#   experimentalComponentsManifest: true
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

Agent Skills: Storybook Testing — Storybook 10

Install this agent skill to your local

Skill Files