vitest-plugin-vis 3.1.0 → 3.3.0

package/src/client/page/to_match_image_snapshot.mdx

@@ -0,0 +1,471 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="page/toMatchImageSnapshot" />
+
+# page.toMatchImageSnapshot
+
+`page.toMatchImageSnapshot()` is a method that captures and compares full page or viewport screenshots against baseline images.
+
+Unlike `expect().toMatchImageSnapshot()` which targets specific elements, `page.toMatchImageSnapshot()` is designed for capturing entire pages or viewports, making it ideal for full-page visual regression testing.
+
+## Basic Usage
+
+```ts
+import { page } from '@vitest/browser/context'
+
+it('should take a page snapshot', async () => {
+	// Your test setup here
+	render(<MyApp />)
+
+	// Take a viewport snapshot
+	await page.toMatchImageSnapshot()
+})
+```
+
+## Options
+
+The `page.toMatchImageSnapshot()` method accepts an optional options object with the following properties:
+
+### Page Capture Options
+
+#### `fullPage`
+
+Capture the entire page including content below the fold, not just the visible viewport.
+
+```ts
+it('should capture full page', async () => {
+	render(<LongPageContent />)
+
+	// Capture the entire scrollable page
+	await page.toMatchImageSnapshot({
+		fullPage: true
+	})
+})
+
+it('should capture viewport only', async () => {
+	render(<LongPageContent />)
+
+	// Capture only the visible viewport (default)
+	await page.toMatchImageSnapshot({
+		fullPage: false // default
+	})
+})
+```
+
+### Snapshot Identification
+
+#### `snapshotKey`
+
+Customize the snapshot key/name for the snapshot file.
+
+```ts
+it('should use custom snapshot key', async () => {
+	render(<MyApp />)
+
+	await page.toMatchImageSnapshot({
+		snapshotKey: 'homepage_layout'
+	})
+})
+```
+
+### Failure Threshold
+
+#### `failureThreshold` and `failureThresholdType`
+
+Control how much difference is allowed before the test fails.
+
+```ts
+// Allow up to 100 pixels to be different
+it('should allow pixel differences', async () => {
+	render(<MyApp />)
+
+	await page.toMatchImageSnapshot({
+		failureThreshold: 100,
+		failureThresholdType: 'pixel' // default
+	})
+})
+
+// Allow up to 0.5% difference
+it('should allow percentage differences', async () => {
+	render(<MyApp />)
+
+	await page.toMatchImageSnapshot({
+		failureThreshold: 0.005,
+		failureThresholdType: 'percent'
+	})
+})
+```
+
+### Comparison Methods
+
+#### `comparisonMethod`
+
+Choose between pixel-by-pixel comparison or structural similarity comparison.
+
+```ts
+// Default pixel comparison
+it('should use pixel comparison', async () => {
+	render(<MyApp />)
+
+	await page.toMatchImageSnapshot({
+		comparisonMethod: 'pixel' // default
+	})
+})
+
+// SSIM (Structural Similarity) comparison
+it('should use SSIM comparison', async () => {
+	render(<MyApp />)
+
+	await page.toMatchImageSnapshot({
+		comparisonMethod: 'ssim'
+	})
+})
+```
+
+### Diff Options
+
+#### `diffOptions` for Pixel Comparison
+
+When using `comparisonMethod: 'pixel'` (default), you can customize pixelmatch options:
+
+```ts
+it('should use custom pixel diff options', async () => {
+	render(<MyApp />)
+
+	await page.toMatchImageSnapshot({
+		comparisonMethod: 'pixel',
+		diffOptions: {
+			threshold: 0.1,           // Matching threshold (0-1, default: 0.1)
+			includeAA: false,         // Include anti-aliased pixels (default: false)
+			alpha: 0.1,              // Blending factor for unchanged pixels (default: 0.1)
+			aaColor: [255, 255, 0],  // Color for anti-aliased pixels [R, G, B]
+			diffColor: [255, 0, 0],  // Color for different pixels [R, G, B]
+			diffColorAlt: null,      // Alternative color for dark-on-light differences
+			diffMask: false          // Draw diff over transparent background (default: false)
+		}
+	})
+})
+```
+
+#### `diffOptions` for SSIM Comparison
+
+When using `comparisonMethod: 'ssim'`, you can customize SSIM options:
+
+```ts
+it('should use custom SSIM diff options', async () => {
+	render(<MyApp />)
+
+	await page.toMatchImageSnapshot({
+		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
+		}
+	})
+})
+```
+
+### Timeout
+
+#### `timeout`
+
+Set a timeout for taking the snapshot.
+
+```ts
+it('should use custom timeout', async () => {
+	render(<MyApp />)
+
+	await page.toMatchImageSnapshot({
+		timeout: 60000 // 60 seconds (default: 30000ms)
+	})
+})
+```
+
+### Testing Utilities
+
+#### `expectToFail`
+
+Expect the matcher to fail - useful for testing that changes are detected.
+
+```ts
+it('should detect page differences', async () => {
+	render(<MyApp />)
+
+	// First, create the baseline
+	if (!(await page.hasImageSnapshot({ snapshotKey: 'page_changes' }))) {
+		await page.toMatchImageSnapshot({
+			snapshotKey: 'page_changes'
+		})
+		return
+	}
+
+	// Modify the page
+	document.body.style.backgroundColor = 'red'
+
+	// Expect the test to fail due to changes
+	await page.toMatchImageSnapshot({
+		snapshotKey: 'page_changes',
+		expectToFail: true
+	})
+	.then(
+		() => {
+			throw new Error('Should not reach - expected failure')
+		},
+		(error) => {
+			expect(error.message).toMatch(/Expected image to match but was differ by \d+ pixels/)
+		}
+	)
+})
+```
+
+## Complete Example
+
+Here's a comprehensive example showing multiple options:
+
+```ts
+it('should demonstrate all page snapshot options', async () => {
+	render(<MyComplexApp />)
+
+	await page.toMatchImageSnapshot({
+		// Page capture
+		fullPage: true,
+
+		// Snapshot identification
+		snapshotKey: 'full_app_layout',
+
+		// Failure threshold
+		failureThreshold: 0.01,
+		failureThresholdType: 'percent',
+
+		// Comparison method
+		comparisonMethod: 'ssim',
+
+		// SSIM-specific options
+		diffOptions: {
+			ssim: 'bezkrovny',
+			windowSize: 11,
+			k1: 0.01,
+			k2: 0.03
+		},
+
+		// Timeout
+		timeout: 45000,
+
+		// Testing utility
+		expectToFail: false
+	})
+})
+```
+
+## Use Cases
+
+### Full Page Layout Testing
+
+Perfect for testing complete page layouts, including content below the fold:
+
+```ts
+it('should capture entire homepage layout', async () => {
+	render(<Homepage />)
+
+	await page.toMatchImageSnapshot({
+		fullPage: true,
+		snapshotKey: 'homepage_complete',
+		failureThreshold: 0.01,
+		failureThresholdType: 'percent'
+	})
+})
+```
+
+### Viewport Testing
+
+Test how your application appears in the current viewport:
+
+```ts
+it('should capture above-the-fold content', async () => {
+	render(<LandingPage />)
+
+	await page.toMatchImageSnapshot({
+		fullPage: false, // default - viewport only
+		snapshotKey: 'landing_viewport'
+	})
+})
+```
+
+### Responsive Design Testing
+
+Test different viewport sizes by combining with browser configuration:
+
+```ts
+it('should test mobile layout', async () => {
+	// Assuming viewport is configured for mobile in test setup
+	render(<ResponsiveApp />)
+
+	await page.toMatchImageSnapshot({
+		snapshotKey: 'mobile_layout',
+		fullPage: true
+	})
+})
+```
+
+### Cross-Browser Consistency
+
+Ensure consistent rendering across different browsers:
+
+```ts
+it('should render consistently across browsers', async () => {
+	render(<CrossBrowserApp />)
+
+	await page.toMatchImageSnapshot({
+		snapshotKey: 'cross_browser_test',
+		comparisonMethod: 'ssim', // More forgiving for browser differences
+		failureThreshold: 0.02,
+		failureThresholdType: 'percent'
+	})
+})
+```
+
+## Comparison Method Recommendations
+
+### When to use Pixel Comparison (`comparisonMethod: 'pixel'`)
+
+- **Default choice** for most page-level visual regression tests
+- **Precise detection** of layout shifts, color changes, and text modifications
+- **Good for** detecting critical visual regressions
+- **Fast execution** for most page sizes
+
+### When to use SSIM Comparison (`comparisonMethod: 'ssim'`)
+
+- **Structural similarity** comparison that's more forgiving of minor rendering differences
+- **Reduced false positives** from browser-specific rendering variations
+- **Better for** pages with complex graphics, gradients, or anti-aliased content
+- **Recommended for** cross-browser testing where minor pixel differences are expected
+
+```ts
+// Recommended SSIM configuration for page testing
+it('should use recommended SSIM settings for pages', async () => {
+	render(<MyApp />)
+
+	await page.toMatchImageSnapshot({
+		comparisonMethod: 'ssim',
+		failureThreshold: 0.01,
+		failureThresholdType: 'percent',
+		diffOptions: {
+			ssim: 'bezkrovny' // Fast and accurate for most cases
+		}
+	})
+})
+```
+
+## Best Practices
+
+### 1. Use Descriptive Snapshot Keys
+
+```ts
+// Good
+await page.toMatchImageSnapshot({
+	snapshotKey: 'dashboard_with_data_loaded'
+})
+
+// Better
+await page.toMatchImageSnapshot({
+	snapshotKey: 'user_dashboard_logged_in_state'
+})
+```
+
+### 2. Consider Page Loading States
+
+```ts
+it('should wait for page to be fully loaded', async () => {
+	render(<AsyncApp />)
+
+	// Wait for async content to load
+	await page.waitForSelector('[data-testid="content-loaded"]')
+
+	await page.toMatchImageSnapshot({
+		snapshotKey: 'fully_loaded_page'
+	})
+})
+```
+
+### 3. Use Appropriate Failure Thresholds
+
+```ts
+// For critical UI elements - strict comparison
+await page.toMatchImageSnapshot({
+	snapshotKey: 'critical_layout',
+	failureThreshold: 0 // No differences allowed
+})
+
+// For pages with dynamic content - more lenient
+await page.toMatchImageSnapshot({
+	snapshotKey: 'dynamic_content_page',
+	failureThreshold: 0.5,
+	failureThresholdType: 'percent'
+})
+```
+
+### 4. Choose Full Page vs Viewport Strategically
+
+```ts
+// Use fullPage for complete layout testing
+await page.toMatchImageSnapshot({
+	fullPage: true,
+	snapshotKey: 'complete_article_layout'
+})
+
+// Use viewport for above-the-fold testing
+await page.toMatchImageSnapshot({
+	fullPage: false,
+	snapshotKey: 'hero_section'
+})
+```
+
+## Limitations
+
+### Concurrent Tests
+
+`page.toMatchImageSnapshot()` cannot be used in concurrent tests as they share the same browser environment:
+
+```ts
+// ❌ This will throw an error
+it.concurrent('concurrent test', async () => {
+	await page.toMatchImageSnapshot() // Error: cannot be called in concurrent test
+})
+
+// ✅ Use regular tests instead
+it('sequential test', async () => {
+	await page.toMatchImageSnapshot() // Works fine
+})
+```
+
+### WebDriverIO Considerations
+
+When using WebDriverIO as the browser provider:
+
+- `fullPage` option may not work correctly in headless mode
+- Consider setting explicit window size in configuration
+- Playwright is recommended for more reliable visual testing
+
+```ts
+// vitest.config.ts - WebDriverIO workaround
+export default {
+	test: {
+		browser: {
+			instances: [
+				{
+					browser: 'chrome',
+					capabilities: {
+						'goog:chromeOptions': {
+							args: ['--window-size=1280,720']
+						}
+					}
+				}
+			]
+		}
+	}
+}
+```

