How do I install the Storybook Play Testing skill?

Run npx skillmds@latest add jonmumm/storybook-play-testing in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Storybook Play Testing skill do?

Storybook play function integration testing for TanStack Start/Router apps. Covers Vite config for blocking server code, router/query/theme decorators, state mocking strategies (props, collections, React Query cache, actor-kit), play function patterns, viewport coverage, and vitest browser test runner. Use when writing Storybook stories, setting up Storybook in a TanStack Start project, testing route-level pages, or adding play function interaction tests. It is listed under Web & Frontend on SkillMD.

Is Storybook Play Testing safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Storybook Play Testing?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Storybook Play Testing free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Storybook Play Testing?

jonmumm (@jonmumm) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Storybook Play Testing by jonmumm — Agent Skill

Name: Storybook Play Testing
Author: jonmumm

Storybook Play Function Testing

Integration tests that render real components in a real browser. No mocks of what you own — mock only the server boundary, then test real behavior through real DOM interactions.

When to Use

Setting up Storybook in a TanStack Start/Router project
Writing stories for route-level pages or shared components
Adding play function interaction tests
Testing form flows, state transitions, edge cases
Verifying responsive behavior (desktop + mobile)

The Problem: TanStack Start + Storybook

TanStack Start has SSR, server functions (createServerFn), Cloudflare Workers entry points, and a generated route tree — all of which crash in Storybook's browser-only preview.

Setup

Using the published addon (recommended)

pnpm add -D storybook-addon-tanstack-start

This single package handles everything: server-side import stubbing, TanStack/Nitro plugin stripping, router context, route params, search params, and loader data.

// .storybook/main.ts
import { tanstackStartPlugin } from 'storybook-addon-tanstack-start/plugin'
import { mergeConfig } from 'vite'

const config = {
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@storybook/addon-vitest',
    '@storybook/addon-a11y',
    '@storybook/addon-docs',
    '@storybook/addon-themes',
  ],
  framework: { name: '@storybook/react-vite', options: {} },
  async viteFinal(config) {
    return mergeConfig(config, {
      plugins: [tanstackStartPlugin({
        // Stub your app's server modules too
        additionalServerModules: ['~/lib/auth/server', '~/lib/billing/server'],
      })],
    })
  },
}
export default config

// .storybook/preview.ts — router decorator auto-applied
export { decorators } from 'storybook-addon-tanstack-start/preview'

For app-specific server modules, alias them to mock files:

// .storybook/mocks/auth-server.ts
export async function loginWithPassword({ data }: LoginInput) {
  if (data.email === 'test@example.com' && data.password === 'password123')
    return { ok: true as const, role: 'parent' as const }
  return { ok: false as const, error: 'Invalid email or password' }
}

// in .storybook/main.ts resolve.alias:
'~/lib/auth/server': path.resolve(__dirname, 'mocks/auth-server.ts'),

4. Query Decorator (`.storybook/decorators/QueryDecorator.tsx`)

Provides React Query context with optional cache pre-population:

import type { Decorator } from '@storybook/react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import React from 'react'

export const withQuery: Decorator = (Story, context) => {
  const queryConfig = context.parameters?.query || {}

  const queryClient = React.useMemo(() => {
    const client = new QueryClient({
      defaultOptions: {
        queries: {
          retry: false, // Fast failures in tests
          ...queryConfig.options?.queries,
          ...(queryConfig.enabled === false && { enabled: false }),
        },
        mutations: { retry: false, ...queryConfig.options?.mutations },
      },
    })

    // Pre-populate cache
    if (queryConfig.mockData) {
      Object.entries(queryConfig.mockData).forEach(([key, data]) => {
        const queryKey = Array.isArray(key) ? key : JSON.parse(key)
        client.setQueryData(queryKey, data)
      })
    }

    return client
  }, [queryConfig])

  return (
    <QueryClientProvider client={queryClient}>
      <Story />
    </QueryClientProvider>
  )
}

5. Preview (`.storybook/preview.ts`)

Wire decorators in correct order — outermost first. The router decorator comes from the addon; the Query decorator is custom (if your app uses React Query):

import { withThemeByClassName } from '@storybook/addon-themes'
import type { Preview } from '@storybook/react'
import { decorators as routerDecorators } from 'storybook-addon-tanstack-start/preview'
import { withQuery } from './decorators/QueryDecorator'
import '../src/styles.css'

