vitest-plugin-vis 3.1.0 → 3.3.0

package/src/client/expect/to_match_image_snapshot.mdx

@@ -0,0 +1,298 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="expect/toMatchImageSnapshot" />
+
+# toMatchImageSnapshot
+
+`expect().toMatchImageSnapshot()` is a custom matcher that compares the current DOM to a snapshot image.
+
+It can be used whether you have enabled the `auto` preset or not.
+
+But typically, you would disable the auto snapshot when doing manual snapshot testing.
+
+You can disable the auto snapshot at various levels:
+
+```ts
+// vitest.setup.ts
+import { vis } from 'vitest-plugin-vis/setup'
+
+// Setup without auto snapshots
+vis.setup()
+```
+
+```ts
+// some.test.ts
+import { setAutoSnapshotOptions } from 'vitest-plugin-vis'
+
+beforeAll(() => {
+	setAutoSnapshotOptions(false)
+})
+
+beforeEach(() => {
+	setAutoSnapshotOptions(false)
+})
+
+it('...', () => {
+	setAutoSnapshotOptions(false)
+})
+```
+
+## Basic Usage
+
+```ts
+// some.test.ts
+import { setAutoSnapshotOptions } from 'vitest-plugin-vis'
+
+it('should take snapshot manually', async ({ expect }) => {
+	// Your test code here
+	render(<MyComponent />)
+
+	// Manual snapshot
+	await expect(document.body).toMatchImageSnapshot()
+})
+```
+
+## Options
+
+The `toMatchImageSnapshot()` matcher accepts an optional options object with the following properties:
+
+### Snapshot Identification
+
+#### `snapshotKey`
+
+Customize the snapshot key/name for the snapshot file.
+
+```ts
+it('should use custom snapshot key', async ({ expect }) => {
+	render(<MyComponent />)
+
+	await expect(document.body).toMatchImageSnapshot({
+		snapshotKey: 'my_custom_snapshot'
+	})
+})
+```
+
+### Failure Threshold
+
+#### `failureThreshold` and `failureThresholdType`
+
+Control how much difference is allowed before the test fails.
+
+```ts
+// Allow up to 50 pixels to be different
+it('should allow pixel differences', async ({ expect }) => {
+	render(<MyComponent />)
+
+	await expect(document.body).toMatchImageSnapshot({
+		failureThreshold: 50,
+		failureThresholdType: 'pixel' // default
+	})
+})
+
+// Allow up to 1% difference
+it('should allow percentage differences', async ({ expect }) => {
+	render(<MyComponent />)
+
+	await expect(document.body).toMatchImageSnapshot({
+		failureThreshold: 0.01,
+		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 ({ expect }) => {
+	render(<MyComponent />)
+
+	await expect(document.body).toMatchImageSnapshot({
+		comparisonMethod: 'pixel' // default
+	})
+})
+
+// SSIM (Structural Similarity) comparison
+it('should use SSIM comparison', async ({ expect }) => {
+	render(<MyComponent />)
+
+	await expect(document.body).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 ({ expect }) => {
+	render(<MyComponent />)
+
+	await expect(document.body).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 ({ expect }) => {
+	render(<MyComponent />)
+
+	await expect(document.body).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 ({ expect }) => {
+	render(<MyComponent />)
+
+	await expect(document.body).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 differences', async ({ expect }) => {
+	render(<MyComponent />)
+
+	// First, create the baseline
+	if (!(await page.hasImageSnapshot({ snapshotKey: 'test_changes' }))) {
+		await expect(document.body).toMatchImageSnapshot({
+			snapshotKey: 'test_changes'
+		})
+		return
+	}
+
+	// Modify the component
+	document.body.style.backgroundColor = 'red'
+
+	// Expect the test to fail due to changes
+	await expect(document.body)
+		.toMatchImageSnapshot({
+			snapshotKey: 'test_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 options', async ({ expect }) => {
+	render(<MyComponent />)
+
+	await expect(document.body).toMatchImageSnapshot({
+		// Snapshot identification
+		snapshotKey: 'comprehensive_test',
+
+		// 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
+	})
+})
+```
+
+## Comparison Method Recommendations
+
+### When to use Pixel Comparison (`comparisonMethod: 'pixel'`)
+
+- **Default choice** for most visual regression tests
+- **Precise pixel-by-pixel** comparison
+- **Good for detecting** small UI changes, text changes, layout shifts
+- **Fast execution** for most image sizes
+- **Customizable colors** for diff visualization
+
+### When to use SSIM Comparison (`comparisonMethod: 'ssim'`)
+
+- **Structural similarity** comparison that correlates better with human perception
+- **Reduced false positives** - less likely to fail on minor rendering differences
+- **Better for images** with gradients, shadows, or anti-aliasing
+- **Recommended threshold**: 1% (`failureThreshold: 0.01, failureThresholdType: 'percent'`)
+- **Performance considerations**: Use `ssim: 'bezkrovny'` for speed, `ssim: 'fast'` for accuracy
+
+```ts
+// Recommended SSIM configuration
+it('should use recommended SSIM settings', async ({ expect }) => {
+	render(<MyComponent />)
+
+	await expect(document.body).toMatchImageSnapshot({
+		comparisonMethod: 'ssim',
+		failureThreshold: 0.01,
+		failureThresholdType: 'percent',
+		diffOptions: {
+			ssim: 'bezkrovny' // Fast and accurate for most cases
+		}
+	})
+})
+```

