vitest-plugin-vis 4.1.0 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-plugin-vis",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Vitest visual testing plugin",
   "keywords": [
     "image-snapshot",
@@ -20,6 +20,8 @@
   },
   "type": "module",
   "imports": {
+    "#vitest-plugin-vis": "./src/index.ts",
+    "#vitest-plugin-vis/client-api": "./src/client-api.ts",
     "#vitest-plugin-vis/config": "./src/config.ts",
     "#vitest-plugin-vis/setup": "./src/setup.ts"
   },
@@ -56,6 +58,10 @@
       "types": "./dist/setup.d.mts",
       "default": "./dist/setup.mjs"
     },
+    "./setup-api": {
+      "types": "./dist/setup-api.d.mts",
+      "default": "./dist/setup-api.mjs"
+    },
     "./testing": {
       "types": "./dist/testing.d.mts",
       "default": "./dist/testing.mjs"
@@ -78,38 +84,39 @@
     "pngjs": "^7.0.0",
     "rimraf": "^6.0.1",
     "ssim.js": "^3.5.0",
-    "type-plus": "8.0.0-beta.7"
+    "type-plus": "8.0.0-beta.8"
   },
   "devDependencies": {
     "@repobuddy/storybook": "^2.1.2",
     "@repobuddy/typescript": "^2.1.0",
-    "@storybook-community/storybook-dark-mode": "^7.0.3",
-    "@storybook/addon-docs": "^10.2.0-alpha.1",
-    "@storybook/addon-vitest": "^10.2.0-alpha.1",
-    "@storybook/react-vite": "^10.2.0-alpha.1",
+    "@storybook-community/storybook-dark-mode": "^7.1.0",
+    "@storybook/addon-docs": "^10.1.10",
+    "@storybook/addon-mdx-gfm": "^8.6.14",
+    "@storybook/addon-vitest": "^10.1.10",
+    "@storybook/react-vite": "^10.1.10",
     "@tailwindcss/vite": "^4.1.14",
     "@types/is-ci": "^3.0.4",
     "@types/pngjs": "^6.0.5",
     "@types/react": "^19.2.2",
-    "@vitest/browser": "^4.0.9",
-    "@vitest/browser-playwright": "^4.0.9",
-    "@vitest/browser-webdriverio": "^4.0.9",
-    "@vitest/coverage-istanbul": "^4.0.9",
-    "@vitest/coverage-v8": "^4.0.9",
-    "@vitest/expect": "^4.0.9",
-    "@vitest/ui": "4.0.9",
+    "@vitest/browser": "^4.0.16",
+    "@vitest/browser-playwright": "^4.0.16",
+    "@vitest/browser-webdriverio": "^4.0.16",
+    "@vitest/coverage-istanbul": "^4.0.16",
+    "@vitest/coverage-v8": "^4.0.16",
+    "@vitest/expect": "^4.0.16",
+    "@vitest/ui": "^4.0.16",
     "cross-env": "^10.0.0",
     "never-fail": "^1.1.4",
     "npm-run-all2": "^8.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "storybook": "^10.2.0-alpha.1",
+    "storybook": "^10.1.10",
     "storybook-addon-tag-badges": "^3.0.2",
     "tailwindcss": "^4.1.14",
-    "tsdown": "^0.16.6",
+    "tsdown": "^0.19.0",
     "typescript": "^5.9.3",
-    "vite": "^7.1.12",
-    "vitest": "^4.0.9",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16",
     "vitest-browser-react": "^2.0.2"
   },
   "peerDependencies": {

package/readme.md

@@ -179,12 +179,12 @@ you can use `snapshotSubpath` to customize the snapshot sub-path to avoid confli
 
 ```ts
 // vitest.config.ts
-import { storybookVis } from 'storybook-addon-vis/vitest-plugin'
+import { vis } from 'vitest-plugin-vis/config'
 import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
 	plugins: [
-		storybookVis({
+		vis({
 			// keep the folder structure
 			snapshotSubpath: (subpath) => subpath
 		})
@@ -245,12 +245,14 @@ export default defineConfig({
 		vis({
 			snapshotRootDir: ({
 				ci, // true if running on CI
+				rootDir, // base directory for snapshots (default: '__vis__')
 				platform, // process.platform
 				providerName, // 'playwright' or 'webdriverio'
 				browserName, // 'chromium', 'firefox', etc.
+				projectName, // instance name when using multiple browser instances
 				screenshotFailures, // from `browser` config
 				screenshotDirectory, // from `browser` config
-			}) => `__vis__/${ci ? platform : 'local'}`,
+			}) => `${rootDir}/${ci ? platform : 'local'}`,
 			snapshotSubpath: ({ subpath }) => trimCommonFolder(subpath),
 			// Alphanumeric characters, and underscore are allowed. Dash is not allowed.
 			snapshotKey: 'auto',
@@ -259,6 +261,49 @@ export default defineConfig({
 })
 ```
 
+#### Multiple browser instances
+
+When using multiple browser instances (e.g., different viewports or browsers),
+each instance runs the same tests and would overwrite snapshots if they shared the same directory.
+Use `projectName` in `snapshotRootDir` to separate snapshots per instance:
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+import { playwright } from '@vitest/browser-playwright'
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [
+		vis({
+			snapshotRootDir({ ci, rootDir, projectName, platform }) {
+				return `${rootDir}/${ci ? platform : 'local'}/${projectName}`
+			},
+		}),
+	],
+	test: {
+		browser: {
+			enabled: true,
+			provider: playwright(),
+			instances: [
+				{ browser: 'chromium', name: 'HD', viewport: { width: 1280, height: 720 } },
+				{ browser: 'chromium', name: 'SVGA', viewport: { width: 800, height: 600 } },
+			],
+		},
+	},
+})
+```
+
+With this configuration, snapshots are stored in separate directories per instance:
+
+```sh
+__vis__/local/HD/__baselines__/...
+__vis__/local/SVGA/__baselines__/...
+```
+
+On CI, the `projectName` corresponds to the `name` of each instance.
+See [vitest.config.playwright.ts](vitest.config.playwright.ts) for a full example.
+
 ### Customizing auto snapshot subject
 
 By default, auto snapshots are taken from the `document.body` element.

package/src/{client/task → auto_snapshots}/_ctx.ts

@@ -1,4 +1,4 @@
-import { getCurrentSuite, getCurrentTest } from '../external/vitest/vitest_suite_proxy.ts'
+import { getCurrentSuite, getCurrentTest } from '../client/external/vitest/vitest_suite_proxy.ts'
 
 export const ctx = {
 	getCurrentTest,

package/src/auto_snapshots/_extract_auto_snapshot_options.ts

@@ -0,0 +1,26 @@
+import { NAME } from '../client-api.ts'
+import type { MetaTask } from './auto_snapshot_options.ts'
+import type { SnapshotMeta } from './snapshot_meta.ts'
+
+export function extractAutoSnapshotOptions<M extends SnapshotMeta<any> = SnapshotMeta<any>>(
+	task: MetaTask,
+): M | undefined {
+	if (!task) return
+
+	const list: any[] = []
+	let current = task
+	while (current?.suite) {
+		list.unshift(current.suite.meta)
+		current = current.suite
+	}
+	list.unshift(task.file?.meta)
+	list.push(task.meta)
+	return list.reduce(
+		(acc, cur) => {
+			const meta = cur?.[NAME]
+			// biome-ignore lint/performance/noAccumulatingSpread: I think this is needed
+			return meta ? Object.assign({}, acc, meta) : acc
+		},
+		{ enable: false },
+	)
+}

package/src/{client/task → auto_snapshots}/auto_snapshot_options.mdx

@@ -1,7 +1,6 @@
 import { Meta } from "@storybook/addon-docs/blocks";
-import { setAutoSnapshotOptions } from '../index'
 
-<Meta title="vitest-plugin-vis/setAutoSnapshotOptions" />
+<Meta title="auto snapshots/setAutoSnapshotOptions" />
 
 # setAutoSnapshotOptions
 

package/src/{client/task → auto_snapshots}/auto_snapshot_options.ts

@@ -1,6 +1,6 @@
-import { assertSnapshotKeyWithoutDash } from '../../shared/asserts.ts'
-import { NAME } from '../../shared/constants.ts'
-import type { ComparisonMethod } from '../../shared/types.ts'
+import { assertSnapshotKeyWithoutDash } from '../shared/asserts.ts'
+import { NAME } from '../shared/constants.ts'
+import type { ComparisonMethod } from '../shared/types.ts'
 import { ctx } from './_ctx.ts'
 import type { SnapshotMeta } from './snapshot_meta.ts'
 
@@ -62,25 +62,3 @@ function getTask(): MetaTask | undefined {
 function parseMeta<M extends ComparisonMethod>(meta: boolean | SnapshotMeta<M>): SnapshotMeta<M> {
 	return typeof meta === 'boolean' ? ({ enable: meta } as any) : { enable: true, ...meta }
 }
-
-export function extractAutoSnapshotOptions<M extends SnapshotMeta<any> = SnapshotMeta<any>>(
-	task: MetaTask,
-): M | undefined {
-	if (!task) return
-
-	const list: any[] = []
-	let current = task
-	while (current?.suite) {
-		list.unshift(current.suite.meta)
-		current = current.suite
-	}
-	list.unshift(task.file?.meta)
-	list.push(task.meta)
-	return list.reduce(
-		(acc, cur) => {
-			const meta = cur?.[NAME]
-			return meta ? Object.assign({}, acc, meta) : acc
-		},
-		{ enable: false },
-	)
-}

package/src/{client/task → auto_snapshots}/snapshot_meta.ts

@@ -1,4 +1,4 @@
-import type { ComparisonMethod, ImageSnapshotSubjectOptions, ToMatchImageSnapshotOptions } from '../../shared/types.ts'
+import type { ComparisonMethod, ImageSnapshotSubjectOptions, ToMatchImageSnapshotOptions } from '../shared/types.ts'
 
 export type SnapshotMeta<M extends ComparisonMethod> = ToMatchImageSnapshotOptions<M> &
 	ImageSnapshotSubjectOptions & {

package/src/client/actions/match_image_snapshot_action.ts

@@ -19,8 +19,6 @@ export async function matchImageSnapshotAction(
 
 	const info = await commands.prepareImageSnapshotComparison(taskId, parseImageSnapshotSubject(subject), options)
 
-	if (!info) return
-
 	return compareImageSnapshot(commands, taskId, info, options)
 }
 

package/src/client/snapshot/compare_image_snapshot.logic.ts

@@ -10,5 +10,5 @@ export function prettifyOptions(options: ToMatchImageSnapshotOptions<any> | unde
 		options.diffOptions ? `diffOptions: ${JSON.stringify(options.diffOptions)}` : '',
 	]
 		.filter(Boolean)
-		.join('\n                 ')
+		.join('\n                ')
 }

package/src/client/snapshot/compare_image_snapshot.ts

@@ -20,8 +20,22 @@ export async function compareImageSnapshot(
 ) {
 	options = { ...info, ...options } as any
 
-	const baselineImage = await toImageData(info.baseline)
 	const resultImage = await toImageData(info.result)
+
+	if (!info.baseline) {
+		if (server.config.snapshotOptions.updateSnapshot === 'all') {
+			await writeSnapshot(commands, resolve(info.projectRoot, info.baselinePath), resultImage)
+			return
+		}
+		throw new Error(
+			dedent`Snapshot \`${taskId}\` has no baseline image. Please review the new snapshot and update the baseline image.
+
+				Options:    ${prettifyOptions(options)}
+				Actual:     ${resolve(info.projectRoot, info.resultPath)}`,
+		)
+	}
+
+	const baselineImage = await toImageData(info.baseline)
 	const [baselineAlignedImage, resultAlignedImage] = alignImagesToSameSize(baselineImage, resultImage)
 	const { width, height } = baselineAlignedImage
 	const diffImage = new ImageData(width, height)

