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.

.storybook/main.ts

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 as is for all snapshots. Unlike the Vitest plugin, the addon does not add local or the platform to it.
• 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: __vis__/<platform> in CI and __vis__/local elsewhere.

snapshotSubpath

Transform the default snapshot subdirectory path to match your project structure. It receives { subpath: string } and returns the transformed subpath. subpath is the story file’s import path as Storybook reports it, such as ./src/button.stories.tsx. The default removes the leading ./ and a leading common folder (src, source, test, tests, lib, js or ts).

shortenLongSnapshotPaths

Shortens snapshot paths that would be too long, the same way the shortenLongSnapshotPaths option of the Vitest plugin does. It defaults to false.

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

The default already drops a leading src/. To drop another folder, such as app/, remove it yourself. subpath starts with ./, so match that too:

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

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

Organize snapshots across multiple projects

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

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

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>/<__baselines__|__results__|__diffs__>/<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 the story name in lowercase, with every character other than a letter or digit replaced by -.
• variant identifies the specific snapshot variant.

Related

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