png-visual-compare

png-visual-compare

Visual regression testing for PNG images with zero binary dependencies

---

A Node.js utility to compare PNG images or their areas without binary and OS dependencies.

Key Benefits:

• Zero Native Binaries — Pure JavaScript for supported macOS and Linux environments
• File or Buffer — Accept absolute file paths or raw Buffer inputs
• Pixel-Level Accuracy — Powered by pixelmatch
• Exclusion Zones — Skip regions during comparison with excludedAreas
• Diff Output — Optionally write a diff PNG with highlighted mismatches
• TypeScript Support — Full type definitions included

Table of Contents

• Installation
• Migration Guide
• Quick Start
• Snapshot Matchers
• API Reference
• Excluded Areas Builder
• Contributing
• License

---

Installation

npm install -D png-visual-compare

Platform Requirement: macOS or Linux only. Windows is not supported.

Node.js Requirement: Node.js 20 or higher is required.

---

Migration Guide to v6.0.0

1. Replace PngData imports with LoadedPng.
2. Recheck any caller-supplied excludedAreas, pixelmatchOptions, diffFilePath, inputBaseDir, and diffOutputBaseDir.
3. If your code already uses async filesystem orchestration, switch to comparePngAsync.

1. Replace PngData with LoadedPng

PngData is no longer exported. If you imported it from the package, switch to LoadedPng:

// Before
import type { PngData } from 'png-visual-compare';

// After
import type { LoadedPng } from 'png-visual-compare';

2. Expect stricter option validation

The library now fails fast for malformed option data instead of relying on downstream behavior:

• excludedAreas must be an array of non-negative finite integer rectangles with x1 <= x2 and y1 <= y2
• pixelmatchOptions must be an object with validated numeric/boolean/tuple fields
• diffFilePath, inputBaseDir, and diffOutputBaseDir must be strings when provided
• diffFilePath now rejects existing directories and existing symlinks in output mode

3. Security/resource limits still throw in permissive mode

throwErrorOnInvalidInputData: false only downgrades ordinary invalid-image inputs. Security, resource-boundary, and comparison-kernel checks still throw:

• inputBaseDir / diffOutputBaseDir containment violations → PathValidationError
• symlink traversal and invalid output target checks → PathValidationError
• maxDimension / maxPixels limits → ResourceLimitError
• failures inside the underlying pixelmatch call → ComparisonError (the original error is preserved on cause)

4. Use comparePngAsync for promise-based I/O

If your integration already uses async filesystem orchestration, prefer:

import { comparePngAsync } from 'png-visual-compare';

It preserves the same comparison semantics as comparePng, but performs file-backed reads/writes asynchronously.

---

Quick Start

import { comparePng, comparePngAsync } from 'png-visual-compare';

const mismatchedPixels: number = comparePng(
    img1, // First PNG: absolute file path or Buffer
    img2, // Second PNG: absolute file path or Buffer
    {
        excludedAreas, // Regions to skip during comparison. Default: []
        diffFilePath, // Path to write the diff PNG (only written when mismatch > 0). Default: undefined
        throwErrorOnInvalidInputData, // Throw on missing/invalid input. Default: true
        extendedAreaColor, // Color used for size-padding regions. Default: { r: 0, g: 255, b: 0 }
        excludedAreaColor, // Color used for excluded areas. Default: { r: 0, g: 0, b: 255 }
        maxDimension, // Max allowed image width/height in px. Always throws if exceeded. Default: 16384
        maxPixels, // Max allowed decoded pixel count per image/canvas. Default: 16777216
        diffOutputBaseDir, // Restrict diffFilePath writes to this directory (path-traversal guard). Default: undefined
        inputBaseDir, // Restrict png1/png2 reads to this directory (path-traversal guard). Default: undefined
        pixelmatchOptions, // Public PixelmatchOptions validated and adapted for pixelmatch. Default: undefined
    },
);

expect(mismatchedPixels).toBe(0);

const asyncMismatchedPixels = await comparePngAsync(img1, img2, { diffFilePath: './diff.png' });

expect(asyncMismatchedPixels).toBe(0);

---

Snapshot Matchers

The package also ships side-effect matcher plugins for Vitest and Jest so PNG diff buffers can be asserted with toMatchPngSnapshot().

Vitest

Register the matcher in your test setup file:

import 'png-visual-compare/vitest';

Then assert any PNG Buffer or Uint8Array:

import { readFileSync } from 'node:fs';

