@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: a file path, encoded PNG bytes, or raw RGBA pixels 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 options sit in one namespace per method family. The matcher manages output itself:

Option	Type	Used by	Description
`diff`	`Omit<DiffOptions, "output">`	`core`, `core-wasm`, `core-native`	`threshold`, `antialiasing` (default `true`), `metric`, `mask`, `window`, `render`. See @blazediff/core
`ssim`	`Omit<SsimOptions, "output">`	`ssim`, `msssim`, `hitchhikers-ssim`	`windowSize`, `k1`, `k2`, `bitDepth`, `msSsim`, `hitchhikers`. See @blazediff/ssim
`gmsd`	`Omit<GmsdOptions, "output">`	`gmsd`	`downsample`, `c`. See @blazediff/gmsd
`runInWorker`	`boolean`	all	Run image I/O and comparison in a worker thread for better performance. Default: `true`


await getOrCreateSnapshot(screenshot, {
  method: 'core',
  failureThreshold: 0.1,
  failureThresholdType: 'percent',
  diff: { threshold: 0.05, metric: 'oklab' },
}, testContext);

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
  | Uint8Array // Encoded PNG bytes (a Buffer works)
  | {
      data: Uint8Array | Uint8ClampedArray | Buffer;
      width: number;
      height: number;
    };

Comparison Methods

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