Storybook Vitest Visual Testing addon

storybook-addon-vis captures and compares image snapshot automatically and manually.

This addon is inspired by jest-image-snapshot. Internally, it uses vitest-plugin-vis to do the heavy lifting.

Starting from Storybook 8.3, Storybook introduces Storybook Test addon.

It allows you to test your components directly inside Storybook. It does this by using a Vitest plugin to transform your stories into [Vitest] tests using portable stories.

These stories are then run by [Vitest] in the browser using Vitest Browser Mode.

Since it is running in an actual browser, jest-image-snapshot does not work as it depends on NodeJS. This add-on provides similar functionality to jest-image-snapshot.

In addition, you can capture image snapshot manually, and controls how the auto image snapshot(s) are taken.

Install

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

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

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

This addon requires the Storybook Vitest addon (@storybook/addon-vitest).

Minimal configuration

Add storybookVis() to the Vitest plugins, and defineStorybookVis() to the Storybook addons.

// vitest.config.ts
import { join } from 'node:path'
import { storybookTest } from '@storybook/addon-vitest/vitest-plugin'
import { playwright } from '@vitest/browser-playwright'
import { storybookVis } from 'storybook-addon-vis/vitest-plugin'
import { defineConfig } from 'vitest/config'

export default defineConfig({
	plugins: [storybookTest({ configDir: join(import.meta.dirname, '.storybook') }), storybookVis()],
	test: {
		browser: {
			enabled: true,
			headless: true,
			api: { allowWrite: true },
			provider: playwright(),
			instances: [{ browser: 'chromium', viewport: { width: 1280, height: 720 } }],
		},
		setupFiles: ['./.storybook/vitest.setup.ts'],
	},
})

// .storybook/vitest.setup.ts
import { setProjectAnnotations } from '@storybook/react-vite'
import { vis, visAnnotations } from 'storybook-addon-vis/vitest-setup'
import { beforeAll } from 'vitest'
import * as projectAnnotations from './preview.tsx'

const annotations = setProjectAnnotations([visAnnotations, projectAnnotations])

beforeAll(annotations.beforeAll)

vis.setup()

// .storybook/main.ts
import { defineStorybookVis } from 'storybook-addon-vis/node'

export default {
	// ...
	addons: ['@storybook/addon-vitest', defineStorybookVis()],
}

Add tags: ['snapshot'] to your preview (or to a single story) to take an automatic snapshot of each story. Ignore the snapshot folders in .gitignore and add the storybook-addon-vis/matcher type to your tsconfig.json. The setup guide covers these, CSF Next, and the details.

The files above are adapted from the sb-csf-3 test case (testcases/sb-csf-3 in the repository, @storybook/react-vite framework), with its a11y and docs addons left out.

Example

A manual snapshot in a play function:

// button.stories.tsx
import type { StoryObj } from '@storybook/react-vite'
import { expect } from 'storybook/test'

export default {
	render: () => <div data-testid="subject">unit</div>,
}

export const MatchingElement: StoryObj = {
	async play({ canvas }) {
		const element = canvas.getByTestId('subject')
		await expect(element).toMatchImageSnapshot()
	},
}

This is the MatchingElement story of src/client/expect/to_match_image_snapshot.stories.tsx, whose matching spec (to_match_image_snapshot.spec.tsx) runs it with composeStories.

Version compatibility

storybook-addon-vis	Storybook	Vitest	Source
4.x	^10.1.10 (also @storybook/addon-vitest ^10.1.10)	^4 (also @vitest/browser ^4)	peerDependencies in package.json
3.x	10	not derivable (3.0.0 depends on vitest-plugin-vis 4.0.0, which updated to Vitest 4)	CHANGELOG.md 3.0.0
2.x	9	not derivable	CHANGELOG.md 2.0.0 ("Supports Storybook 9.0.0")
1.x	8	not derivable	previous version of this readme ("For Storybook 8, please use 1.x"), not stated in CHANGELOG.md

The minimum Storybook patch version of 1.x to 3.x is not derivable.

With Storybook 10.3+, @storybook/addon-vitest often applies project annotations for you. If you are not on CSF Next, you may need to move visAnnotations from setProjectAnnotations([...]) in vitest.setup.ts to .storybook/preview.ts. See Storybook 10.3+ and Vitest project annotations.

Documentation

Full documentation is on the documentation website:

• Install
• Setup
• Automatic snapshots
• Manual snapshots
• Troubleshooting
• Reference: defineStorybookVis()
• Reference: defineStorybookVisOptions()
• Migrating to 3.0 and Migrating to 1.0
• Reviewing failures with agents

For AI agents, llms.txt in this package lists the entry points and documentation pages. The site-wide copy is at https://repobuddy.github.io/visual-testing/llms.txt.