Migrating to Vitest addon from test-runner

The test-runner was created back in 2021 to enable users to run stories as tests. It is a solution that uses Jest as a runner and Playwright as a browser environment. Over the years, Storybook has evolved and introduced many testing-related concepts, including a Vitest-based testing solution, a spiritual successor to the test-runner. Alongside it, we released a testing widget, allowing users to run tests directly from Storybook's UI and get reports such as a11y and coverage.

You do not have to change how you write your stories between the test-runner and the Vitest addon.

This guide explains how to migrate an existing project using @storybook/test-runner to the @storybook/addon-vitest.

Why migrate?

Migrating to the Vitest addon replaces the previous Jest-based test-runner with a modern, browser-friendly testing stack. It's designed to run stories as tests directly in Storybook's UI while also integrating with Vitest's CLI and IDE integrations — reducing setup complexity and bringing built-in support for accessibility and coverage. The main benefits are summarized below.

Vitest is used as a runner instead of Jest, offering faster test execution and better integration with modern JavaScript tooling.
Stories seamlessly integrate as tests in your Vitest setup, significantly simplifying your component test configuration.
There is no need to build and run Storybook to run tests, which makes the setup faster and more portable.
Tests are still tested in a Playwright environment, but in Vitest's Browser mode.
Accessibility testing comes out of the box and integrates with the Storybook testing widget and Accessibility addon panel.
Code coverage is enabled via Vitest's built-in coverage support. You no longer need instrumentation from the @storybook/addon-coverage package, which can make your stories render faster.

For more, please refer to the comparison table in the Vitest addon guide.

Is my project eligible to upgrade?

The Vitest addon is supported and recommended for React, Preact, Vue, Svelte, and Web Components projects, which use the Vite builder (or the Next.js framework with Vite).

If you are using a different renderer (such as Angular) or the Webpack builder, you should continue to use the test runner to test your stories.

Migration steps

Below you will find the essential steps to migrate from the test-runner to the Vitest addon. Additionally, you can use the following commit as a reference for an example project being migrated.

1. Remove test-runner dependencies

Remove the following dependencies:

@storybook/test-runner dependency
@storybook/addon-coverage dependency (if present)

Remove the following files:

test-runner-jest.config.js file (if present)
.storybook/test-runner.ts file (if present)
- If you had configured accessibility testing, this is now done out of the box with the Vitest addon.
- If you had configured image snapshot testing, check this FAQ.
- If you had configuration for custom, advanced use cases such as using the prepare hook, please reach out on Discord or open a discussion on GitHub so we can assist you with the migration.

3. Set up `@storybook/addon-vitest`

Run this command, which will set up all the necessary code for you.
<CodeSnippets path="addon-test-install.md" />

Update the package.json script for Storybook tests, replacing the test-runner binary and using Vitest instead:

diff

{
  "scripts": {
-    "test-storybook": "test-storybook"
+    "test-storybook": "vitest --project=storybook"
  }
}

4. Update your CI to run Vitest instead of the test-runner

If you're using the Storybook test-runner in CI, replace its build/serve/wait flow with a single Vitest command. For example, in GitHub Actions:

diff

name: 'Storybook Tests'

on: push

jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version-file: '.nvmrc'
      - name: Install dependencies
        run: npm ci
      - name: Install Playwright
        run: npx playwright install --with-deps
-      - name: Build Storybook
-        run: npm run build-storybook --quiet
-      - name: Serve Storybook and run tests
-        run: |
-          npx concurrently -k -s first -n "SB,TEST" -c "magenta,blue" \
-            "npx http-server storybook-static --port 6006 --silent" \
-            "npx wait-on tcp:127.0.0.1:6006 && npm run test-storybook --coverage"
+      - name: Run storybook tests
+        run: |
+          npm run test-storybook

If you want to generate coverage reports in CI, use the --coverage flag with the test script: npm run test-storybook -- --coverage.

For other CI providers and for more detailed configuration info, check the testing in CI guide.

FAQ

What if I am using Storybook with Webpack or RsPack?

The Vitest addon relies on Vite to transform and run your stories as tests. Which means it only works with Storybook frameworks that use Vite.

If your Storybook project uses a non-Vite builder like Webpack or RsPack, you will need to keep using the @storybook/test-runner for your component testing.

Most Webpack-based Storybook projects which do not have complex configurations can migrate to Vite relatively easily. If you are using Next.js, you can use the @storybook/nextjs-vite framework to use Vite with Storybook.

What if I am using Jest for my unit tests?

You can still migrate to use Vitest, but if you believe you won't benefit from it, you can keep using the @storybook/test-runner.

What if I am doing image snapshot testing?

There are solutions for image snapshot testing that integrate with the Storybook testing widget:

On the cloud with the Visual tests addon
Locally with storybook-addon-vis