Return

Storybook + Vitest Integration for Component Testing

INFRASTRUCTURE •

Situation

Discovered @storybook/addon-vitest on Storybook's "Level Up" onboarding page. Visual UI components required additional browser environment setups to run unit tests. The addon features enable to run Storybook's tests on CLI environments without additional configurations. Wanted to consolidate testing documentation (Storybook) and testing execution (Vitest) into a unified workflow.

Task

  • Install @storybook/addon-vitest and configure integration between Storybook stories and Vitest
  • Enable browser-based component testing without duplicating test code
  • Set up infrastructure to run interactive tests defined in Storybook stories via Vitest CLI

Action

1. Installed Dependencies

  • Added @storybook/addon-vitest (v10.1.8) for Storybook-Vitest integration
  • Added @vitest/browser-playwright (v4.0.15) for browser mode support

2. Configured Storybook

  • Registered @storybook/addon-vitest addon to enable test execution from stories
  • Kept existing addons: accessibility (a11y), docs, and links

3. Configured Vitest

  • Created Vitest project named "storybook" with storybookTest() plugin
  • Configured plugin to point to .storybook/ directory and launch Storybook via pnpm storybook --no-open
  • Enabled browser mode with Playwright provider (headless Chromium)
  • Added tag filtering (tags: { include: ["test"] }) to only run stories tagged with "test"
  • Referenced setup file .storybook/vitest.setup.ts for Storybook annotations

4. Created Setup File

  • Used setProjectAnnotations() to load Storybook preview configuration
  • Registered beforeAll hook to initialize Storybook context for tests

5. Added Test Scripts

  • pnpm test: Run all stories tagged "test" once (vitest run --project=storybook)

6. Wrote Interactive Tests

  • Tagged story with ["autodocs", "test"] to include in test runs
  • Added play function with user interaction simulation (hover, unhover)
  • Verified DOM rendering, tooltip behavior, and accessibility attributes

Result

Successfully unified component documentation and testing into a single workflow. Stories now serve as both visual documentation in Storybook UI and executable tests in Vitest, eliminating the need to maintain separate test files. Visual and interaction tests that previously required manual inspection in Storybook can now run automatically in CI/CD pipeline via pnpm test.

The integration significantly reduced configuration complexity by leveraging Storybook's browser environment setup for Vitest. All tests run in real browser context (Chromium via Playwright) by default, eliminating JSDOM-related limitations and the need for custom browser environment configurations. Tag-based filtering (tags: ["test"]) provides granular control over which stories execute as tests.

The trade-off was removing the existing standalone Vitest setup in favor of the Storybook-driven approach, which introduced new testing syntax. Developers now write play functions using Storybook's testing utilities (within, userEvent, expect from storybook/test) instead of traditional Vitest test blocks. While this requires learning Storybook-specific patterns, it reduces context switching by keeping tests colocated with stories.