Storybook Testing — Storybook 9/10

Overview

Storybook 9/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 no longer just documentation; they are executable test specifications.

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
Mocking modules at the story level with sb.mock
Running accessibility tests in CI via the a11y addon
Generating living documentation with autodocs
Migrating from Storybook 7/8 to 9/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.
Isolate with sb.mock, not vi.mock. Story-level module mocking via sb.mock is scoped per-story and does not leak between tests.
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({})`	No type inference, verbose	CSF3 object stories with `satisfies`
`@storybook/test-runner` package	Deprecated in 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()`

References

references/storybook-migration-guide.md — Migration path from Storybook 7/8 to 9/10
references/storybook-ci-strategy.md — CI pipeline configuration for visual, interaction, and a11y testing
references/storybook-addon-ecosystem.md — Essential addons for Storybook 9/10 in 2026

Related Skills

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

storybook-testing