expect(readFileSync('./diff.png')).toMatchPngSnapshot();
expect(readFileSync('./dark-mode-diff.png')).toMatchPngSnapshot('dark mode diff');
expect(readFileSync('./masked-diff.png')).toMatchPngSnapshot({
    excludedAreas: [{ x1: 0, y1: 0, x2: 20, y2: 20 }],
});
expect(readFileSync('./thresholded-diff.png')).toMatchPngSnapshot('thresholded diff', {
    pixelmatchOptions: { threshold: 0.2 },
});

Update stored snapshots with the normal Vitest command:

npx vitest run -u

Jest

Register the matcher from setupFilesAfterEnv:

import 'png-visual-compare/jest';

Then use it the same way in tests:

import { readFileSync } from 'node:fs';

expect(readFileSync('./diff.png')).toMatchPngSnapshot();
expect(readFileSync('./dark-mode-diff.png')).toMatchPngSnapshot('dark mode diff');
expect(readFileSync('./masked-diff.png')).toMatchPngSnapshot({
    excludedAreas: [{ x1: 0, y1: 0, x2: 20, y2: 20 }],
});
expect(readFileSync('./thresholded-diff.png')).toMatchPngSnapshot('thresholded diff', {
    pixelmatchOptions: { threshold: 0.2 },
});

Update stored snapshots with Jest's normal snapshot flow:

npx jest -u

If your Jest config uses injectGlobals: false, register the matcher explicitly in your setup file:

import { expect } from '@jest/globals';
import { registerJestPngSnapshotMatcher } from 'png-visual-compare/jest';

registerJestPngSnapshotMatcher(expect);

toMatchPngSnapshot() is intentionally strict: it accepts only PNG Buffer / Uint8Array input, and passes any provided ComparePngOptions to comparePng when checking the stored snapshot.

Negated assertions

expect(received).not.toMatchPngSnapshot() asserts that the received PNG differs from the stored snapshot:

expect(await page.screenshot()).not.toMatchPngSnapshot('light mode');

• Passes when the received PNG differs from the stored snapshot beyond the configured threshold.
• Fails when they match.
• Never writes or updates a snapshot, even under -u — you cannot record what an image must not be.
• Throws when no snapshot is stored. A missing baseline would otherwise pass vacuously, which is a false green. Record the baseline with a positive toMatchPngSnapshot() first.

---

API Reference

comparePng(png1, png2, opts?): number

Compares two PNG images pixel-by-pixel and returns the number of mismatched pixels (0 means identical).

Parameters:

Parameter	Type	Description
png1	string | Buffer	First PNG — absolute file path or raw PNG Buffer
png2	string | Buffer	Second PNG — absolute file path or raw PNG Buffer
opts	ComparePngOptions	Optional configuration object

---

comparePngAsync(png1, png2, opts?): Promise<number>

Async equivalent of comparePng. It performs the same comparison flow, but uses fs.promises for file-backed reads and diff writes.

---

ComparePngOptions

Option	Type	Default	Description
excludedAreas	Area[]	[]	Rectangular regions to exclude from comparison (painted on both images before diffing, so they always match)
diffFilePath	string	undefined	File path for the diff PNG. Only written when result > 0
throwErrorOnInvalidInputData	boolean	true	Throw on missing/unsupported input. Set to false to treat invalid input as a zero-size PNG. An error is always thrown when both inputs are invalid
extendedAreaColor	Color	{ r: 0, g: 255, b: 0 }	Fill colour for padded regions when images differ in size. Override when the default green clashes with your image content
excludedAreaColor	Color	{ r: 0, g: 0, b: 255 }	Fill colour applied to excludedAreas on both images before comparison. Override when the default blue clashes with your image content
maxDimension	number	16384	Maximum allowed width or height (px) for either input image. Always throws when exceeded, regardless of throwErrorOnInvalidInputData. Set to Infinity to disable. Protects against DoS via crafted PNG headers
maxPixels	number	16777216	Maximum decoded pixel count for a single input image and for the normalized comparison canvas. Set to Infinity to disable. Protects against large-but-axis-valid PNGs that would still exhaust memory
diffOutputBaseDir	string	undefined	When set, diffFilePath must resolve to a path inside this directory. Any attempt to write outside it throws "Path traversal detected". Use in server-side contexts where diffFilePath may be caller-controlled
inputBaseDir	string	undefined	When set, string input paths (png1 / png2) must resolve to a path inside this directory. Any attempt to read outside it throws "Path traversal detected". Use in server-side contexts where paths may be caller-controlled
pixelmatchOptions	PixelmatchOptions	undefined	Options forwarded to pixelmatch

---

Area

type Area = {
    x1: number; // left edge (pixels from left)
    y1: number; // top edge (pixels from top)
    x2: number; // right edge (pixels from left, inclusive)
    y2: number; // bottom edge (pixels from top, inclusive)
};

