@blazediff/vitest

Vitest matcher for visual regression testing with blazediff. Powered by @blazediff/matcher with Vitest-specific snapshot state integration.

Features

- Native Vitest matcher: toMatchImageSnapshot() extends Vitest's expect
- Snapshot state tracking: Vitest reports accurate snapshot counts (added/matched/updated/failed)
- Multiple comparison algorithms: core, bin, ssim, msssim, hitchhikers-ssim, gmsd
- Auto-setup: Imports and registers automatically
- Update mode: Works with Vitest's -u flag
- TypeScript support: Full type definitions included

Installation

``bash
npm install --save-dev @blazediff/vitest
`

Peer dependencies: Vitest >= 1.0.0

Quick Start

`typescript
import { expect, it } from 'vitest';
import '@blazediff/vitest';

it('should match screenshot', async () => {
const screenshot = await takeScreenshot();

await expect(screenshot).toMatchImageSnapshot({
method: 'core',
});
});
`

API Reference

$3

Vitest matcher for image snapshot comparison.














Parameter	Type	Description
options	Partial<MatcherOptions>	Optional comparison options (see below)

#### Options




















































Option	Type	Default	Description
method	'core' | 'bin' | 'ssim' | 'msssim' | 'hitchhikers-ssim' | 'gmsd'	'core'	Comparison algorithm to use
failureThreshold	number	0	Number of pixels or percentage difference allowed
failureThresholdType	'pixel' | 'percent'	'pixel'	How to interpret failureThreshold
snapshotsDir	string	'__snapshots__'	Directory to store snapshots relative to test file
snapshotIdentifier	string	auto-generated	Custom identifier for the snapshot file
updateSnapshots	boolean	false	Force update snapshots
threshold	number	0.1	Color difference threshold (0-1) for core/bin methods

See @blazediff/matcher for full options documentation.

Usage Patterns

$3

`typescript
import { expect, it } from 'vitest';
import '@blazediff/vitest';

it('renders correctly', async () => {
const screenshot = await page.screenshot();

await expect(screenshot).toMatchImageSnapshot({
method: 'core',
});
});
`

$3

`typescript
// Fast Rust-native comparison (file paths only)
await expect('/path/to/image.png').toMatchImageSnapshot({
method: 'bin',
});

// Pure JavaScript comparison
await expect(imageBuffer).toMatchImageSnapshot({
method: 'core',
});

// Perceptual similarity (SSIM)
await expect(imageBuffer).toMatchImageSnapshot({
method: 'ssim',
});

// Gradient-based comparison
await expect(imageBuffer).toMatchImageSnapshot({
method: 'gmsd',
});
`

$3

`bash


Update all snapshots

vitest -u

Update snapshots for specific test

vitest -u path/to/test.spec.ts

Or using environment variable

VITEST_UPDATE_SNAPSHOTS=true vitest
`

Or programmatically:

`typescript
await expect(screenshot).toMatchImageSnapshot({
method: 'core',
updateSnapshots: true,
});
`

$3

`typescript
// Allow up to 100 pixels difference
await expect(screenshot).toMatchImageSnapshot({
method: 'core',
failureThreshold: 100,
failureThresholdType: 'pixel',
});

// Allow up to 0.1% difference
await expect(screenshot).toMatchImageSnapshot({
method: 'core',
failureThreshold: 0.1,
failureThresholdType: 'percent',
});
`

$3

`typescript
await expect(screenshot).toMatchImageSnapshot({
method: 'core',
snapshotsDir: '__image_snapshots__',
});
`

$3

`typescript
await expect(screenshot).toMatchImageSnapshot({
method: 'core',
snapshotIdentifier: 'homepage-desktop-chrome',
});
`

$3

`typescript
import { test, expect } from 'vitest';
import '@blazediff/vitest';
import { chromium } from 'playwright';

test('visual regression with Playwright', async () => {
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com');

const screenshot = await page.screenshot();
await expect(screenshot).toMatchImageSnapshot({
method: 'core',
});

await browser.close();
});
`

$3

`typescript
// Assert images are different
await expect(screenshot).not.toMatchImageSnapshot({
method: 'core',
});
`

$3

For tests that might interfere with each other (e.g., cleaning up snapshots), use sequential execution:

`typescript
import { describe, it } from 'vitest';

describe.sequential('Visual regression tests', () => {
it('test 1', async () => {
await expect(image1).toMatchImageSnapshot({ method: 'core' });
});

it('test 2', async () => {
await expect(image2).toMatchImageSnapshot({ method: 'core' });
});
});
`

Snapshot State Tracking

This matcher integrates with Vitest's snapshot state tracking system. Vitest will report accurate counts in test summaries:

`
Snapshots 2 written | 1 updated | 5 passed
`

The matcher updates Vitest's internal counters:
- Written: New snapshots created
- Updated: Snapshots updated with -u flag
- Passed: Existing snapshots matched
- Failed: Snapshot comparisons failed

Setup

$3

Simply import the package in your test file:

`typescript
import '@blazediff/vitest';
`

The matcher is automatically registered when imported.

$3

Alternatively, call the setup function explicitly:

`typescript
import { setupBlazediffMatchers } from '@blazediff/vitest';

setupBlazediffMatchers();
`

$3

To avoid importing in every test file, add to your Vitest config:

`typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
test: {
setupFiles: ['./vitest.setup.ts'],
},
});
`

`typescript
// vitest.setup.ts
import '@blazediff/vitest';
`

TypeScript

TypeScript types are included. To use the matcher with TypeScript:

`typescript
import '@blazediff/vitest';

declare module 'vitest' {
interface Assertion {
toMatchImageSnapshot(options?: Partial): Promise;
}
}
``

The type augmentation is automatically included when you import the package.

Links

- GitHub Repository
- Documentation
- NPM Package
- @blazediff/matcher - Core matcher logic