const preview: Preview = {
  initialGlobals: {
    viewport: { value: 'desktop', isRotated: false },
  },
  decorators: [
    withQuery,           // Outermost: React Query context
    ...routerDecorators, // Middle: Router context (from addon)
    withThemeByClassName({
      themes: { light: 'light', dark: 'dark' },
      defaultTheme: 'light',
      parentSelector: 'html',
    }),
  ],
  parameters: {
    viewport: {
      options: {
        mobileSmall: { name: 'Mobile Small (320px)', styles: { width: '320px', height: '568px' } },
        mobileLarge: { name: 'Mobile Large (414px)', styles: { width: '414px', height: '896px' } },
        tablet: { name: 'Tablet (768px)', styles: { width: '768px', height: '1024px' } },
        desktop: { name: 'Desktop (1280px)', styles: { width: '1280px', height: '800px' } },
      },
    },
  },
}
export default preview

6. Vitest Browser Testing (`vitest.config.ts`)

Run play functions as real browser tests via Playwright:

import { storybookTest } from '@storybook/addon-vitest/vitest-plugin'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  plugins: [
    react(),
    storybookTest({
      configDir: '.storybook',
      storybookScript: 'pnpm storybook --ci',
      tags: {
        include: ['test'],
        exclude: ['no-tests'],
      },
    }),
  ],
  test: {
    name: 'storybook',
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
    setupFiles: ['./.storybook/vitest.setup.ts'],
    globals: true,
  },
})

Dependencies

pnpm add -D storybook-addon-tanstack-start \
  @storybook/react @storybook/react-vite @storybook/builder-vite \
  @storybook/addon-vitest @storybook/addon-a11y @storybook/addon-docs \
  @storybook/addon-themes storybook \
  @vitest/browser playwright

State Mocking Strategies

Different state management requires different mocking approaches. Pick the one that matches your app:

Strategy 1: Props (simplest)

For presentational components that receive data as props:

const meta: Meta<typeof AdminDashboard> = {
  component: AdminDashboard,
  tags: ['autodocs'],
}

export const Desktop: Story = {
  args: {
    kids: mockKids,
    totalLiability: 43750,
    pendingRequests: mockPendingRequests,
    onApproveRequest: fn(),
    onDenyRequest: fn(),
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement)
    await expect(canvas.getByText('Total Liability')).toBeVisible()
  },
}

When to use: Components that are already well-composed — they take data in, render it, and emit callbacks. This is the ideal target shape.

Strategy 2: Storybook Loaders + In-Memory Collections

For apps using TanStack React DB, Zustand, nanostores, or any client-side store:

import { appStateCollection, kidProfilesCollection } from '~/lib/kid-store'

const seedData = async () => {
  appStateCollection.insert({ id: 'app-state', activeProfileId: 'kid-1', globalRate: 500 })
  kidProfilesCollection.insert({
    id: 'kid-1', name: 'Avery', type: 'CHILD',
    payAmount: 2500, payFrequency: 'WEEKLY',
    nextPayoutDate: new Date(Date.now() + 4 * 24 * 60 * 60 * 1000).toISOString(),
  })
  return {}
}

export const Desktop: Story = {
  loaders: [seedData],
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement)
    await expect(canvas.getByText('Current Balance')).toBeVisible()
  },
}

When to use: Components that read from client-side stores via hooks. The loader seeds the store before the story renders. No network calls happen — collections live in memory.

Strategy 3: React Query Cache Pre-Population

For components that use useQuery / useSuspenseQuery:

export const WithData: Story = {
  parameters: {
    query: {
      mockData: {
        '["posts"]': [{ id: 1, title: 'First Post' }],
        '["user","123"]': { id: '123', name: 'John' },
      },
    },
  },
}

// Force loading state
export const Loading: Story = {
  parameters: { query: { enabled: false } },
}

When to use: Components that fetch data via React Query hooks.

Strategy 4: Actor-Kit Mock Clients

For components consuming actor-kit contexts (see /actorkit-storybook-testing skill for full details):

import { createActorKitMockClient } from 'actor-kit/test'
import { withActorKit } from 'actor-kit/storybook'

// Via decorator (static states)
const meta: Meta<typeof GameView> = {
  decorators: [
    withActorKit<GameMachine>({ actorType: 'game', context: GameContext }),
  ],
}

export const Lobby: Story = {
  parameters: {
    actorKit: {
      game: { 'game-123': { ...defaultGameSnapshot, value: { lobby: 'ready' } } },
    },
  },
}

// Via mount (interactive — state mutations mid-test)
export const StartGame: Story = {
  play: async ({ mount, canvas }) => {
    const client = createActorKitMockClient<GameMachine>({ initialSnapshot: defaultGameSnapshot })

    client.send = (event) => {
      if (event.type === 'START_GAME') {
        client.produce((draft) => { draft.value = { active: 'questionPrep' } })
      }
      return Promise.resolve()
    }

    await mount(
      <GameContext.ProviderFromClient client={client}>
        <GameView />
      </GameContext.ProviderFromClient>
    )

    await userEvent.click(canvas.getByRole('button', { name: /start/i }))
    await canvas.findByText(/question prep/i)
  },
}

