@blazediff/matcher

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

Installation

npm install @blazediff/matcher

pnpm add @blazediff/matcher

yarn add @blazediff/matcher

bun add @blazediff/matcher

Features

• Multiple comparison methods: Choose from core, bin, ssim, msssim, hitchhikers-ssim, gmsd
• Flexible input types: Accepts file paths or image buffers with dimensions
• Snapshot state tracking: Reports added, matched, updated, failed status
• Configurable thresholds: Set tolerance by pixel count or percentage
• Framework-agnostic: Core logic powers Jest, Vitest, and Bun integrations
• Rich comparison results: Get diff counts, percentages, and similarity scores

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.

Returns: Promise<ComparisonResult>

MatcherOptions

Core comparison options:

Method-specific options:

ComparisonResult

Result object returned by getOrCreateSnapshot:

ImageInput

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

Comparison Methods

bin - Rust Native (Fastest)

Rust-native comparison via N-API bindings with native performance.

• Speed: Fastest method, especially for large images
• Input: File paths only
• Algorithm: YIQ color space with block-based optimization
• Use case: Production testing, CI/CD pipelines

const result = await getOrCreateSnapshot(
  '/path/to/image.png',
  { method: 'bin' },
  testContext
);

core - Pure JavaScript

Pixel-by-pixel comparison in pure JavaScript with zero native dependencies.

• Speed: Fast, with block-based optimization
• Input: File paths or buffers
• Algorithm: YIQ color space with anti-aliasing detection
• Use case: Cross-platform compatibility, when native binaries are unavailable

const result = await getOrCreateSnapshot(
  imageBuffer,
  { method: 'core' },
  testContext
);

ssim - Structural Similarity

Standard SSIM algorithm for perceptual similarity measurement.

• Speed: Moderate
• Input: File paths or buffers
• Algorithm: Structural Similarity Index
• Score: 1 = identical, lower = more different
• Use case: Perceptual quality assessment

const result = await getOrCreateSnapshot(
  imageBuffer,
  { method: 'ssim', windowSize: 11 },
  testContext
);

msssim - Multi-Scale SSIM

Multi-scale SSIM for better handling of varying resolutions.

• Speed: Slower than standard SSIM
• Input: File paths or buffers
• Algorithm: SSIM computed across multiple scales
• Use case: Images with varying resolutions or scales

hitchhikers-ssim - Fast SSIM

Optimized SSIM approximation from Hitchhiker’s Guide.

• Speed: Faster than standard SSIM
• Input: File paths or buffers
• Algorithm: Optimized SSIM calculation
• Use case: Faster perceptual comparison with acceptable accuracy trade-off

gmsd - Gradient Magnitude

Gradient Magnitude Similarity Deviation for structural change detection.

• Speed: Moderate
• Input: File paths or buffers
• Algorithm: Gradient-based perceptual similarity
• Score: 0 = identical, higher = more different
• Use case: Detecting structural and edge changes

const result = await getOrCreateSnapshot(
  imageBuffer,
  { method: 'gmsd', downsample: 0 },
  testContext
);

Usage Examples

File Paths

const result = await getOrCreateSnapshot(
  '/path/to/screenshot.png',
  { method: 'bin' },
  {
    testPath: '/path/to/test.spec.ts',
    testName: 'homepage renders',
  }
);

Image Buffers

const imageData = {
  data: new Uint8Array([/* pixel data */]),
  width: 800,
  height: 600,
};
 
const result = await getOrCreateSnapshot(
  imageData,
  { method: 'core' },
  {
    testPath: '/path/to/test.spec.ts',
    testName: 'renders correctly',
  }
);

Custom Thresholds

// Allow up to 0.1% difference
const result = await getOrCreateSnapshot(
  imagePath,
  {
    method: 'core',
    failureThreshold: 0.1,
    failureThresholdType: 'percent',
  },
  testContext
);

Snapshot State Tracking

The snapshotStatus field indicates what happened to the snapshot:

const result = await getOrCreateSnapshot(imagePath, options, testContext);
 
switch (result.snapshotStatus) {
  case 'added':
    console.log('New snapshot created');
    break;
  case 'matched':
    console.log('Snapshot matched existing baseline');
    break;
  case 'updated':
    console.log('Snapshot updated (update mode)');
    break;
  case 'failed':
    console.log(`Snapshot failed: ${result.diffPercentage}% different`);
    break;
}

Framework Integrations

For most users, framework-specific packages provide a better developer experience:

• @blazediff/jest - Jest matcher with toMatchImageSnapshot()
• @blazediff/vitest - Vitest matcher with toMatchImageSnapshot()
• @blazediff/bun - Bun test matcher with toMatchImageSnapshot()

These packages wrap @blazediff/matcher and integrate with framework snapshot state tracking.

Links

• GitHub Repository 
• NPM Package 
• @blazediff/core - Core comparison algorithm
• @blazediff/ssim - SSIM algorithms
• @blazediff/gmsd - GMSD algorithm
• @blazediff/bin - Rust-native bindings