@blazediff/matcher

Core matcher logic for visual regression testing. Provides snapshot comparison with multiple algorithms, framework-agnostic APIs, and snapshot state tracking.

Features

- Multiple comparison methods: core, bin, ssim, msssim, hitchhikers-ssim, gmsd
- Flexible input types: File paths or image buffers
- Snapshot state tracking: Reports added/matched/updated/failed status
- Configurable thresholds: Pixel count or percentage-based
- Framework-agnostic: Core logic for Jest, Vitest, Bun integrations
- Rich comparison results: Diff counts, percentages, and similarity scores

Installation

``bash
npm install @blazediff/matcher
`

Quick Start

`typescript
import { getOrCreateSnapshot } from '@blazediff/matcher';

const result = await getOrCreateSnapshot(
imageBuffer, // or file path
{
method: 'core',
failureThreshold: 0.01,
failureThresholdType: 'percent',
},
{
testPath: '/path/to/test.spec.ts',
testName: 'should render correctly',
}
);

console.log(result.pass); // true/false
console.log(result.snapshotStatus); // 'added' | 'matched' | 'updated' | 'failed'
console.log(result.diffPercentage); // e.g., 0.05
`

API Reference

$3

Main function for snapshot comparison.

Returns: Promise

$3

$3

$3

`typescript
type ImageInput =
| string // File path
| {
data: Uint8Array | Uint8ClampedArray | Buffer;
width: number;
height: number;
};
`

Comparison Methods

$3

`typescript
const result = await getOrCreateSnapshot(
'/path/to/screenshot.png',
{ method: 'bin' },
{ testPath: __filename, testName: 'test name' }
);
`

$3

`typescript
const imageData = {
data: new Uint8Array([...]),
width: 800,
height: 600,
};

const result = await getOrCreateSnapshot(
imageData,
{ method: 'core' },
{ testPath: __filename, testName: 'test name' }
);
`

$3

`typescript
const result = await getOrCreateSnapshot(
imagePath,
{
method: 'core',
failureThreshold: 0.1,
failureThresholdType: 'percent', // Allow 0.1% difference
},
{ testPath: __filename, testName: 'test name' }
);
`

$3

`typescript
// Fastest - Rust native (file paths only)
await getOrCreateSnapshot(imagePath, { method: 'bin' }, context);

// Pure JavaScript
await getOrCreateSnapshot(imageBuffer, { method: 'core' }, context);

// Perceptual similarity
await getOrCreateSnapshot(imageBuffer, { method: 'ssim' }, context);

// Gradient-based
await getOrCreateSnapshot(imageBuffer, { method: 'gmsd' }, context);
``

Framework Integrations

This package provides the core logic for framework-specific integrations:

- @blazediff/jest - Jest matcher
- @blazediff/vitest - Vitest matcher
- @blazediff/bun - Bun test matcher

Links

- GitHub Repository
- Documentation
- NPM Package