@blazediff/jest

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

Features

• Native Jest matcher: toMatchImageSnapshot() extends Jest's expect
• Snapshot state tracking: Jest 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 Jest's -u flag
• TypeScript support: Full type definitions included

Installation

npm install --save-dev @blazediff/jest

Peer dependencies: Jest >= 27.0.0

Quick Start

import '@blazediff/jest';

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

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

API Reference

toMatchImageSnapshot(options?)

Jest matcher for image snapshot comparison.

Options

See @blazediff/matcher for full options documentation.

Usage Patterns

Basic Snapshot Test

import '@blazediff/jest';

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

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

Different Comparison Methods

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

Update Snapshots

# Update all snapshots
jest -u

# Update snapshots for specific test
jest -u path/to/test.spec.ts

# Or using environment variable
JEST_UPDATE_SNAPSHOTS=true jest

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 as playwrightExpect } from '@playwright/test';
import { expect as jestExpect } from '@jest/globals';
import '@blazediff/jest';

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

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

Negation

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

Snapshot State Tracking

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

Snapshots:   2 added, 1 updated, 5 passed, 8 total

The matcher updates Jest's internal counters:

• Added: New snapshots created
• Updated: Snapshots updated with -u flag
• Passed: Existing snapshots matched
• Failed: Snapshot comparisons failed

TypeScript

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

import '@blazediff/jest';

declare global {
  namespace jest {
    interface Matchers<R> {
      toMatchImageSnapshot(options?: Partial<import('@blazediff/matcher').MatcherOptions>): Promise<R>;
    }
  }
}

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

Links

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