qa-storybook

name	qa-storybook
description	[Testing] Storybook visual regression: baselines, responsive breakpoints, state variations, Atomic Design.
argument-hint	component name | atoms | molecules | organisms | all

/qa-storybook — Storybook Component Testing

Test Storybook components for visual regression, responsive behavior, and state completeness. Delegates to ui-ux-expert agent with Chrome DevTools MCP.

Usage

/qa-storybook Button               # Test a specific component
/qa-storybook atoms                 # Test all atom-tier components
/qa-storybook molecules             # Test all molecule-tier components
/qa-storybook organisms             # Test all organism-tier components
/qa-storybook all                   # Full visual regression run

Supporting Files

• tooling-stack.md — SB 9 package map (storybook/test, @storybook/addon-vitest, a11y addon, Chromatic), determinism rules, CI gating, hosted-vs-dev caveat, boundary with /qa-accessibility. Read first.
• play-function-patterns.md — Canonical interaction-test patterns using storybook/test (expect, userEvent, fn, step); when play is the wrong tool.
• how-to-test-storybook.md — What to test per component (rendering, a11y, interactions, visual, composition, i18n, error boundaries); negative/edge scenarios.
• visual-regression-testing.md — Test case template for visual regression: baselines, state matrix, tool selection (Chromatic default, Playwright fallback), determinism rules.
• responsive-component-testing.md — Responsive testing at 5 breakpoints (375px, 768px, 1024px, 1280px, 1920px): layout adaptation, touch targets, text reflow, image scaling.

Execution

1. Resolve Storybook URL from environment: STORYBOOK_URL (QA) or STORYBOOK_DEV_URL (dev)

2. Identify target components:

   • If component name: find matching stories in Storybook
   • If tier (atoms/molecules/organisms): test all components in that Atomic Design tier
   • Baselines captured on-demand and stored in test evidence directories

3. Delegate to ui-ux-expert via Task tool (subagent_type: ui-ux-expert):

   • Pass component name(s), Storybook URL, baseline directory
   • Agent uses Chrome DevTools MCP for screenshot capture
   • Agent reads supporting files from this skill folder for methodology

4. For each component, test:

   • All story variations (default, hover, focus, error, loading, disabled)
   • 5 responsive breakpoints (mobile 375px → desktop 1920px)
   • Compare against existing baselines if present
   • Flag pixel differences > threshold

5. Output:

   • Visual diff report with pass/fail per component/state/viewport
   • New baselines saved to test evidence directory (e.g., reports/tickets/SprintXX-XX/VCST-XXXX/screenshots/)
   • Summary: X components tested, Y passed, Z regressions found

Rules

• Always capture all documented states, not just the default
• Use naming convention: {story-name}-{viewport}.png
• Baselines are captured on-demand — no persistent storybook/ directory needed
• If no baseline exists, the first capture becomes the baseline
• Hosted Storybook is a production build — import.meta.env.DEV === false. Don't verify DEV-only warnings here (see tooling-stack.md).
• A11y assertions: only on the Coffee theme (other themes aren't WCAG-compliant); visual diff still covers all themes.

Boundary with /qa-accessibility

• /qa-storybook — a11y addon inside stories (component-isolated, axe rules per component).
• /qa-accessibility — full-page audits on storefront/admin (keyboard journeys, landmarks, page-level contrast).
• If a finding reproduces in a story, it belongs here. If it only appears once composed into a page, it belongs to /qa-accessibility.
• When you need a programmatic axe run on a rendered story (outside the addon — e.g. asserting against a specific story iframe), use the shared axeRunSnippet() + classifyAxeResults() from scripts/lib/axe-runner.ts so severity mapping and the "axe-unavailable ⇒ inconclusive, not clean" rule stay identical to /qa-accessibility. Visual pixel-diff stays with Chromatic / Playwright toHaveScreenshot() (the agent owns the "intentional change?" verdict); there is no JS-snippet differ.