f0-storybook-testing

name: f0-storybook-testing description: Write Storybook play function interaction tests and configure axe-playwright a11y tests for F0 components. Use when adding play functions to stories, debugging a11y violations, or configuring per-story a11y test modes.

F0 Storybook Testing

Covers two types of tests that run via pnpm test-storybook:

1. Interaction tests — play functions in .stories.tsx files
2. a11y tests — axe-playwright runs automatically on every story via .storybook/test-runner.ts

For story file structure and snapshot patterns, see the f0-storybook-stories skill instead.

Quick Reference

Key Rules

Interaction Tests (play functions)

• Import expect, within, userEvent, waitFor from "storybook/test"
• Use within(canvasElement) to scope queries to the story canvas
• For portals (dropdowns, tooltips): query canvasElement.closest("body")! instead
• Use step() to group related assertions — improves failure messages
• userEvent in play functions does not need .setup() — call directly

a11y Tests (automatic)

• axe runs on every story automatically after render (WCAG 2.x AA)
• Default behaviour on violation: test fails ("error" mode)
• To suppress failures on known violations, configure per-story:

// Skip a11y entirely in CI (use sparingly)
parameters: {
  a11y: {
    skipCi: true
  }
}

// Downgrade to warning (test passes, violation logged)
parameters: {
  a11y: {
    test: "warning"
  }
}

// Downgrade to todo (test passes, violation logged)
parameters: {
  a11y: {
    test: "todo"
  }
}

// Custom axe rules for this story
parameters: {
  a11y: {
    config: {
      rules: [{ id: "color-contrast", enabled: false }]
    }
  }
}

• withSkipA11y() from @/lib/storybook-utils/parameters is for Chromatic snapshot skips, not for axe — use parameters.a11y directly for axe control

Commands

pnpm test-storybook                      # run all storybook tests
pnpm test-storybook -- --testPathPattern filename  # run one file