@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

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

Peer dependencies: Jest >= 27.0.0

Quick Start

`typescript
import '@blazediff/jest';

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

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

API Reference

$3

Jest 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 '@blazediff/jest';

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

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:

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

$3

`typescript
// 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:

`typescript
import '@blazediff/jest';

declare global {
namespace jest {
interface Matchers {
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