Storybook Vitest Addon

0.1.8 · active · verified Tue Apr 21

The `storybook_vitest_addon` integrates Vitest unit test results directly into a Storybook panel, enhancing the development workflow by displaying relevant test outcomes alongside component stories. This addon is currently at version `0.1.8` and has a relatively frequent release cadence, often aligning with Storybook and Vitest major version updates, as seen with recent upgrades to Storybook 8. It primarily supports React and Vite-based Storybook setups, requiring `vitest` v1.1.0 or newer. Its key differentiator is its minimal visual overhead, focusing on clarity for test results, and its direct integration via Storybook parameters, making it straightforward to link test output (JSON format) to individual stories. Developers provide a JSON file of Vitest results and the test file name to the addon's parameters to enable the display.

Common errors

```
Cannot find module 'storybook_vitest_addon'
```
cause The package is not installed or incorrectly referenced.

fix Run `npm install storybook_vitest_addon` or `yarn add storybook_vitest_addon`. Ensure the package is listed in `devDependencies` in `package.json`.
```
TypeError: Cannot read properties of undefined (reading 'vitest')
```
cause The addon is not correctly registered with Storybook, or the parameters are not nested under `vitest`.

fix Add `storybook_vitest_addon` to your `.storybook/main.js` or `.storybook/main.ts` `addons` array. Ensure your story's `parameters` object has a `vitest` key with `testFile` and `testResults`.
```
Storybook 'manager' build fails after upgrading Storybook
```
cause Incompatibility between the addon's version and the new Storybook major version.

fix Update `storybook_vitest_addon` to the latest compatible version. For Storybook 8, this typically means `storybook_vitest_addon@0.1.7` or higher.

Warnings

breaking The addon has frequent updates to maintain compatibility with major Storybook versions. Upgrading Storybook (e.g., from v7 to v8) will often require updating this addon to a compatible version.
Fix: Always check the `Compatibility` section in the addon's README or `package.json` for supported Storybook and Vitest versions when upgrading either dependency. For Storybook 8, ensure `storybook_vitest_addon` is `v0.1.7` or newer.
breaking Early versions (pre-v0.0.6) had breaking changes related to Vitest API updates. Specifically, `v0.0.6` addressed a breaking change in Vitest `v0.8.0`.
Fix: Upgrade to `storybook_vitest_addon` `v0.0.6` or newer if using Vitest `v0.8.0` or higher to ensure correct parsing of test results.
gotcha The addon requires test results in a JSON format. This means you need to configure Vitest to output its results to a JSON file during your test run.
Fix: Configure your `vitest` script to output results to a JSON file (e.g., `vitest run --json --outputFile=./unit-test-results.json`). Then, import this file into your Storybook stories.
gotcha The addon's panel might not display content if it's not correctly configured or if the provided `testResults` JSON is malformed or empty.
Fix: Ensure `testFile` and `testResults` parameters are correctly set within `parameters.vitest` for the story. Verify that the `unit-test-results.json` file actually contains valid Vitest output and is being correctly imported.

Install

npm install storybook_vitest_addon npm
yarn add storybook_vitest_addon yarn
pnpm add storybook_vitest_addon pnpm

Imports

ADDON_ID
```
import { ADDON_ID } from 'storybook_vitest_addon';
```
While not directly imported by end-users for common usage, internal Storybook addon development often relies on such constants. The primary interaction is via Storybook parameters.
vitest
wrong:
```
import { vitest } from 'storybook_vitest_addon'
```
correct:
```
parameters: { vitest: { testFile: '...', testResults: ... } }
```
The addon is configured via the Storybook `parameters` field under the `vitest` key, not by importing a symbol named `vitest` directly from the package. This is a common pattern for Storybook addons.
vitestResults
```
import vitestResults from './unit-test-results.json';
```
The addon expects a JSON file containing Vitest test results, which is typically imported as a default export from a local JSON file generated by Vitest.

Quickstart

This quickstart demonstrates how to configure the `storybook_vitest_addon` in a Storybook story file, linking Vitest test results to a component.

import { Meta, StoryObj } from '@storybook/react';
import vitestResults from './unit-test-results.json'; // Assume this file is generated by Vitest

interface ButtonProps {
  label: string;
  primary?: boolean;
}

// Dummy Button Component for example
const Button = ({ primary = false, label }: ButtonProps) => {
  const mode = primary ? 'storybook-button--primary' : 'storybook-button--secondary';
  return (
    <button type="button" className={['storybook-button', mode].join(' ')}>
      {label}
    </button>
  );
};

const meta: Meta<typeof Button> = {
  title: 'Example/Button',
  component: Button,
  parameters: {
    vitest: {
      testFile: 'Button.test.tsx', // Name of the Vitest test file for this component
      testResults: vitestResults, // The imported JSON object of test results
    },
  },
  argTypes: {
    backgroundColor: { control: 'color' },
  },
};

export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
};

export const Secondary: Story = {
  args: {
    label: 'Button',
  },
};

view raw JSON →