vitest-image-snapshot weekly downloads statistics

Image Snapshot Testing

Visual regression testing for images. Compare rendered outputs against reference images to catch visual bugs.

• Native vitest integratio • Accepts ImageData or PNG buffers - test WebGPU, Canvas, or any image processing • Aggregated HTML diff report for visual failures

Setup

1. Install

2. Import in your test file

3. (Optional) Configure HTML diff report

Configure the reporter in vitest.config.ts:

Default behavior (no configuration): • Report location: {vitest.config.root}/image_diff_report/index.html • Auto-open: failures (can override with IMAGE_DIFF_AUTO_OPEN=always or IMAGE_DIFF_AUTO_OPEN=never env var)

Configuration options: • reportPath: Absolute or relative to config.root (default: 'image_diff_report') • autoOpen: Auto-open report in browser on failures, always or never (default: 'failures' or 'never' on CI) • port: Port for html report server (default: 4343)

Basic Usage

Accepts standard browser ImageData or Buffer (pre-encoded PNGs):

Options

See Match Options for all available configuration options.

Updating Snapshots

When you intentionally change shader behavior:

Diff Report

If you added ImageSnapshotReporter to vitest.config.ts, failed tests generate a self-contained HTML report with: • Expected vs Actual side-by-side • Diff visualization (mismatched pixels highlighted) • Mismatch statistics • All images copied to report directory (portable and shareable)

Default location: {vitest.config.root}/image_diff_report/index.html

Monorepo behavior: In workspace mode (running tests from workspace root), each package's report goes to its own directory when using absolute paths in config.

Auto-open on failure:

Or enable via inline reporter config:

IMAGE_DIFF_AUTO_OPEN will override reporter config if both are set.

CI

When a CI environment is detected then IMAGE_DIFF_AUTO_OPEN and config options are ignored and autoOpen is set to "never".

The report is still generated and can be saved as an artifact for review or published to a static hosting service if you prefer.

Directory Structure

Notes: • image_actual/ saves on every run (pass or fail) for manual inspection • Report copies all images to image_diff_report/ preserving directory structure • Report is self-contained and portable (can be zipped, shared, or committed)

API Reference

toMatchImage()

Vitest matcher for comparing images against reference snapshots.

Parameters:

• imageData: ImageData | Buffer - Image to compare • nameOrOptions?: string | MatchImageOptions - Snapshot name or options

Match Options:

How Comparison Works

Image comparison uses pixelmatch, which converts RGB to YIQ color space for perceptually-weighted comparison. YIQ separates luminance (Y) from chrominance (I, Q), making the comparison more aligned with human perception than raw RGB byte comparison.

The threshold option (0-1) controls sensitivity to color differences in YIQ space.

Color space note: Images are compared as raw RGBA bytes. If using display-p3 (supported in WebGPU via GPUCanvasConfiguration.colorSpace), ensure both reference and actual images use the same color space.

Examples

WebGPU Shaders

Canvas/DOM ImageData

Troubleshooting

"No reference snapshot found"

First run: Snapshot created automatically CI: Run with -u locally first, then commit snapshots

Images don't match but look identical

• threshold too strict - increase tolerance • GPU/driver differences - use allowedPixelRatio • Anti-aliasing differences - set includeAA: true

Build Version

vitest-image-snapshot is currently part of the wesl-js monorepo. (It'll eventually move to it's own repo).

Contributions

See Implementation.md for details and feature ideas.

Description from the npm listing.