@blazediff/vitest

toMatchImageSnapshot() for Vitest. Auto-registers on import, tracks snapshot state, supports all comparison methods.

Installation


npm install --save-dev @blazediff/vitest


pnpm add --save-dev @blazediff/vitest


yarn add --dev @blazediff/vitest


bun add --dev @blazediff/vitest

Peer dependencies: Vitest >= 1.0.0

Quick Start


import { expect, it } from 'vitest';
import '@blazediff/vitest';
 
it('should match screenshot', async () => {
  const screenshot = await page.screenshot();
 
  await expect(screenshot).toMatchImageSnapshot({
    method: 'core',
  });
});

The matcher auto-registers when you import @blazediff/vitest. No additional setup required!

API Reference

toMatchImageSnapshot(options?)

Vitest matcher for image snapshot comparison.


await expect(imageInput).toMatchImageSnapshot(options?);

Parameters

Parameter	Type	Description
`imageInput`	`ImageInput`	Image to compare (file path or buffer with dimensions)
`options`	`Partial<MatcherOptions>`	Optional comparison options

Options

Option	Type	Default	Description
`method`	`ComparisonMethod`	`'core'`	Comparison algorithm
`failureThreshold`	`number`	`0`	Allowed difference (pixels or percentage)
`failureThresholdType`	`'pixel' \| 'percent'`	`'pixel'`	Threshold interpretation
`snapshotsDir`	`string`	`'__snapshots__'`	Snapshot directory (relative to test)
`snapshotIdentifier`	`string`	auto-generated	Custom snapshot filename
`updateSnapshots`	`boolean`	`false`	Force snapshot update
`threshold`	`number`	`0.1`	Color threshold for `core`/`core-native` (0-1)
`runInWorker`	`boolean`	`true`	Run comparison in worker thread for better performance

See @blazediff/matcher for all available options.

Comparison Methods

`core` - Pure JavaScript (Default)


await expect(screenshot).toMatchImageSnapshot({
  method: 'core', // Fast, works with buffers and file paths
});

`core-native` - Rust Native (Fastest)


await expect('/path/to/image.png').toMatchImageSnapshot({
  method: 'core-native', // Requires file paths
});

`ssim` - Perceptual Similarity


await expect(screenshot).toMatchImageSnapshot({
  method: 'ssim', // Structural similarity
});

`gmsd` - Gradient-based


await expect(screenshot).toMatchImageSnapshot({
  method: 'gmsd', // Detects structural changes
});

Usage Patterns

Basic Snapshot Test


import { expect, it } from 'vitest';
import '@blazediff/vitest';
 
it('renders homepage correctly', async () => {
  const screenshot = await browser.screenshot();
 
  await expect(screenshot).toMatchImageSnapshot({
    method: 'core',
  });
});

Custom Thresholds

Allow small differences while catching regressions:


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

Use percentage-based thresholds for responsive images that may change size across different viewports.

Update Snapshots


# Update all failing snapshots
vitest -u
 
# Update snapshots for specific test file
vitest -u src/components/Button.test.ts
 
# Update snapshots matching pattern
vitest -u --testNamePattern="renders correctly"
 
# Using environment variable
VITEST_UPDATE_SNAPSHOTS=true vitest

Programmatically:


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

Custom Snapshot Directory


await expect(screenshot).toMatchImageSnapshot({
  method: 'core',
  snapshotsDir: '__image_snapshots__', // Custom directory
});

Custom Snapshot Identifier


await expect(screenshot).toMatchImageSnapshot({
  method: 'core',
  snapshotIdentifier: 'homepage-desktop-1920x1080',
});

Negation

Test that images are intentionally different:


const before = await page.screenshot();
await page.click('.toggle-theme');
const after = await page.screenshot();
 
// Assert that theme toggle changed the UI
await expect(after).not.toMatchImageSnapshot({
  method: 'core',
  snapshotIdentifier: 'before-theme-toggle',
});

Configuration

Global Setup

To avoid importing in every test file, configure Vitest:


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


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