vitest-plugin-vis 4.1.0 → 4.2.0

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/task/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/prepare_image_snapshot_comparison.ts

@@ -4,7 +4,7 @@ import type { PrepareImageSnapshotComparisonCommand } from '../../shared/command
 import type { ImageSnapshotComparisonInfo } from '../../shared/types.ts'
 import { file } from '../externals/file.ts'
 import { getProjectRoot } from '../project.ts'
-import { takeSnapshot, takeSnapshotByBrowser } from '../snapshot.ts'
+import { takeSnapshot } from '../snapshot.ts'
 import { snapshotWriter } from '../snapshot_writer.ts'
 import { visServerContext } from '../vis_server_context.ts'
 import type { ExtendedBrowserCommand } from '../vis_server_context.types.ts'
@@ -22,20 +22,20 @@ export const prepareImageSnapshotComparison: ExtendedBrowserCommand<
 	const info = await visServerContext.getSnapshotInfo(context, taskId, options)
 
 	const baselineBuffer = await file.tryReadFile(resolve(projectRoot, info.baselinePath))
-	if (!baselineBuffer) {
-		if (isBase64String(subject)) {
-			await snapshotWriter.writeBase64(resolve(projectRoot, info.baselinePath), subject)
-		} else {
-			await takeSnapshotByBrowser(context, projectRoot, info.baselinePath, subject, options)
+	if (!baselineBuffer && isBase64String(subject)) {
+		await snapshotWriter.writeBase64(resolve(projectRoot, info.resultPath), subject)
+		return {
+			...info,
+			projectRoot,
+			result: subject,
 		}
-		return
 	}
 
 	const resultBuffer = await takeSnapshot(context, projectRoot, info.resultPath, subject, options)
 	return {
 		...info,
 		projectRoot,
-		baseline: baselineBuffer.toString('base64'),
+		baseline: baselineBuffer?.toString('base64'),
 		result: resultBuffer.toString('base64'),
 	}
 }

package/src/server/commands/prepare_page_image_snapshot_comparison.ts

@@ -18,16 +18,11 @@ export const preparePageImageSnapshotComparison: ExtendedBrowserCommand<
 	const projectRoot = getProjectRoot(context)
 	const info = await visServerContext.getSnapshotInfo(context, taskId, options)
 	const baselineBuffer = await file.tryReadFile(resolve(projectRoot, info.baselinePath))
-	if (!baselineBuffer) {
-		await takePageSnapshot(context, projectRoot, info.baselinePath, options)
-		return
-	}
-
 	const resultBuffer = await takePageSnapshot(context, projectRoot, info.resultPath, options)
 	return {
 		...info,
 		projectRoot,
-		baseline: baselineBuffer.toString('base64'),
+		baseline: baselineBuffer?.toString('base64'),
 		result: resultBuffer.toString('base64'),
 	}
 }

package/src/server/snapshot_path.ts

@@ -6,12 +6,14 @@ import { trimCommonFolder } from '../shared/trim_common_folder.ts'
 import type { ExtendedBrowserCommandContext } from './vis_server_context.types.ts'
 
 export function resolveSnapshotRootDir(browserCommandContext: ExtendedBrowserCommandContext, options: VisOptions) {
-	if (!options.snapshotRootDir) return getSnapshotRootDir(SNAPSHOT_ROOT_DIR)
+	if (!options.snapshotRootDir) return getSnapshotRootDir()
 	const snapshotRootDir = options.snapshotRootDir
 	if (typeof snapshotRootDir === 'string') return getSnapshotRootDir(snapshotRootDir)
 	const { config } = browserCommandContext.project.browser
 	return snapshotRootDir({
 		ci,
+		rootDir: SNAPSHOT_ROOT_DIR,
+		projectName: browserCommandContext.project.name,
 		browserName: config.browser.name,
 		providerName: browserCommandContext.provider.name,
 		platform,

package/src/{setup.create_vis.mdx → setup/create_vis.mdx}

@@ -1,12 +1,11 @@
 import { Meta, Markdown ,Canvas} from "@storybook/addon-docs/blocks";
 
-<Meta
-tags={['deprecated']}
-title="vitest-plugin-vis/setup/createVis"
-/>
+<Meta title="setup/createVis" tags={['deprecated']} />
+
+# `createVis`
 
 🪦 Deprecated
 
 `createVis` in `vitest-plugin-vis/setup` is deprecated.
 
-It is moved to `/client-api`.
+It is moved to `vitest-plugin-vis/setup-api`.

package/src/setup/create_vis.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeAll, expect } from 'vitest'
+import { setAutoSnapshotOptions } from '../auto_snapshots/auto_snapshot_options.ts'
+import type { SnapshotMeta } from '../auto_snapshots/snapshot_meta.ts'
 import { autoSnapshotMatcher } from '../client/suite/auto_snapshot_matcher.ts'
-import { setAutoSnapshotOptions } from '../client/task/auto_snapshot_options.ts'
-import type { SnapshotMeta } from '../client/task/snapshot_meta.ts'
 import type { SetupVisSuiteCommand } from '../shared/commands.types.ts'
 import type { ComparisonMethod, SetupVisOptions } from '../shared/types.ts'
 
@@ -92,10 +92,19 @@ export type VisClientConfigurator<GM extends Record<string, any> | unknown = unk
 		): void
 	}
 	beforeAll: {
+		/**
+		 * @deprecated No known use case.
+		 */
 		setup(): Promise<void>
 	}
 	afterEach: {
+		/**
+		 * @deprecated No known use case.
+		 */
 		matchImageSnapshot(): Promise<void>
+		/**
+		 * @deprecated No known use case.
+		 */
 		matchPerTheme<C extends ComparisonMethod, M extends Record<string, any> | unknown = unknown>(
 			themes: Record<
 				string,
@@ -120,11 +129,7 @@ export function createVis<GM extends Record<string, any> | unknown = unknown>(co
 			}
 
 			if (typeof options?.auto === 'function') {
-				afterEach(
-					matcher.createMatcher({
-						auto: options.auto,
-					}),
-				)
+				afterEach(matcher.createMatcher({ auto: options.auto }))
 			} else if (typeof options?.auto === 'object') {
 				afterEach(matcher.createMatcher(options.auto))
 			} else {

package/src/setup/overview.mdx

@@ -0,0 +1,17 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="setup" />
+
+# Overview
+
+`vitest-plugin-vis/setup` provides the API to setup the plugin on the client side.
+
+It provides the API you needed in `vitest.setup.ts`.
+
+## Augmentation
+
+When you import `vitest-plugin-vis/setup`, it will augment `expect` and `page` to provide methods for visual testing.
+
+- `expect().toMatchImageSnapshot()`: Match the image snapshot.
+- `page.toMatchImageSnapshot()`: Match the image snapshot.
+- `page.hasImageSnapshot()`: Check if the image snapshot exists.

package/src/setup/readme.md

@@ -2,4 +2,6 @@
 
 Code in this directory is used to setup the plugin in `vitest.setup.ts`.
 
-The code is executed in a NodeJS main thread.
+The code is executed in Vitest browser runner worker.
+
+This worker is running on a headless chrome with `window.name` set to `vitest-iframe`.