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

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)

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

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