tessl/npm-jest-image-snapshot

Jest matcher for image comparisons used for visual regression testing.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Configuration

Name: tessl/npm-jest-image-snapshot
Author: tessl

The configuration system in jest-image-snapshot allows you to create customized matchers with default options and fine-tune comparison algorithms for your specific testing needs.

Capabilities

Configuration Factory

Creates a customized toMatchImageSnapshot matcher with predefined default options, useful for sharing configuration across multiple tests.

/**
 * Creates a customized toMatchImageSnapshot matcher with default options
 * @param defaultOptions - Default configuration applied to all comparisons
 * @returns Configured toMatchImageSnapshot function
 */
function configureToMatchImageSnapshot(defaultOptions?: MatcherOptions): typeof toMatchImageSnapshot;

Usage Examples:

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

// Create matcher with default threshold
const toMatchImageSnapshot = configureToMatchImageSnapshot({
  failureThreshold: 0.01,
  failureThresholdType: 'percent',
  customDiffConfig: { threshold: 0.1 }
});

expect.extend({ toMatchImageSnapshot });

// Use in tests - default options are applied
it('visual test with defaults', () => {
  expect(imageBuffer).toMatchImageSnapshot(); // Uses 0.01% threshold
});

// Override defaults per test
it('visual test with override', () => {
  expect(imageBuffer).toMatchImageSnapshot({
    failureThreshold: 0.05 // Overrides default 0.01
  });
});

Custom Diff Configuration

Configuration options for the underlying comparison algorithms (pixelmatch and SSIM).

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

Pixelmatch Configuration

Pixelmatch is the default comparison method, providing pixel-by-pixel comparison.

interface PixelmatchDiffConfig {
  /** Per-pixel sensitivity threshold (0-1, default: 0.01) */
  threshold?: number;
  /** Whether to include anti-aliasing detection (default: false) */
  includeAA?: boolean;
  /** Alpha channel blending factor (0-1, default: 0.1) */
  alpha?: number;
  /** Anti-aliasing color [R, G, B] (default: [255, 255, 0]) */
  aaColor?: [number, number, number];
  /** Diff highlight color [R, G, B] (default: [255, 0, 255]) */
  diffColor?: [number, number, number];
  /** Alternative diff color [R, G, B] */
  diffColorAlt?: [number, number, number];
}

Pixelmatch Examples:

// High sensitivity - detects small differences
expect(imageBuffer).toMatchImageSnapshot({
  customDiffConfig: {
    threshold: 0.001 // Very sensitive
  }
});

// Low sensitivity - ignores minor differences  
expect(imageBuffer).toMatchImageSnapshot({
  customDiffConfig: {
    threshold: 0.1 // Less sensitive
  }
});

// Custom diff colors
expect(imageBuffer).toMatchImageSnapshot({
  customDiffConfig: {
    threshold: 0.01,
    diffColor: [255, 0, 0], // Red highlights
    aaColor: [0, 255, 0]    // Green for anti-aliasing
  }
});

SSIM Configuration

SSIM (Structural Similarity Index) provides perceptual comparison focusing on structural changes.

interface SSIMDiffConfig {
  /** SSIM algorithm variant: 'bezkrovny' (fast, default) or 'fast' (accurate) */
  ssim?: 'bezkrovny' | 'fast';
}

SSIM Examples:

// Fast SSIM (default) - optimized for speed
expect(imageBuffer).toMatchImageSnapshot({
  comparisonMethod: 'ssim',
  customDiffConfig: {
    ssim: 'bezkrovny' // 9x faster, slight accuracy loss  
  },
  failureThreshold: 0.01,
  failureThresholdType: 'percent'
});

// Accurate SSIM - higher precision
expect(imageBuffer).toMatchImageSnapshot({
  comparisonMethod: 'ssim', 
  customDiffConfig: {
    ssim: 'fast' // More accurate, slower
  },
  failureThreshold: 0.01,
  failureThresholdType: 'percent'
});

Runtime Hooks

Runtime hooks allow custom processing of images before they are written to disk.

interface RuntimeHooks {
  /**
   * Called before writing any image to disk
   * @param params - Hook parameters including buffer and metadata
   * @returns Modified buffer to write to disk
   */
  onBeforeWriteToDisc(params: {
    buffer: Buffer;
    destination: string;
    testPath: string;
    currentTestName: string;
  }): Buffer;
}

Runtime Hooks Example:

// runtimeHooks.js
module.exports = {
  onBeforeWriteToDisc({ buffer, destination, testPath, currentTestName }) {
    // Add EXIF metadata or modify image before saving
    console.log(`Writing ${destination} for test ${currentTestName}`);
    return buffer; // Return modified buffer
  }
};

// In test file
expect(imageBuffer).toMatchImageSnapshot({
  runtimeHooksPath: require.resolve('./runtimeHooks.js')
});

Global Configuration Patterns

Common patterns for configuring jest-image-snapshot across your test suite.

Setup File Configuration:

// jest-setup.js
const { configureToMatchImageSnapshot } = require('jest-image-snapshot');

const toMatchImageSnapshot = configureToMatchImageSnapshot({
  // Default options for all tests
  failureThreshold: 0.01,
  failureThresholdType: 'percent',
  customDiffConfig: {
    threshold: 0.01
  },
  blur: 1, // Reduce noise from scaling
  allowSizeMismatch: false,
  storeReceivedOnFailure: true
});

expect.extend({ toMatchImageSnapshot });

Environment-Specific Configuration:

const isCI = process.env.CI === 'true';

const toMatchImageSnapshot = configureToMatchImageSnapshot({
  // Stricter thresholds in CI
  failureThreshold: isCI ? 0.001 : 0.01,
  failureThresholdType: 'percent',
  // Store received images in CI for debugging
  storeReceivedOnFailure: isCI,
  // Disable colors in CI logs
  noColors: isCI
});

Device-Specific Configuration:

const getDeviceConfig = (deviceType) => {
  const baseConfig = {
    failureThreshold: 0.01,
    failureThresholdType: 'percent'
  };

  switch (deviceType) {
    case 'mobile':
      return {
        ...baseConfig,
        customSnapshotsDir: './snapshots/mobile',
        blur: 1 // Account for rendering differences
      };
    case 'desktop':
      return {
        ...baseConfig,
        customSnapshotsDir: './snapshots/desktop',
        allowSizeMismatch: true // Different screen sizes
      };
    default:
      return baseConfig;
  }
};