defineStorybookVisOptions

A helper function to define options for the Storybook Visual Testing addon. It returns the options you pass in, which gives you type checking and completion.

import { defineMain } from '@storybook/your-framework'
import { defineStorybookVisOptions } from 'storybook-addon-vis/node'

export default defineMain({
  addons: [
    {
      name: 'storybook-addon-vis',
      options: defineStorybookVisOptions({
        visProjects: [
          {
            snapshotRootDir: '__vis__/linux',
          },
          {
            snapshotRootDir: '__vis__/local',
          },
        ],
      }),
    },
  ],
})

Function signature

function defineStorybookVisOptions(options: StorybookVisOptions): StorybookVisOptions

Options

`visProjects`

Configure one or more visual testing projects. Each project can have its own snapshot storage settings.

`snapshotRootDir`

Where snapshots are stored. It can be:

A static path string, used for all snapshots.
A function that receives { ci: boolean; platform: string }. ci is whether the code runs in a CI environment, and platform is the platform string (for example linux, darwin, win32).
undefined, which uses the default snapshot root directory.

`snapshotSubpath`

Transform the default snapshot subdirectory path to match your project structure. It receives { subpath: string } and returns the transformed subpath.

Examples

Store snapshots in a custom directory

import { defineStorybookVisOptions } from 'storybook-addon-vis/node'

const options = defineStorybookVisOptions({
  visProjects: [
    {
      snapshotRootDir: '__vis__/snapshots',
    },
  ],
})

Use different directories for CI and local development

import { defineStorybookVisOptions } from 'storybook-addon-vis/node'

const options = defineStorybookVisOptions({
  visProjects: [
    {
      snapshotRootDir: ({ ci, platform }) => {
        if (ci) {
          return `__vis__/ci/${platform}`
        }
        return '__vis__/local'
      },
    },
  ],
})

Customize the snapshot subdirectory structure

For example, to remove a src/ prefix from file paths:

import { defineStorybookVisOptions } from 'storybook-addon-vis/node'

const options = defineStorybookVisOptions({
  visProjects: [
    {
      snapshotRootDir: '__vis__',
      snapshotSubpath: ({ subpath }) => subpath.replace(/^src\//, ''),
    },
  ],
})

Organize snapshots across multiple projects

import { defineStorybookVisOptions } from 'storybook-addon-vis/node'

const options = defineStorybookVisOptions({
  visProjects: [
    {
      snapshotRootDir: '__vis__/components',
      snapshotSubpath: ({ subpath }) => `components/${subpath}`,
    },
    {
      snapshotRootDir: '__vis__/pages',
      snapshotSubpath: ({ subpath }) => `pages/${subpath}`,
    },
  ],
})

Use the default configuration

Provide an empty project configuration to use the default snapshot root directory and subpath:

import { defineStorybookVisOptions } from 'storybook-addon-vis/node'

const options = defineStorybookVisOptions({
  visProjects: [{}],
})

Snapshot path structure

The final snapshot path is constructed as:

<snapshotRootDir>/<baseline|diff|results>/<snapshotSubpath>/<task-id>-<variant>.png

snapshotRootDir is determined by the snapshotRootDir option.
snapshotSubpath is the result of the snapshotSubpath function, or the default.
task-id is derived from the story name.
variant identifies the specific snapshot variant.

defineStorybookVis: register the addon and its options in one call.