Strategy 5: Server Function Mocks

For pages that call createServerFn — create per-domain mock files:

// .storybook/mocks/auth-server.ts
export async function loginWithPassword({ data }: LoginInput) {
  if (data.email === 'test@example.com' && data.password === 'password123')
    return { ok: true as const, role: 'parent' as const }
  return { ok: false as const, error: 'Invalid email or password' }
}

Then alias in main.ts:

'~/lib/auth/server': path.resolve(__dirname, 'mocks/auth-server.ts'),

Play Function Patterns

Basic: Assert Visibility

play: async ({ canvasElement }) => {
  const canvas = within(canvasElement)
  await expect(canvas.getByText('Dashboard')).toBeVisible()
  await expect(canvas.getByRole('button', { name: /submit/i })).toBeDisabled()
}

Form Interaction

play: async ({ canvasElement }) => {
  const canvas = within(canvasElement)

  await userEvent.type(canvas.getByLabelText('Amount'), '10')
  await userEvent.type(canvas.getByLabelText('What is this for?'), 'Art supplies')

  const submit = canvas.getByRole('button', { name: /submit/i })
  await expect(submit).toBeEnabled()
  await userEvent.click(submit)
}

Async Waiting

play: async ({ canvasElement }) => {
  const canvas = within(canvasElement)
  await waitFor(() =>
    expect(canvas.getByRole('heading', { name: 'Dashboard' })).toBeVisible()
  )
}

Labeled Steps

play: async ({ canvasElement, step }) => {
  const canvas = within(canvasElement)

  await step('Fill form', async () => {
    await userEvent.type(canvas.getByLabelText('Name'), 'Sarah')
  })

  await step('Submit', async () => {
    await userEvent.click(canvas.getByRole('button', { name: /continue/i }))
  })

  await step('Verify success', async () => {
    await expect(canvas.getByText(/success/i)).toBeVisible()
  })
}

Portaled Content (Drawers, Modals, Tooltips)

Content that portals to document.body won't be inside canvasElement:

play: async ({ canvasElement }) => {
  const canvas = within(canvasElement)

  await userEvent.click(canvas.getByRole('button', { name: 'Review' }))

  // Query from document.body for portaled content
  const body = within(document.body)
  await expect(body.getByText('Review Withdrawal Request')).toBeVisible()
}

Spy Callbacks

import { fn } from 'storybook/test'

export const ClickHandler: Story = {
  args: { onClick: fn() },
  play: async ({ canvasElement, args }) => {
    const canvas = within(canvasElement)
    await userEvent.click(canvas.getByRole('button'))
    await expect(args.onClick).toHaveBeenCalledTimes(1)
  },
}

Viewport Coverage

Every story MUST have Desktop + Mobile variants. This catches responsive bugs early.

export const Desktop: Story = {
  args: defaultArgs,
  play: async ({ canvasElement }) => { /* assertions */ },
}

export const Mobile: Story = {
  args: defaultArgs,
  globals: { viewport: { value: 'mobileLarge', isRotated: false } },
  play: Desktop.play, // Reuse play function when assertions are the same
}

For stories with mobile-specific assertions, write a separate play function.

Story Organization

Route-Level Pages

Extract the page component from the route file so it can be imported without route registration side effects:

// src/routes/dashboard/index.tsx (route file)
export const Route = createFileRoute('/dashboard/')({
  component: DashboardPage,
  loader: async () => { /* server-side loader */ },
})

// The page component is exported separately
export function DashboardPage() { /* ... */ }

// src/routes/dashboard/DashboardPage.stories.tsx
import { DashboardPage } from '~/routes/dashboard/index'

function DashboardWrapper() {
  return (
    <div className="min-h-screen">
      <Navigation currentPath="/dashboard" />
      <DashboardPage />
    </div>
  )
}

const meta: Meta<typeof DashboardWrapper> = {
  title: 'Pages/Dashboard',
  component: DashboardWrapper,
  parameters: { layout: 'fullscreen' },
}

Naming Convention

Components/UI/Button          — Shared UI primitives
Components/Navigation         — Layout components
Components/AdminDashboard     — Feature components
Onboarding/Kid Name           — Flow steps
Pages/Kid/Dashboard           — Route-level pages
Pages/Admin/Settings          — Route-level pages

Mocking Server Functions in Stories

The addon stubs createServerFn generically. For your app's own server modules, use additionalServerModules in the plugin config to redirect them to stubs, then create mock files with the same function signatures:

// .storybook/mocks/auth-server.ts
export async function loginWithPassword({ data }: LoginInput) {
  if (data.email === 'parent@example.com' && data.password === 'password123')
    return { ok: true as const, role: 'parent' as const }
  return { ok: false as const, error: 'Invalid email or password' }
}

export async function startOAuthLogin({ data }: OAuthStartInput) {
  return { ok: true as const, redirectUrl: `https://oauth.example.com/${data.provider}` }
}

Then alias in .storybook/main.ts:

resolve: {
  alias: {
    '~/lib/auth/server': path.resolve(__dirname, 'mocks/auth-server.ts'),
    '~/lib/billing/server': path.resolve(__dirname, 'mocks/billing-server.ts'),
  },
},

Checklist

Before shipping stories:

Every story has Desktop + Mobile variants
Play functions assert on visible text/roles, not implementation details
fn() used for callback props to verify interactions
Edge cases covered: empty state, error state, loading state, max data
Portaled content (drawers, modals) queried from document.body
Server modules aliased to mocks in .storybook/main.ts
tags: ['autodocs'] on meta for auto-generated docs
parameters: { layout: 'fullscreen' } for page-level stories

Storybook MCP for Agent-Driven Development

Storybook 10.3+ includes MCP support that lets AI agents interact with your stories — preview components, run tests, and self-correct.

# Install the MCP addon
npx storybook add @storybook/addon-mcp

# Register with your agent
npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project

For TanStack Start projects, install storybook-addon-tanstack-start first (makes the build work), then add MCP on top. For team-wide access, publish via Chromatic:

{
  "mcpServers": {
    "storybook-mcp": {
      "type": "http",
      "url": "https://main--<appid>.chromatic.com/mcp"
    }
  }
}

Related Skills

/actorkit-storybook-testing — Deep patterns for actor-kit mock clients and state machines
/testing-trophy — Philosophy: play functions ARE the integration test layer
/react-composable-components — Components shaped for easy story testing
/dont-use-use-effect — Cleaner React = easier to test
/mutation-testing — Verify play function test quality with Stryker

Storybook Play Testing

File contents

Storybook Play Function Testing

When to Use

The Problem: TanStack Start + Storybook

Setup

Using the published addon (recommended)

4. Query Decorator (`.storybook/decorators/QueryDecorator.tsx`)

5. Preview (`.storybook/preview.ts`)

6. Vitest Browser Testing (`vitest.config.ts`)

Dependencies

State Mocking Strategies

Strategy 1: Props (simplest)

Strategy 2: Storybook Loaders + In-Memory Collections

Strategy 3: React Query Cache Pre-Population

Strategy 4: Actor-Kit Mock Clients

Strategy 5: Server Function Mocks

Play Function Patterns

Basic: Assert Visibility

Form Interaction

Async Waiting

Labeled Steps

Portaled Content (Drawers, Modals, Tooltips)

Spy Callbacks

Viewport Coverage

Story Organization

Route-Level Pages

Naming Convention

Mocking Server Functions in Stories

Checklist

Storybook MCP for Agent-Driven Development

Related Skills

Frequently asked questions

Storybook Play Testing

File contents

Storybook Play Function Testing

When to Use

The Problem: TanStack Start + Storybook

Setup

Using the published addon (recommended)

4. Query Decorator (.storybook/decorators/QueryDecorator.tsx)

5. Preview (.storybook/preview.ts)

6. Vitest Browser Testing (vitest.config.ts)

Dependencies

State Mocking Strategies

Strategy 1: Props (simplest)

Strategy 2: Storybook Loaders + In-Memory Collections

Strategy 3: React Query Cache Pre-Population

Strategy 4: Actor-Kit Mock Clients

Strategy 5: Server Function Mocks

Play Function Patterns

Basic: Assert Visibility

Form Interaction

Async Waiting

Labeled Steps

Portaled Content (Drawers, Modals, Tooltips)

Spy Callbacks

Viewport Coverage

Story Organization

Route-Level Pages

Naming Convention

Mocking Server Functions in Stories

Checklist

Storybook MCP for Agent-Driven Development

Related Skills

Related skills

Frequently asked questions

How do I install the Storybook Play Testing skill?

What does the Storybook Play Testing skill do?

Is Storybook Play Testing safe to use?

Which AI agents work with Storybook Play Testing?

Is Storybook Play Testing free to use?

Who published Storybook Play Testing?

4. Query Decorator (`.storybook/decorators/QueryDecorator.tsx`)

5. Preview (`.storybook/preview.ts`)

6. Vitest Browser Testing (`vitest.config.ts`)