package/src/client/snapshot/should_take_snapshot.ts

@@ -1,5 +1,5 @@
+import type { SnapshotMeta } from '../../auto_snapshots/snapshot_meta.ts'
 import { hasRenderContent } from '../external/browser/has_render_content.ts'
-import type { SnapshotMeta } from '../task/snapshot_meta.ts'
 
 export function shouldTakeSnapshot(meta: SnapshotMeta<any> | undefined) {
 	return hasRenderContent() && meta?.enable

package/src/client/suite/auto_snapshot_matcher.ts

@@ -1,9 +1,9 @@
 import dedent from 'dedent'
+import { extractAutoSnapshotOptions } from '../../auto_snapshots/_extract_auto_snapshot_options.ts'
+import type { SnapshotMeta } from '../../auto_snapshots/snapshot_meta.ts'
 import type { SetupVisSuiteCommand } from '../../shared/commands.types.ts'
 import type { ComparisonMethod } from '../../shared/types.ts'
 import { shouldTakeSnapshot } from '../snapshot/should_take_snapshot.ts'
-import { extractAutoSnapshotOptions } from '../task/auto_snapshot_options.ts'
-import type { SnapshotMeta } from '../task/snapshot_meta.ts'
 import { toTaskId } from '../task/task_id.ts'
 import { ctx } from './_ctx.ts'
 
@@ -25,7 +25,6 @@ export function autoSnapshotMatcher<GM extends Record<string, any> | unknown = u
 		) {
 			return async function matchImageSnapshot() {
 				const test = ctx.getCurrentTest()
-				if ((test?.result?.errors?.length ?? 0) > 0) return
 
 				const meta = extractAutoSnapshotOptions(test)
 				if (!shouldTakeSnapshot(meta)) return

package/src/client-api.ts

@@ -1,5 +1,6 @@
 import './server/commands/augment.ts'
 
+export * from './auto_snapshots/auto_snapshot_options.ts'
 export * from './client/actions/has_image_snapshot_action.ts'
 export * from './client/actions/load_image_snapshot_results_action.ts'
 export * from './client/actions/match_image_snapshot_action.ts'
@@ -7,7 +8,6 @@ export * from './client/actions/match_page_image_snapshot_action.ts'
 export * from './client/expect/expectation_result.ts'
 export type * from './client/expect/to_match_image_snapshot.types.ts'
 export * from './client/suite/auto_snapshot_matcher.ts'
-export { setAutoSnapshotOptions, type MetaTask } from './client/task/auto_snapshot_options.ts'
 export * from './client/task/task_id.ts'
 export * from './shared/constants.ts'
 export type * from './shared/types.ts'

package/src/config/overview.mdx

@@ -0,0 +1,145 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="config" />
+
+# Overview
+
+Configuration refers to configuring the plugin in your `vitest.config.ts` file.
+
+You can configure the plugin by passing options to the `vis` function from `vitest-plugin-vis/config`.
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis()],
+})
+```
+
+## Customizing snapshot path
+
+Let's say you have this test:
+
+```ts
+// src/components/MyComponent.spec.tsx
+
+describe('MyComponent', () => {
+	describe('className', () => {
+		it('can customize className', () => {
+			// ...
+		})
+	})
+})
+```
+
+By default, when you run the test locally,the image snapshot will be saved in the following path:
+
+```sh
+__vis__/local/__baselines__/components/MyComponent.spec.tsx/MyComponent/className/can-customize-className-auto.png
+```
+
+This path can be broken down into a few parts:
+
+> `__vis__/local`: `snapshotRootDir`
+
+This is the `snapshotRootDir` where the image snapshots folders are placed.
+When running on CI, the `snapshotRootDir` is default 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 current test run images are saved,
+and a `__diffs__` folder where the diff images are saved if the comparison fails.
+
+> `components/MyComponent.spec.tsx`: `snapshotSubpath`
+
+This is part of the path based on the path of the test file relative to the project root.
+By default, the plugin will trim the common folder such as `src` or `test` from the path to reduce the path length.
+
+If you place your test files in multiple folders,
+such as in both `tests` and `src` folders,
+and they might have files with the same name and create conflicting snapshots,
+you can use `snapshotSubpath` to customize the snapshot sub-path to avoid conflicts.
+
+```ts
+// 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 will look like this:
+
+```ini
+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.
+This is not customizable.
+
+> `auto`: `snapshotKey`
+
+This is the key of the snapshot.
+In this case, it is `auto` because the snapshot is taken automatically at the end of the test.
+If you take a manual snapshot, the key will be `0`, `1`, etc.
+If you customize it when taking the snapshot,
+the global customization will not be used.
+
+You can customize the `snapshotRootDir`, `snapshotSubpath`, and `snapshotKey` with corresponding options:
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+import { vis, trimCommonFolder } 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',
+		})
+	]
+})
+```

