Add Story

Purpose: Create comprehensive Storybook stories with test plans, play functions, and validated passing tests Usage: /add-story <ComponentName or path>

Prerequisites

• •Storybook installed and configured in the project
• •@storybook/test for expect, userEvent, within, waitFor
• •MSW (Mock Service Worker) if the component has API dependencies
• •@storybook/addon-interactions for play function debugging

Constraints

• •Do not modify the original component without explicit permission
• •Do not run full test suites (npm test) -- scope to the component
• •Do not use querySelector in tests -- use Testing Library queries
• •Do not skip waitFor for async assertions
• •Test plan must be included at top of story file
• •Create play functions for all interactive scenarios
• •Run tests and ensure they pass
• •Use Testing Library queries (getByRole, getByLabelText, etc.)
• •Scope tests appropriately (canvas for component, screen for modals)

Workflow

Step 1: Read the Component Structure

• •Read the component file to understand props, slots, events, and behavior
• •Identify component states and variants
• •Note any conditional rendering or dynamic behavior
• •List dependencies (API calls, stores, context providers)

Step 2: Create a Test Plan

Document all meaningful component states to cover using Given/When/Then format. Include the test plan as a block comment at the top of the story file. See references/story-patterns.md for the test plan template.

Step 3: Review Existing Patterns

Before writing stories:

• •Check existing stories in the project for conventions
• •Identify mocking requirements (MSW, stores, providers)
• •Note the project's Storybook configuration

Step 4: Write Stories for Visual States

Create stories covering all visual states (default, disabled, loading, error, etc.). Use meta configuration with title, component, parameters, and autodocs tag. See references/story-patterns.md for templates and the factory pattern.

Step 5: Write Play Functions for Interactions

Add play functions for all interactive scenarios using step() blocks, Testing Library queries, and waitFor for async assertions. See references/story-patterns.md for play function examples.

Step 6: Add Mocking If Required

For components with API dependencies, use MSW handlers in story parameters. See references/testing-best-practices.md for MSW patterns.

Step 7: Run Tests and Validate

npm run test-storybook -- --grep "ComponentName"

Fix failures, re-run until all pass. See references/testing-best-practices.md for debugging guidance.

Story File Checklist

Before completing:

• • Test plan documented at top of file
• • Meta configuration complete (title, component, parameters)
• • Default story exists
• • All visual states covered (disabled, loading, error, etc.)
• • Play functions for interactive scenarios
• • MSW handlers for API dependencies (if applicable)
• • Tests pass locally

References

• •references/story-patterns.md - Story templates, play functions, factory pattern, test plan format
• •references/testing-best-practices.md - MSW mocking, Testing Library queries, async handling, example workflow