Skip to main content
skill CX Codex

storybook-testing — Claude Code skill for Storybook tests

The storybook-testing Claude Code skill guides component testing in Storybook 10. It covers story authoring, visual checks, CI setup, and migration from Storybook 9.

MIT 224 installs ★ 305 updated 2026-11-21

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yonatangross/orchestkit --skill storybook-testing -a claude-code
Open on GitHub

What storybook-testing does

The skill explains how to use Storybook stories as component tests. Topics include typed CSF3 stories, interaction checks with play(), and running stories through Vitest with @storybook/addon-vitest.

It also covers Chromatic TurboSnap for visual regression and @storybook/addon-a11y for accessibility scans in CI. Other sections describe module mocks with sb.mock, autodocs, and migration from Storybook 9. Storybook 10 requires Node 20.16+, 22.19+, or 24+; the skill targets Storybook 10.6.1 and later.

What it helps with

  • write a typed component story in CSF3
  • test a user interaction with play()
  • run Storybook stories as Vitest tests
  • set up visual regression with TurboSnap
  • scan component accessibility in CI

Example prompts for the agent

  • Show me how to test Storybook 10 component stories with Vitest.
  • Add a click interaction check with play() to this button story.
  • Explain a CI setup with TurboSnap and accessibility scans.

How to install storybook-testing

1Skills CLI (Vercel)

npx skills add yonatangross/orchestkit --skill storybook-testing -a claude-code

2Manually: put the files in place

~/.claude/skills/storybook-testing/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/storybook-testing/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about storybook-testing

How do I install storybook-testing in Claude Code?

Run npx skills add yonatangross/orchestkit --skill storybook-testing -a claude-code. The skill file is at ~/.claude/skills/storybook-testing/SKILL.md.

What does storybook-testing do?

It provides guidance for testing Storybook 10 components, including interaction tests, visual regression, accessibility scans, and autodocs.

Which Node versions does Storybook 10 require with this skill?

Use Node 20.16+, 22.19+, or 24+. The guide targets Storybook 10.6.1 and later.

Source text

SKILL.md · MIT
---
name: storybook-testing
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "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."
user-invocable: false
# Reference skill: fenced Storybook MCP names teach CSF/testing patterns; this
# skill never invokes those tools (disable-model-invocation: true).
tool-coverage: illustrative
targets:
  - library: storybook
    version: ">=10.6.1"
metadata:
  archive-candidate: "pending an outside usage signal"
  owner-agent: "frontend-ui-developer"
  category: document-asset-creation
  storybook-version: "10.3"
  version: "2.0.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "storybook, vitest, csf3, chromatic, turbosnap, visual-regression, play-functions, component-testing, a11y-testing, autodocs, esm-only, module-automocking"
allowed-tools: "Read Glob Grep WebFetch WebSearch"
---

# 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 the Storybook mode of the `design-to-code` 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

- `design-to-code` (Storybook mode): Storybook MCP tools for 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

© OrchestKit · MIT · yonatangross/orchestkit

Similar skills

All skills for Testing and QA →

From the same set86

The whole set →
animation-motion-design animation-motion-design — a Claude Code skill for interface animation with Motion and the View Transitions API. It comes into play for page changes, gesture-driven controls, and prefers-reduced-motion support. CX Codex +1 228installs web-research-workflow The web-research-workflow skill picks a web access method, extracts page content, and tracks competitor changes. Use it for research, documentation capture, and site monitoring. CX Codex +1 228installs react-server-components-framework The react-server-components-framework skill guides server-first Next.js apps with React Server Components, the App Router, caching, streaming SSR, and Server Actions. CX Codex +1 227installs doctor doctor diagnoses OrchestKit manifests, hooks, subagents, and MCP servers across project files. Pinpoints broken configurations and suggests fixes before deployment. CX Codex +1 227installs explore explore spawns 3–5 agents in parallel to map code structure, trace data flows, identify architecture patterns, and assess code health. Useful for quickly understanding an unfamiliar repo or discovering how a large system is designed. CX Codex +1 224installs errors The errors skill sorts Claude Code session failures by type, looks for earlier matches, and suggests recovery steps. It activates after a command, network, or tool error. CX Codex +1 223installs issue-progress-tracking issue-progress-tracking guides GitHub issue ceremonies using the gh CLI by updating progress labels, creating dedicated branches, enforcing atomic commits, and linking PRs. CX Codex +1 221installs release-management release-management creates GitHub releases with gh release, picks a semver version and builds notes from merged PRs. Handy when you tag a version or publish a changelog. CX Codex +1 220installs

Project sponsors

Companies that keep this analytics open