vitest-plugin-vis 4.0.0 → 4.2.0

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

package/src/config/vis.mdx

@@ -0,0 +1,313 @@
+import { Meta, Source } from "@storybook/addon-docs/blocks";
+
+<Meta title="config/vis" />
+
+# `vis`
+
+`vis` from `vitest-plugin-vis/config` is the Vitest plugin of `vitest-plugin-vis`.
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis()],
+})
+```
+
+It provides a lot of options to customize the behavior of the plugin.
+(You can learn more about the default configuration [here](/docs/overview--docs#basic-configuration).)
+
+## `preset`
+
+The `preset` option set up typical visual testing strategies.
+
+### `auto`
+
+The `auto` preset is the default preset.
+It will take a snapshot of the page at the end of each rendering test.
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({ preset: 'auto' })],
+})
+```
+
+### `manual`
+
+The `manual` preset is for manual testing.
+It will not take any snapshot automatically.
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({ preset: 'manual' })],
+})
+```
+
+See [Manual Snapshot](/docs/expect-tomatchimagesnapshot--docs) section on how to take an image snapshot manually.
+
+### `custom`
+
+The `custom` preset is for advanced users.
+It will not take any snapshot automatically.
+You need to set up your own visual testing strategy in `vitest.setup.ts`.
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({ preset: 'custom' })],
+	test: {
+		// Set up your own visual testing strategy in `vitest.setup.ts`.
+		setupFiles: ['./vitest.setup.ts'],
+	}
+})
+```
+
+When using the `custom` preset,
+you need to set up your own visual testing strategy in `vitest.setup.ts` using the [vis](?path=/docs/setup-vis--docs) function from `vitest-plugin-vis/setup`.
+
+## `subject`
+
+By default, the snapshot is taken from the `document.body` element.
+
+If you establish a common pattern in your tests,
+you can customize the subject to snapshot by setting the `subject` option.
+
+
+For example, if you enforce a `data-testid` attribute on the element you want to snapshot,
+you can use the `subject` option to specify the selector:
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({ subject: '[data-testid="subject"]' })]
+})
+```
+
+## `snapshotRootDir`
+
+By default, the snapshot is saved in the `__vis__` folder relative to the project root.
+
+If you want to save the snapshot in a different folder,
+you can set the `snapshotRootDir` option.
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [
+		vis({
+			// save the snapshot in the `<projectRoot>/custom` folder
+			snapshotRootDir: 'custom'
+		})
+	]
+})
+```
+
+Beside providing a static path,
+you can also provide a function to dynamically determine the snapshot root directory based on the context.
+
+The function receives the following context:
+
+- `ci`: Whether the code is running in a CI environment
+- `platform`: The platform string (e.g., 'linux', 'darwin', 'win32')
+- `browserName`: The name of the browser (e.g., 'chromium', 'firefox', etc.)
+- `providerName`: The name of the provider (e.g., 'playwright', 'webdriverio', etc.)
+- `screenshotFailures`: Whether the screenshot failures are enabled
+- `screenshotDirectory`: The directory to save the screenshot
+
+By default, we provide this function:
+
+```ts
+({ ci, platform }) => `__vis__/${ci ? platform : 'local'}
+```
+
+## `snapshotSubpath`
+
+Customize the snapshot subpath.
+
+By default, we provide this function: `({ subpath }) => trimCommonFolder(subpath)`
+
+The `trimCommonFolder` function is also provided if you want to use it in your own custom function.
+
+## `snapshotKey`
+
+`snapshotKey` specifies the key of the snapshot.
+In the context of `vis()`, `snapshotKey` is used to specify the key of the auto snapshot.
+
+By default, the `snapshotKey` is `auto`.
+
+[vitest-plugin-vis]: https://npmjs.org/package/vitest-plugin-vis
+
+## `comparisonMethod`
+
+`comparisonMethod` specifies the method of the comparison.
+By default, the `comparisonMethod` is `pixel`.
+
+If you want to use the `ssim` method,
+you can set the `comparisonMethod` option.
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({ comparisonMethod: 'ssim' })]
+})
+```
+
+## `diffOptions`
+
+`diffOptions` specifies the options of the comparison.
+It accepts different options based on the `comparisonMethod`.
+
+### Pixel Comparison
+
+For `pixel` comparison, it accepts the options of `pixelmatch`:
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({
+		comparisonMethod: 'pixelmatch',
+		diffOptions: {
+			threshold: 0.1,        // Matching threshold (0-1), default: 0.1
+			includeAA: false,      // Include anti-aliased pixels in comparison
+			alpha: 0.1,            // Blending factor of unchanged pixels
+			aaColor: [255, 255, 0], // Color of anti-aliased pixels in diff
+			diffColor: [255, 0, 255] // Color of different pixels in diff
+		}
+	})],
+})
+```
+
+For option details, please refer to the [pixelmatch documentation](https://github.com/mapbox/pixelmatch?tab=readme-ov-file#pixelmatchimg1-img2-output-width-height-options).
+
+### SSIM Comparison
+
+Sometimes pixel-perfect isn't what you need. If you're working with images that have gradients, shadows, or anti-aliasing, SSIM (Structural Similarity Index) might be a better fit.
+It's designed to match how humans actually perceive image differences, which means fewer false positives when minor rendering differences don't actually matter.
+For `ssim` comparison, it accepts the options of `ssim`:
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({
+		comparisonMethod: 'ssim',
+		diffOptions: {
+			ssim: 'bezkrovny',  // 'bezkrovny' (fast, default) | 'fast' (accurate) | 'weber' | 'original'
+			windowSize: 11,     // Window size for SSIM calculation (default: 11)
+			k1: 0.01,          // First stability constant (default: 0.01)
+			k2: 0.03,          // Second stability constant (default: 0.03)
+			bitDepth: 8,       // Bits per channel (default: 8)
+			downsample: 'original' // 'original' | 'fast' | false
+		}
+	})],
+})
+```
+
+For option details, please refer to the [ssim documentation](https://github.com/obartra/ssim).
+Note that `ssim.js` repository indicates it is archived.
+If there is any issue with `ssim` comparison,
+it may not be fixed.
+
+## Failure Thresholds
+
+Sometimes you want a bit of flexibility in your tests. That's where failure thresholds come in! They let you decide how much difference is acceptable before a test fails.
+
+### Pixel-Based Threshold
+
+If you know roughly how many pixels might differ (maybe due to font rendering differences across platforms), you can set a specific pixel count. This is great when you have a good sense of what "acceptable difference" means in pixels.
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({
+		failureThreshold: 100,        // Allow 100 pixels to differ
+		failureThresholdType: 'pixel' // Default: 'pixel'
+	})],
+})
+```
+
+### Percentage-Based Threshold
+
+Percentage-based thresholds are often more intuitive, especially when you're working with different image sizes. Instead of thinking "100 pixels," you can think "2% of the image," which scales better across different screen sizes and resolutions.
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({
+		failureThreshold: 0.05,        // Allow 5% of pixels to differ
+		failureThresholdType: 'percent'
+	})],
+})
+```
+
+### Pixel-Perfect Comparison
+
+When you need absolute precision—maybe you're testing critical UI components or want to catch the tiniest visual regressions—pixel-perfect comparison is your go-to. This is the default behavior and ensures that any pixel difference will be caught.
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({
+		failureThreshold: 0,
+		failureThresholdType: 'pixel'
+	})],
+})
+```
+
+## Timeout Configuration
+
+Sometimes your tests need a bit more time to render, especially if you're working with complex components or slower environments. You can adjust the timeout to give your tests the breathing room they need.
+
+### Custom Timeout
+
+If you find your tests are timing out, or if you're working with particularly complex components that take longer to render, you can increase the timeout. The default is 30 seconds, but feel free to adjust it based on your needs.
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({
+		timeout: 60000 // 60 seconds (default: 30000ms)
+	})],
+})
+```
+
+### Quick Timeout for Fast Tests
+
+On the flip side, if you know your tests are quick and you want faster feedback, you can reduce the timeout. This helps catch issues faster and keeps your test suite snappy!
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({
+		timeout: 5000 // 5 seconds
+	})],
+})
+```

package/src/index.ts

@@ -2,5 +2,5 @@
 import './client/expect/augment.ts'
 import './client/page/augment.ts'
 
-export { setAutoSnapshotOptions, type MetaTask } from './client/auto_snapshot_options.ts'
+export * from './auto_snapshots/auto_snapshot_options.ts'
 export type * from './shared/types.ts'

package/src/overview.mdx

@@ -4,19 +4,28 @@ import { Meta, Markdown } from "@storybook/addon-docs/blocks";
 
 # Vitest Visual Testing Plugin
 
-[vitest-plugin-vis] provides visual testing for [Vitest] when running in [Browser Mode][browser-mode].
+[vitest-plugin-vis] provides visual testing for tests running in [Vitest Browser Mode][vitest-browser-mode].
 
-It offers a new unique features:
+Vitest 4 adds [Visual Regression Test][visual-regression-test] support natively.
+You can choose which method to use based on your needs.
 
-- You can capture and compare image snapshot both automatically and manually.
-- You can take a snapshot of the whole page or a specific component.
-- You can take snapshots in different environments, platform, browser, screen size and themes.
-- The snapshots are stored locally in the `__vis__` directory.
-- You can enable, disable, and customize how the snapshots are taken and compared.
+Here is a comparison of the features between [Vitest Visual Regression Test][visual-regression-test] and [vitest-plugin-vis].
+
+| Feature | [Vitest Visual Regression Test][visual-regression-test] | [vitest-plugin-vis] |
+| ------- | -------------------------------------------------- | ------------------- |
+| Manual snapshot creation | ✅ | ✅ |
+| Automatic snapshot creation | ❌ | ✅ |
+| Multi-theme snapshots | ❌ | ✅ |
+| Comparison methods | `pixel`, `ssim`, custom | `pixel`, `ssim` |
+| Threshold customization | ✅ | ✅ |
+| Fine-grained snapshot variations | ❌ | ✅ |
+| Masking elements | ✅ | 🚧 |
 
 ## Install
 
-[vitest-plugin-vis] works with Vitest 2.0.0 or later.
+[vitest-plugin-vis] works with Vitest 2 or later.
+
+For Vitest 2 or 3, please use [vitest-plugin-vis] v3.
 
 ```sh
 npm install --save-dev vitest-plugin-vis
