@blazediff/matcher

Core snapshot comparison logic that powers @blazediff/jest, @blazediff/vitest, and @blazediff/bun. Most users should use those framework packages directly.

Installation


npm install @blazediff/matcher


pnpm add @blazediff/matcher


yarn add @blazediff/matcher


bun add @blazediff/matcher

Quick Start


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',
  }
);
 
if (result.pass) {
  console.log(`✓ Snapshot ${result.snapshotStatus}`);
} else {
  console.log(`✗ ${result.diffPercentage}% different`);
}

API Reference

getOrCreateSnapshot(received, options, testContext)

Main function for snapshot comparison and management.

Parameter	Type	Description
`received`	`ImageInput`	Image to compare (file path or buffer with dimensions)
`options`	`MatcherOptions`	Comparison options
`testContext`	`TestContext`	Test information (testPath, testName)

Returns: Promise<ComparisonResult>

MatcherOptions

Core comparison options:

Option	Type	Default	Description
`method`	`ComparisonMethod`	-	Comparison algorithm: `'core'`, `'core-native'`, `'ssim'`, `'msssim'`, `'hitchhikers-ssim'`, `'gmsd'`
`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

Method-specific options:

Option	Type	Default	Description
`threshold`	`number`	`0.1`	Color difference threshold (0-1) for `core`/`core-native` methods
`antialiasing`	`boolean`	`false`	Enable anti-aliasing detection (`core-native` method)
`includeAA`	`boolean`	`false`	Include anti-aliased pixels in diff count (`core` method)
`windowSize`	`number`	`11`	Window size for SSIM variants
`k1`	`number`	`0.01`	k1 constant for SSIM
`k2`	`number`	`0.03`	k2 constant for SSIM
`downsample`	`0 \| 1`	`0`	Downsample factor for GMSD
`runInWorker`	`boolean`	`true`	Run image I/O and comparison in a worker thread for better performance

ComparisonResult

Result object returned by getOrCreateSnapshot:

Field	Type	Description
`pass`	`boolean`	Whether the comparison passed
`message`	`string`	Human-readable message describing the result
`snapshotStatus`	`SnapshotStatus`	Status: `'added'`, `'matched'`, `'updated'`, `'failed'`
`diffCount`	`number?`	Number of different pixels (pixel-based methods)
`diffPercentage`	`number?`	Percentage of different pixels
`score`	`number?`	Similarity score (SSIM: 1 = identical, GMSD: 0 = identical)
`baselinePath`	`string?`	Path to baseline snapshot
`receivedPath`	`string?`	Path to received image (saved on failure)
`diffPath`	`string?`	Path to diff visualization

ImageInput


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

Comparison Methods

Available methods: core, core-native, ssim, msssim, hitchhikers-ssim, gmsd. See @blazediff/core, @blazediff/core-native, @blazediff/ssim, and @blazediff/gmsd for algorithm details.