or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcore-matcher.mdindex.mdsnapshot-management.md
tile.json

tessl/npm-jest-image-snapshot

Jest matcher for image comparisons used for visual regression testing.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/jest-image-snapshot@6.5.x

To install, run

npx @tessl/cli install tessl/npm-jest-image-snapshot@6.5.0

index.mddocs/

Jest Image Snapshot

Jest Image Snapshot is a Jest matcher that performs image comparisons for visual regression testing. It extends Jest's testing capabilities by enabling pixel-perfect comparison of images using pixelmatch or SSIM algorithms, with features like customizable difference thresholds, Gaussian blur for noise reduction, and flexible diff layout options.

Package Information

  • Package Name: jest-image-snapshot
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install --save-dev jest-image-snapshot

Core Imports

const { toMatchImageSnapshot, configureToMatchImageSnapshot } = require('jest-image-snapshot');

expect.extend({ toMatchImageSnapshot });

For ES modules:

import { toMatchImageSnapshot, configureToMatchImageSnapshot } from 'jest-image-snapshot';

expect.extend({ toMatchImageSnapshot });

Basic Usage

const { toMatchImageSnapshot } = require('jest-image-snapshot');

expect.extend({ toMatchImageSnapshot });

it('should match image snapshot', async () => {
  // Get image buffer (e.g., from Puppeteer, Playwright, etc.)
  const page = await browser.newPage();
  await page.goto('https://example.com');
  const image = await page.screenshot();

  // Compare with snapshot
  expect(image).toMatchImageSnapshot();
});

// With custom options
it('should match with custom threshold', () => {
  expect(imageBuffer).toMatchImageSnapshot({
    failureThreshold: 0.01,
    failureThresholdType: 'percent'
  });
});

Architecture

Jest Image Snapshot operates through several key components:

  • Matcher Function: toMatchImageSnapshot extends Jest's expect functionality
  • Configuration Factory: configureToMatchImageSnapshot creates matchers with default options
  • Image Comparison Engine: Uses pixelmatch or SSIM algorithms for pixel-level comparison
  • Snapshot Management: Integrates with Jest's snapshot system for baseline storage and updates
  • Diff Generation: Creates visual diff images showing differences between baseline and received images
  • Process Management: Supports both in-process and child-process execution for performance

Capabilities

Core Matcher

The primary Jest matcher function that performs image comparison against stored snapshots. Handles snapshot creation, comparison, and updating through Jest's standard workflow.

function toMatchImageSnapshot(options?: MatcherOptions): void;

interface MatcherOptions {
  customDiffConfig?: CustomDiffConfig;
  comparisonMethod?: 'pixelmatch' | 'ssim';
  customSnapshotIdentifier?: string | CustomSnapshotIdentifierFunction;
  customSnapshotsDir?: string;
  customDiffDir?: string;
  customReceivedDir?: string;
  customReceivedPostfix?: string;
  storeReceivedOnFailure?: boolean;
  diffDirection?: 'horizontal' | 'vertical';
  onlyDiff?: boolean;  
  noColors?: boolean;
  failureThreshold?: number;
  failureThresholdType?: 'pixel' | 'percent';
  updatePassedSnapshot?: boolean;
  blur?: number;
  runInProcess?: boolean;
  dumpDiffToConsole?: boolean;
  dumpInlineDiffToConsole?: boolean;
  allowSizeMismatch?: boolean;
  maxChildProcessBufferSizeInBytes?: number;
  runtimeHooksPath?: string;
}

Core Matcher

Configuration Factory

Factory function for creating customized matchers with default options, useful for sharing configuration across multiple tests.

function configureToMatchImageSnapshot(defaultOptions?: MatcherOptions): typeof toMatchImageSnapshot;

Configuration

Snapshot Reporter

Jest reporter for tracking and cleaning up obsolete snapshot files that are no longer referenced by tests.

class OutdatedSnapshotReporter {
  static markTouchedFile(filePath: string): void;
  static readTouchedFileListFromDisk(): string[];
  onRunStart(): void;
  onRunComplete(): void;
}

Snapshot Management

Snapshot State Utility

Internal utility function for updating Jest snapshot state, primarily used for advanced integrations and testing scenarios.

function updateSnapshotState(originalSnapshotState: object, partialSnapshotState: object): object;

Types

interface CustomDiffConfig {
  // Pixelmatch options
  threshold?: number;
  includeAA?: boolean;
  alpha?: number;
  aaColor?: [number, number, number];
  diffColor?: [number, number, number];
  diffColorAlt?: [number, number, number];
  // SSIM options  
  ssim?: 'bezkrovny' | 'fast';
}

interface CustomSnapshotIdentifierFunction {
  (params: {
    testPath: string;
    currentTestName: string;
    counter: number;
    defaultIdentifier: string;
  }): string;
}

interface RuntimeHooks {
  onBeforeWriteToDisc(params: {
    buffer: Buffer;
    destination: string;
    testPath: string;
    currentTestName: string;
  }): Buffer;
}