@@ -28,7 +37,15 @@ yarn add --save-dev vitest-plugin-vis
 
 ## Basic Configuration
 
-To use [vitest-plugin-vis], you need to add it to your Vitest configuration.
+To use [vitest-plugin-vis], you need to:
+
+- Add the `vis` plugin to your Vitest configuration.
+- Update `.gitignore` for the snapshot directories.
+- Update your TypeScript configuration to include the `vitest-plugin-vis` type.
+
+### Vitest Configuration
+
+The [vitest-plugin-vis] plugin can be used without customization.
 
 ```ts
 // vitest.config.ts
@@ -38,40 +55,27 @@ import { vis } from 'vitest-plugin-vis/config'
 export default defineConfig({
 	plugins: [vis()],
 	test: {
-		// vitest v2
-		browser: {
-			enabled: true,
-			provider: 'playwright',
-			name: 'chromium',
-		},
-		// vitest v3
-		browser: {
-			enabled: true,
-			provider: 'playwright',
-			instances: [
-				{ browser: 'chromium' }
-			]
-		}
+		// ... your Vitest Browser Mode configuration ...
 	}
 })
 ```
 
 This default configuration will:
 
-- Use the `auto` preset, taking image snapshot at the end on each rendering test.
+- Use the [auto preset](?path=/docs/configuration--docs#auto-preset), taking image snapshot at the end on each rendering test.
 - Use `pixelmatch` as the image comparison method.
 - Set config to compare image snapshot with a failure threshold of `0 pixels`.
 - Timeout for image comparison is set to `30000 ms`.
 - Save image snapshots in the `<project-root>/__vis__` directory.
 
-## Update .gitignore
+### Update .gitignore
 
 By default, [vitest-plugin-vis] will save image snapshots in the `<project-root>/__vis__` directory.
 
 Under this directory, you will find different set of snapshots for different environments:
 
 - `local`: For snapshots taken locally.
-- `<platform: ubuntu | darwin | win32>`: Fom snapshots taken in respective CI.
+- `<platform: ubuntu | darwin | win32>`: For snapshots taken in respective CI.
 
 In each platform directory, there are 3 directories:
 
@@ -87,6 +91,40 @@ Because of that, you should add the following lines to your `.gitignore` file:
 **/__vis__/**/__results__
 ```
 
-[browser-mode]: https://vitest.dev/guide/browser
+### TypeScript Configuration
+
+If you want to do manual snapshot testing, you need to tell TypeScript about the matcher.
+
+Add the following to your `tsconfig.json`:
+
+```jsonc
+{
+	"compilerOptions": {
+		"types": ["vitest-plugin-vis"]
+	}
+}
+```
+
+## Advanced Configuration
+
+[Vitest Browser Mode][vitest-browser-mode] is a mode that allows you to run tests in a browser environment.
+It has two parts: the Node.js side and the browser side.
+
+It runs a worker in Node.js environment and starts a browser instance using provider such as [Playwright][playwright] or [WebDriverIO][webdriverio].
+It then runs the tests in the browser environment and controls the browser instance remotely through the provider.
+
+For [vitest-plugin-vis], we run code on the Node.js side to load and save the image snapshots,
+ask the provider to take screenshots,
+and on the browser side we provides API to take snapshots.
+
+The Node.js side is configured in your `vitest.config.ts` file,
+while the browser side is configured in your `vitest.setup.ts` file.
+
+Please check out the documentation for [Config](?path=/docs/config-vis--docs) and [Setup](?path=/docs/setup-vis--docs) for more details.
+
 [vitest]: https://vitest.dev
-[vitest-plugin-vis]: https://npmjs.org/package/vitest-plugin-vis
+[vitest-browser-mode]: https://vitest.dev/guide/browser
+[vitest-plugin-vis]: https://npmjs.org/package/vitest-plugin-vis
+[playwright]: https://playwright.dev/
+[webdriverio]: https://webdriver.io/
+[visual-regression-test]: https://vitest.dev/guide/browser/visual-regression-testing.html

package/src/server/commands/augment.ts

@@ -1,9 +1,11 @@
-import type { HasImageSnapshotCommand } from './has_image_snapshot.ts'
-import type { ImageSnapshotNextIndexCommand } from './image_snapshot_next_index.ts'
-import type { LoadImageSnapshotResultsCommand } from './load_image_snapshot_results.ts'
-import type { PrepareImageSnapshotComparisonCommand } from './prepare_image_snapshot_comparison.ts'
-import type { PreparePageImageSnapshotComparisonCommand } from './prepare_page_image_snapshot_comparison.ts'
-import type { SetupVisSuiteCommand } from './setup_vis_suite.ts'
+import type {
+	HasImageSnapshotCommand,
+	ImageSnapshotNextIndexCommand,
+	LoadImageSnapshotResultsCommand,
+	PrepareImageSnapshotComparisonCommand,
+	PreparePageImageSnapshotComparisonCommand,
+	SetupVisSuiteCommand,
+} from '../../shared/commands.types.ts'
 
 declare module 'vitest/browser' {
 	interface BrowserCommands

package/src/server/commands/has_image_snapshot.ts

@@ -1,11 +1,8 @@
+import type { HasImageSnapshotCommand } from '../../shared/commands.types.ts'
 import { visServerContext } from '../vis_server_context.ts'
 import type { ExtendedBrowserCommand } from '../vis_server_context.types.ts'
 import { assertTestPathDefined } from './_assertions.ts'
 
-export interface HasImageSnapshotCommand {
-	hasImageSnapshot(taskId: string, snapshotKey: string | undefined): Promise<boolean>
-}
-
 export const hasImageSnapshot: ExtendedBrowserCommand<Parameters<HasImageSnapshotCommand['hasImageSnapshot']>> = async (
 	context,
 	taskId,

package/src/server/commands/image_snapshot_next_index.ts

@@ -1,14 +1,8 @@
+import type { ImageSnapshotNextIndexCommand } from '../../shared/commands.types.ts'
 import { visServerContext } from '../vis_server_context.ts'
 import type { ExtendedBrowserCommand } from '../vis_server_context.types.ts'
 import { assertTestPathDefined } from './_assertions.ts'
 
-export interface ImageSnapshotNextIndexCommand {
-	/**
-	 * Get the index of the snapshot image to be created.
-	 */
-	imageSnapshotNextIndex(taskId: string): Promise<number>
-}
-
 export const imageSnapshotNextIndex: ExtendedBrowserCommand<
 	Parameters<ImageSnapshotNextIndexCommand['imageSnapshotNextIndex']>
 > = async (context, taskId) => {