package/src/client-api.ts

@@ -7,6 +7,7 @@ export * from './client/actions/match_page_image_snapshot_action.ts'
 export { setAutoSnapshotOptions, type MetaTask } from './client/auto_snapshot_options.ts'
 export * from './client/expect/expectation_result.ts'
 export type * from './client/expect/to_match_image_snapshot.types.ts'
+export * from './client/setup/create_vis.ts'
 export * from './client/task_id.ts'
 export * from './shared/constants.ts'
 export type * from './shared/types.ts'

package/src/config/types.ts

@@ -34,12 +34,14 @@ 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.
+		 * Note:
+		 * - 'enable` is deprecated. Use `manual` for the same effect.
+		 * - 'none` is deprecated. Use `custom` for the same effect.
 		 *
 		 * @default 'auto'
 		 *
 		 */
-		preset?: 'enable' | 'manual' | 'auto' | 'none' | undefined
+		preset?: 'enable' | 'manual' | 'auto' | 'custom' | 'none' | undefined
 		/**
 		 * The snapshot folder relative to the root of the project.
 		 *

package/src/config/vis.ts

@@ -23,7 +23,7 @@ export function vis<M extends ComparisonMethod = 'pixel'>(options: VisOptions<M>
 						name: undefined as unknown as string,
 						commands,
 					},
-					setupFiles: preset && preset !== 'none' ? [`vitest-plugin-vis/presets/${preset}`] : [],
+					setupFiles: preset && preset !== 'none' && preset !== 'custom' ? [`vitest-plugin-vis/presets/${preset}`] : [],
 				},
 			}
 		},

package/src/config.vis.mdx

@@ -0,0 +1,76 @@
+import { Meta, Source } from "@storybook/addon-docs/blocks";
+
+<Meta title="vitest-plugin-vis/config/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 can set up your own visual testing strategy in `vitest.setup.ts` using the [vis](/docs/vitest-plugin-vis-setup-vis--docs) object from `vitest-plugin-vis/setup`.
+
+[vitest-plugin-vis]: https://npmjs.org/package/vitest-plugin-vis
+
+

package/src/overview.mdx

@@ -0,0 +1,92 @@
+import { Meta, Markdown } from "@storybook/addon-docs/blocks";
+
+<Meta title="Overview" />
+
+# Vitest Visual Testing Plugin
+
+[vitest-plugin-vis] provides visual testing for [Vitest] when running in [Browser Mode][browser-mode].
+
+It offers a new unique features:
+
+- 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.
+
+## Install
+
+[vitest-plugin-vis] works with Vitest 2.0.0 or later.
+
+```sh
+npm install --save-dev vitest-plugin-vis
+
+pnpm add --save-dev vitest-plugin-vis
+
+yarn add --save-dev vitest-plugin-vis
+```
+
+## Basic Configuration
+
+To use [vitest-plugin-vis], you need to add it to your Vitest configuration.
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+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' }
+			]
+		}
+	}
+})
+```
+
+This default configuration will:
+
+- Use the `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
+
+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.
+
+In each platform directory, there are 3 directories:
+
+- `__baselines__`: The directory for the baseline snapshots. This should be committed to the repository (except for `local`).
+- `__results__`: The directory for the current snapshots created when Vitest runs.
+- `__diffs__`: The directory for the diffs between the current snapshot and the baseline snapshot.
+
+Because of that, you should add the following lines to your `.gitignore` file:
+
+```gitignore
+**/__vis__/local
+**/__vis__/**/__diffs__
+**/__vis__/**/__results__
+```
+
+[browser-mode]: https://vitest.dev/guide/browser
+[vitest]: https://vitest.dev
+[vitest-plugin-vis]: https://npmjs.org/package/vitest-plugin-vis

package/src/server/snapshot_path.ts

@@ -19,7 +19,15 @@ export function resolveSnapshotRootDir(browserCommandContext: PartialBrowserComm
 	})
 }
 
-function getSnapshotRootDir(snapshotRootDir: string) {
+/**
+ * Gets the root directory for storing snapshots.
+ *
+ * @param snapshotRootDir - Base directory for snapshots. Defaults to `__vis__`.
+ * @returns The full snapshot root directory path, which includes a platform-specific subdirectory:
+ * - When running in CI: `<snapshotRootDir>/<platform>` (e.g. `__vis__/linux`)
+ * - When running locally: `<snapshotRootDir>/local`
+ */
+export function getSnapshotRootDir(snapshotRootDir = SNAPSHOT_ROOT_DIR) {
 	return `${snapshotRootDir}/${ci ? platform : 'local'}`
 }
 

package/src/server-utils.ts

@@ -1,2 +1,3 @@
+export { getSnapshotRootDir } from './server/snapshot_path.ts'
 export * from './shared/constants.ts'
 export * from './shared/trim_common_folder.ts'

package/src/setup.create_vis.mdx

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