@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, core-native, 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

npm install @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',
  }
);

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

API Reference

getOrCreateSnapshot(received, options, testContext)

Main function for snapshot comparison.

Returns: Promise<ComparisonResult>

MatcherOptions

ComparisonResult

ImageInput

type ImageInput =
  | string // File path
  | Uint8Array // Encoded PNG bytes (a Buffer works)
  | {
      data: Uint8Array | Uint8ClampedArray | Buffer;
      width: number;
      height: number;
    };

Comparison Methods

core-native

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

• Input: File paths, PNG buffers or raw RGBA images
• Algorithm: YIQ color space with block-based optimization
• Best for: Production testing, large images

core-wasm

The core-native algorithm compiled to WebAssembly. Same results, no native binaries.

• Input: File paths or buffers

core

Pixel-by-pixel comparison in JavaScript. Pure JS implementation with no native dependencies.

• Input: File paths or buffers
• Algorithm: YIQ color space with anti-aliasing detection
• Best for: Cross-platform compatibility

ssim

Structural Similarity Index. Measures perceptual similarity.

• Input: File paths or buffers
• Algorithm: Standard SSIM with configurable window size
• Best for: Perceptual quality assessment
• Score: 1 = identical, lower = more different

msssim

Multi-Scale Structural Similarity Index.

• Input: File paths or buffers
• Algorithm: SSIM across multiple scales
• Best for: Images with varying resolutions or scales

hitchhikers-ssim

Fast SSIM approximation from Hitchhiker's Guide.

• Input: File paths or buffers
• Algorithm: Optimized SSIM calculation
• Best for: Faster SSIM with acceptable accuracy trade-off

gmsd

Gradient Magnitude Similarity Deviation.

• Input: File paths or buffers
• Algorithm: Gradient-based perceptual similarity
• Best for: Detecting structural changes
• Score: 0 = identical, higher = more different

Usage Examples

With File Paths

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

With Image Buffers

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

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

Custom Threshold

const result = await getOrCreateSnapshot(
  imagePath,
  {
    method: 'core',
    failureThreshold: 0.1,
    failureThresholdType: 'percent', // Allow 0.1% difference
    diff: { threshold: 0.05 }, // Stricter per-pixel color threshold
  },
  { testPath: __filename, testName: 'test name' }
);

Different Comparison Methods

// Fastest - Rust native (paths, PNG buffers or raw images)
await getOrCreateSnapshot(imagePath, { method: 'core-native' }, 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