---

Color

type Color = {
    r: number; // red channel (0-255)
    g: number; // green channel (0-255)
    b: number; // blue channel (0-255)
};

---

PixelmatchOptions

Option	Type	Default	Description
threshold	number	0.1	Matching threshold 0–1. Lower = more sensitive
includeAA	boolean	false	When true, anti-aliased pixels count as mismatches
alpha	number	0.1	Opacity of unchanged pixels in the diff image
aaColor	[r, g, b]	[255, 255, 0]	Colour of anti-aliased pixels in the diff
diffColor	[r, g, b]	[255, 0, 0]	Colour of differing pixels in the diff
diffColorAlt	[r, g, b]	undefined	Alternative diff colour for dark pixels (dark-mode support)
diffMask	boolean	false	Show only changed pixels on a transparent background
checkerboard	boolean	true	Blend semi-transparent pixels against a checkerboard (vs white)

Errors

All public errors extend the built-in Error and expose a stable string code for runtime matching without parsing messages. Match either via instanceof or via code:

Class	code	When it throws
InvalidInputError	ERR_INVALID_PNG_INPUT	A PNG input is missing, malformed, or cannot be decoded. Recoverable via throwErrorOnInvalidInputData: false (treated as a zero-size PNG)
PathValidationError	ERR_PATH_VALIDATION	A file path fails validation: traversal outside a base directory, symlink at the output target, empty/null-byte path
ResourceLimitError	ERR_RESOURCE_LIMIT	A PNG would exceed maxDimension or maxPixels. Always throws regardless of throwErrorOnInvalidInputData
ComparisonError	ERR_COMPARISON	The underlying pixelmatch call threw. The original failure is preserved on the standard cause property. Always throws

import { comparePng, ComparisonError } from 'png-visual-compare';

try {
    comparePng(img1, img2);
} catch (error) {
    if (error instanceof ComparisonError) {
        console.error('Pixel comparison failed:', error.message);
        console.error('Underlying:', error.cause);
    }
}

Exported constants

Constant	Value	Description
DEFAULT_EXTENDED_AREA_COLOR	{ r: 0, g: 255, b: 0 }	Default fill colour for size-extended padding regions
DEFAULT_EXCLUDED_AREA_COLOR	{ r: 0, g: 0, b: 255 }	Default fill colour for excluded areas
DEFAULT_MAX_DIMENSION	16384	Default maximum image dimension (px). Import this constant when you want to reference the default value
DEFAULT_MAX_PIXELS	16777216	Default maximum decoded pixel count for one image or the normalized comparison canvas

---

Excluded Areas Builder

Defining excludedAreas coordinates by hand can be tedious. The Excluded Areas Builder is a browser-based visual tool included in this repository that lets you draw exclusion rectangles directly on your image and copy the resulting Area[] JSON with one click.

Launch

npm run tool:excluded-areas-builder

This opens tools/excluded-areas-builder.html in your default browser on macOS or Linux. No server or build step is required — the file runs entirely in the browser.

How to use

1. Load your image

Either click Upload Image in the toolbar or drag and drop any PNG (or other image format) onto the page.

2. Zoom to a comfortable level

• Click Fit to scale the image to fit the viewport (default on load).
• Click + / − to zoom in or out in 25% steps.
• Hold Ctrl (or Cmd on macOS) and scroll to zoom continuously.

3. Draw exclusion rectangles

Click and drag on the image to draw a rectangle. Release the mouse to commit it. Each committed rectangle is shown with an orange border and a #N label in its top-left corner matching the numbered list in the sidebar.

4. Select and delete rectangles

• Click a rectangle on the image or its entry in the sidebar to select it (turns blue).
• Press Delete or Backspace to remove the selected rectangle, or click the × button next to any entry in the sidebar.
• Click Clear all to remove every rectangle at once.
• Press Escape to deselect without deleting.

5. Copy the JSON

The Area[] JSON panel in the sidebar updates live as you draw. Click Copy to copy the JSON to your clipboard, then paste it directly into your comparePng call:

import { comparePng } from 'png-visual-compare';

const mismatchedPixels = comparePng(img1, img2, {
    excludedAreas: [
        { x1: 120, y1: 45, x2: 340, y2: 210 },
        { x1: 500, y1: 300, x2: 650, y2: 400 },
    ],
});

All coordinates are in original image pixels regardless of the current zoom level.

---

Contributing

See CONTRIBUTING.md for development setup, commands, and PR guidelines.

---

License

MIT dichovsky

Buy Me A Coffee

Support this project: