Config overview

Unverified

No spec covers the claims on this page yet. That includes the default snapshot path, the folder names, and the snapshotRootDir context fields. The options themselves are covered on the vis page.

Configuration refers to configuring the plugin in your vitest.config.ts file.

You configure the plugin by passing options to the vis function from vitest-plugin-vis/config.

vitest.config.ts

import { vis } from 'vitest-plugin-vis/config'

export default defineConfig({
  plugins: [vis()],
})

Customizing the snapshot path

Say you have this test:

src/components/MyComponent.spec.tsx

describe('MyComponent', () => {
  describe('className', () => {
    it('can customize className', () => {
      // ...
    })
  })
})

By default, when you run the test locally, the image snapshot is saved in the following path:

__vis__/local/__baselines__/components/MyComponent.spec.tsx/MyComponent/className/can-customize-className-auto.png

This path breaks down into a few parts.

__vis__/local: snapshotRootDir

This is the snapshotRootDir where the image snapshot folders are placed. When running on CI, the snapshotRootDir defaults to __vis__/<process.platform>.

__baselines__: baseline folder

This is the folder where the baseline images are saved and used for comparison. There is also a __results__ folder where the images of the current test run are saved, and a __diffs__ folder where the diff images are saved if the comparison fails.

components/MyComponent.spec.tsx: snapshotSubpath

This part is based on the path of the test file relative to the project root. By default, the plugin trims a common folder such as src or test from the path to reduce the path length. See trimCommonFolder.

If you place test files in multiple folders, such as both tests and src, and they might have files with the same name and create conflicting snapshots, use snapshotSubpath to customize the snapshot sub-path to avoid conflicts.

vitest.config.ts

import { vis } from 'vitest-plugin-vis/config'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  plugins: [
    vis({
      // keep the folder structure
      snapshotSubpath: ({ subpath }) => subpath,
    }),
  ],
})

With the above configuration, the snapshot folder structure looks like this:

v __vis__
  > # ...
  v local # snapshot generated on local machine
    > __baselines__
      v examples
        v button.stories.tsx
          snapshot-1.png
          snapshot-2.png
      v src
        v button.stories.tsx
          snapshot-1.png
          snapshot-2.png
      v tests
        v button.stories.tsx
          snapshot-1.png
          snapshot-2.png
v examples
  button.stories.tsx
v src
  button.stories.tsx
v tests
  button.stories.tsx

MyComponent/className/can-customize-className: snapshotId

This is the ID of the snapshot, based on the test name and scope. It is not customizable.

auto: snapshotKey

This is the key of the snapshot. Here it is auto because the snapshot is taken automatically at the end of the test. If you take a manual snapshot, the key is 0, 1, and so on. If you customize the key when taking the snapshot, the global customization is not used.

Customizing with options

You can customize snapshotRootDir, snapshotSubpath, and snapshotKey with the corresponding options:

vitest.config.ts

import { defineConfig } from 'vitest/config'
import { trimCommonFolder, vis } from 'vitest-plugin-vis/config'

export default defineConfig({
  plugins: [
    vis({
      snapshotRootDir: ({
        ci, // true if running on CI
        platform, // process.platform
        providerName, // 'playwright' or 'webdriverio'
        browserName, // 'chromium', 'firefox', etc.
        screenshotFailures, // from `browser` config
        screenshotDirectory, // from `browser` config
      }) => `__vis__/${ci ? platform : 'local'}`,
      snapshotSubpath: ({ subpath }) => trimCommonFolder(subpath),
      // Alphanumeric characters and underscore are allowed. Dash is not allowed.
      snapshotKey: 'auto',
    }),
  ],
})