@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, core-native, 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

npm install --save-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 takeScreenshot();

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

API Reference

toMatchImageSnapshot(options?)

Vitest matcher for image snapshot comparison.

Options

See @blazediff/matcher for full options documentation.

Usage Patterns

Basic Snapshot Test

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

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

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

Different Comparison Methods

// Fast Rust-native comparison (paths, PNG buffers or raw images)
await expect('/path/to/image.png').toMatchImageSnapshot({
  method: 'core-native',
});

// 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',
});

Update Snapshots

# 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:

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

Custom Thresholds

// 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',
});

Custom Snapshot Directory

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

Custom Snapshot Identifier

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

With Playwright

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();
});

Negation

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

Sequential Tests

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

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

Auto-setup (Recommended)

Simply import the package in your test file:

import '@blazediff/vitest';

The matcher is automatically registered when imported.

Manual Setup

Alternatively, call the setup function explicitly:

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

setupBlazediffMatchers();

Global Setup

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

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

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

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

TypeScript

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

import '@blazediff/vitest';

declare module 'vitest' {
  interface Assertion<T = any> {
    toMatchImageSnapshot(options?: Partial<import('@blazediff/matcher').MatcherOptions>): Promise<void>;
  }
}

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

Links

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