package/src/{shared → config}/trim_common_folder.mdx

@@ -1,6 +1,6 @@
 import { Meta, Source } from "@storybook/addon-docs/blocks";
 
-<Meta title="vitest-plugin-vis/config/trimCommonFolder" />
+<Meta title="config/trimCommonFolder" />
 
 # trimCommonFolder
 

package/src/config/types.ts

@@ -34,23 +34,22 @@ export type VisOptions<M extends ComparisonMethod = 'pixel'> = (M extends 'ssim'
 		/**
 		 * Loads the `test.setupFiles` of the specified preset.
 		 *
-		 * Note:
-		 * - 'enable` is deprecated. Use `manual` for the same effect.
-		 * - 'none` is deprecated. Use `custom` for the same effect.
-		 *
 		 * @default 'auto'
-		 *
+		 * @deprecated 'enable' is deprecated. Use `manual` for the same effect.
+		 * @deprecated 'none' is deprecated. Use `custom` for the same effect.
 		 */
 		preset?: 'enable' | 'manual' | 'auto' | 'custom' | 'none' | undefined
 		/**
 		 * The snapshot folder relative to the root of the project.
 		 *
-		 * Default: `{projectRoot}/__vis__/{platform}`
+		 * @default "({ ci, platform }) => `__vis__/${ci ? platform : 'local'}`"
 		 */
 		snapshotRootDir?:
 			| string
 			| ((context: {
 					ci: boolean
+					rootDir: string
+					projectName?: string | undefined
 					browserName?: string | undefined
 					providerName: string
 					platform: string