Skip to content
visual-testingvisual-testingvisual-testing

Get started with the Storybook addon

This page takes you from nothing to a committed baseline in a few minutes. The addon runs your stories in Vitest browser mode and compares an image of each one with a stored baseline.

Supports

Section titled “Supports”
Package Version
storybook ^10.1.10
@storybook/addon-vitest ^10.1.10
vitest ^4
@vitest/browser ^4

These are the peer dependencies of storybook-addon-vis in its package.json. Vitest browser mode needs a provider, Playwright or WebdriverIO.

Install

Section titled “Install”

Set up the Storybook Vitest addon first. The addon needs it. Then install storybook-addon-vis:

Terminal window
npm install --save-dev storybook-addon-vis


pnpm add --save-dev storybook-addon-vis


yarn add --save-dev storybook-addon-vis

Configure

Section titled “Configure”

Three edits are enough for the first snapshot. Configuration explains each of them.

// vitest.config.ts: add the storybookVis plugin next to storybookTest
import { storybookTest } from '@storybook/addon-vitest/vitest-plugin'
import { storybookVis } from 'storybook-addon-vis/vitest-plugin'
import { defineConfig } from 'vitest/config'


export default defineConfig({
  plugins: [storybookTest(), storybookVis()],
  test: {
    browser: { /* your Vitest browser mode configuration */ },
    setupFiles: ['./vitest.setup.ts'],
  },
})
// vitest.setup.ts: apply the annotations and turn visual testing on
import { setProjectAnnotations } from '@storybook/your-framework'
import { vis, visAnnotations } from 'storybook-addon-vis/vitest-setup'
import { beforeAll } from 'vitest'
import * as projectAnnotations from './.storybook/preview.ts'


const annotations = setProjectAnnotations([projectAnnotations, visAnnotations])


beforeAll(annotations.beforeAll)


vis.setup()
// .storybook/main.ts: register the addon
const config: StorybookConfig = {
  addons: ['storybook-addon-vis'],
}

Using CSF Next? The CSF Next guide replaces the setup file with one line in the preview.

Take a snapshot

Section titled “Take a snapshot”

Give a story the snapshot tag:

button.stories.tsx
export const Primary = {
  tags: ['snapshot'],
  args: { label: 'Button', primary: true },
}

To snapshot every story, put tags: ['snapshot'] in .storybook/preview.ts instead. Automatic snapshots covers the tag rules.

First run: create the baselines

Section titled “First run: create the baselines”

A snapshot test fails when it has no baseline to compare with. Run Vitest once with the update flag to write the first baselines:

Terminal window
npx vitest run -u

The images land in the snapshot root, __vis__/local on your machine and __vis__/<platform> on CI:

__vis__/local/
  __baselines__/button.stories.tsx/primary-auto.png

The file name is the story name and a key. Automatic snapshots use the key auto unless you set themes.

Commit __baselines__ and ignore the rest, as shown in Configuration. Later runs compare the new render with the baseline and write __results__ and __diffs__ when they differ. In Storybook, use -u and not createMissingBaseline, which may not reach the server. Updating baselines explains why and covers the update workflow. How snapshots work explains the folders.

Next

Section titled “Next”