package/src/client/page/has_image_snapshot.mdx

@@ -0,0 +1,328 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="page/hasImageSnapshot" />
+
+# page.hasImageSnapshot
+
+`page.hasImageSnapshot()` is a utility method that checks if an image snapshot exists for the current test.
+
+This method allows you to conditionally execute code based on whether a snapshot has been previously created for the current test. It's particularly useful for negative testing scenarios, conditional snapshot creation, and handling different behavior for first-time runs vs. subsequent runs.
+
+## Basic Usage
+
+```ts
+import { page } from '@vitest/browser/context'
+
+it('should check if snapshot exists', async ({ expect }) => {
+	const hasSnapshot = await page.hasImageSnapshot()
+
+	if (!hasSnapshot) {
+		// First run - create baseline snapshot
+		await page.toMatchImageSnapshot()
+	} else {
+		// Subsequent runs - perform comparison
+		await expect(page.getByTestId('component')).toMatchImageSnapshot()
+	}
+})
+```
+
+## Options
+
+The `page.hasImageSnapshot()` method accepts an optional options object:
+
+### `snapshotKey`
+
+Custom key to identify the specific snapshot. If not provided, uses the default snapshot key for the test.
+
+```ts
+it('should check for specific snapshot', async ({ expect }) => {
+	// Check for default snapshot
+	const hasDefaultSnapshot = await page.hasImageSnapshot()
+
+	// Check for custom snapshot
+	const hasCustomSnapshot = await page.hasImageSnapshot({
+		snapshotKey: 'dark_mode'
+	})
+
+	expect(hasDefaultSnapshot).toBe(false)
+	expect(hasCustomSnapshot).toBe(false)
+})
+```
+
+**Important**: The `snapshotKey` cannot contain dash characters (-) as they are reserved for internal path separation.
+
+```ts
+// ❌ This will throw an error
+await page.hasImageSnapshot({ snapshotKey: 'invalid-key' })
+// Error: Snapshot key cannot contain dash
+
+// ✅ Use underscores or camelCase instead
+await page.hasImageSnapshot({ snapshotKey: 'valid_key' })
+await page.hasImageSnapshot({ snapshotKey: 'validKey' })
+```
+
+## Use Cases
+
+### Negative Testing
+
+Test behavior when snapshots don't exist:
+
+```ts
+it('should handle missing snapshots gracefully', async ({ expect }) => {
+	const hasSnapshot = await page.hasImageSnapshot({ snapshotKey: 'nonexistent' })
+	expect(hasSnapshot).toBe(false)
+
+	// Now create the snapshot
+	await page.toMatchImageSnapshot({ snapshotKey: 'nonexistent' })
+
+	// Verify it now exists
+	const hasSnapshotAfter = await page.hasImageSnapshot({ snapshotKey: 'nonexistent' })
+	expect(hasSnapshotAfter).toBe(true)
+})
+```
+
+### Conditional Snapshot Creation
+
+Handle different behavior for first-time runs vs. subsequent runs:
+
+```ts
+it('should create or compare snapshots conditionally', async ({ expect }) => {
+	const hasSnapshot = await page.hasImageSnapshot()
+
+	if (!hasSnapshot) {
+		// First run - setup and create baseline
+		render(<MyComponent theme="light" />)
+		await page.toMatchImageSnapshot()
+	} else {
+		// Subsequent runs - test different scenarios
+		render(<MyComponent theme="dark" />)
+		await expect(page.getByTestId('component')).toMatchImageSnapshot({
+			expectToFail: true,
+			snapshotKey: 'dark_theme'
+		})
+	}
+})
+```
+
+### Theme or State-Specific Snapshots
+
+Work with different themes or application states:
+
+```ts
+it('should support theme-specific snapshots', async ({ expect }) => {
+	// Check for dark mode snapshot
+	const hasDarkSnapshot = await page.hasImageSnapshot({ snapshotKey: 'dark_mode' })
+
+	if (!hasDarkSnapshot) {
+		// Setup dark mode and create snapshot
+		document.body.classList.add('dark')
+		render(<MyApp />)
+		await page.toMatchImageSnapshot({ snapshotKey: 'dark_mode' })
+	}
+
+	// Check for light mode snapshot
+	const hasLightSnapshot = await page.hasImageSnapshot({ snapshotKey: 'light_mode' })
+
+	if (!hasLightSnapshot) {
+		// Setup light mode and create snapshot
+		document.body.classList.remove('dark')
+		render(<MyApp />)
+		await page.toMatchImageSnapshot({ snapshotKey: 'light_mode' })
+	}
+})
+```
+
+### Progressive Snapshot Building
+
+Build up complex test scenarios progressively:
+
+```ts
+it('should build snapshots progressively', async ({ expect }) => {
+	// Check if we have the base component snapshot
+	const hasBaseSnapshot = await page.hasImageSnapshot({ snapshotKey: 'base' })
+
+	if (!hasBaseSnapshot) {
+		render(<BaseComponent />)
+		await page.toMatchImageSnapshot({ snapshotKey: 'base' })
+	}
+
+	// Check if we have the enhanced component snapshot
+	const hasEnhancedSnapshot = await page.hasImageSnapshot({ snapshotKey: 'enhanced' })
+
+	if (!hasEnhancedSnapshot) {
+		render(<EnhancedComponent />)
+		await page.toMatchImageSnapshot({ snapshotKey: 'enhanced' })
+	}
+
+	// Now we can safely compare both exist
+	expect(await page.hasImageSnapshot({ snapshotKey: 'base' })).toBe(true)
+	expect(await page.hasImageSnapshot({ snapshotKey: 'enhanced' })).toBe(true)
+})
+```
+
+## Behavior and Limitations
+
+### Test Context Required
+
+The method must be called within a test context:
+
+```ts
+// ❌ This will throw an error
+const hasSnapshot = await page.hasImageSnapshot()
+// Error: `hasImageSnapshot()` must be called in a test.
+
+// ✅ Call within a test
+it('should work in test context', async () => {
+	const hasSnapshot = await page.hasImageSnapshot()
+	// This works correctly
+})
+```
+
+### Concurrent Tests Not Supported
+
+Cannot be used in concurrent tests because they share the same iframe environment:
+
+```ts
+// ❌ This will throw an error
+it.concurrent('should not work in concurrent test', async () => {
+	const hasSnapshot = await page.hasImageSnapshot()
+	// Error: `hasImageSnapshot()` cannot be called in a concurrent test because
+	// concurrent tests run at the same time in the same iframe and affect each other's environment.
+})
+
+// ✅ Use regular tests
+it('should work in regular test', async () => {
+	const hasSnapshot = await page.hasImageSnapshot()
+	// This works correctly
+})
+```
+
+### Async Operation
+
+Always returns a Promise, so you must use `await` or `.then()`:
+
+```ts
+// ✅ Using await
+const hasSnapshot = await page.hasImageSnapshot()
+
+// ✅ Using .then()
+page.hasImageSnapshot().then(hasSnapshot => {
+	if (hasSnapshot) {
+		// Handle existing snapshot
+	}
+})
+
+// ❌ Don't forget await
+const hasSnapshot = page.hasImageSnapshot() // This is a Promise, not a boolean!
+```
+
+## Error Handling
+
+The method will throw errors in specific cases:
+
+```ts
+// Test context errors
+try {
+	await page.hasImageSnapshot()
+} catch (error) {
+	// Error: `hasImageSnapshot()` must be called in a test.
+}
+
+// Concurrent test errors
+it.concurrent('concurrent test', async () => {
+	try {
+		await page.hasImageSnapshot()
+	} catch (error) {
+		// Error: `hasImageSnapshot()` cannot be called in a concurrent test because
+		// concurrent tests run at the same time in the same iframe and affect each other's environment.
+	}
+})
+
+// Snapshot key validation errors
+try {
+	await page.hasImageSnapshot({ snapshotKey: 'invalid-key' })
+} catch (error) {
+	// Error: Snapshot key cannot contain dash
+}
+```
+
+## Integration with Other Methods
+
+`page.hasImageSnapshot()` works seamlessly with other visual testing methods:
+
+```ts
+it('should integrate with other methods', async ({ expect }) => {
+	// Check if snapshot exists
+	const hasSnapshot = await page.hasImageSnapshot({ snapshotKey: 'integration' })
+
+	if (!hasSnapshot) {
+		// Create page snapshot
+		await page.toMatchImageSnapshot({ snapshotKey: 'integration' })
+	}
+
+	// Now test element snapshots
+	const element = page.getByTestId('component')
+	await expect(element).toMatchImageSnapshot({ snapshotKey: 'element' })
+
+	// Verify both snapshots exist
+	expect(await page.hasImageSnapshot({ snapshotKey: 'integration' })).toBe(true)
+	expect(await page.hasImageSnapshot({ snapshotKey: 'element' })).toBe(true)
+})
+```
+
+## Best Practices
+
+### Use Descriptive Snapshot Keys
+
+```ts
+// ✅ Good - descriptive and clear
+await page.hasImageSnapshot({ snapshotKey: 'homepage_header' })
+await page.hasImageSnapshot({ snapshotKey: 'modal_open_state' })
+await page.hasImageSnapshot({ snapshotKey: 'dark_theme_sidebar' })
+
+// ❌ Avoid - unclear purpose
+await page.hasImageSnapshot({ snapshotKey: 'test1' })
+await page.hasImageSnapshot({ snapshotKey: 'snapshot' })
+```
+
+### Handle Both Cases
+
+Always handle both the existence and non-existence cases:
+
+```ts
+it('should handle both snapshot states', async () => {
+	const hasSnapshot = await page.hasImageSnapshot({ snapshotKey: 'feature' })
+
+	if (hasSnapshot) {
+		// Test against existing snapshot
+		render(<FeatureComponent />)
+		await page.toMatchImageSnapshot({ snapshotKey: 'feature' })
+	} else {
+		// Create initial snapshot
+		render(<FeatureComponent />)
+		await page.toMatchImageSnapshot({ snapshotKey: 'feature' })
+	}
+})
+```
+
+### Combine with Conditional Logic
+
+Use with environment or configuration checks:
+
+```ts
+it('should adapt to environment', async () => {
+	const isDarkMode = process.env.THEME === 'dark'
+	const snapshotKey = isDarkMode ? 'dark_mode' : 'light_mode'
+
+	const hasSnapshot = await page.hasImageSnapshot({ snapshotKey })
+
+	if (!hasSnapshot) {
+		// Setup appropriate theme
+		if (isDarkMode) {
+			document.body.classList.add('dark')
+		}
+		render(<App />)
+		await page.toMatchImageSnapshot({ snapshotKey })
+	}
+})
+```