ODiff

Install the playwright-odiff package via npm to use a faster and more reliable replacement for Playwright's .toHaveScreenshot() matcher.

npm install playwright-odiff

To use ODiff for visual regression testing in Playwright, install the playwright-odiff package. You must import the setup in your test entrypoint or setup file to enable the custom matchers.

// in your setup file or test entrypoint
import "playwright-odiff/setup";

expect(page).toHaveScreenshotOdiff("screenshot-name", { /* any odiff and playwright options */ });

To use playwright-odiff, you must register it in your top-level Playwright setup script (the file where you configure test, extend, or your common test entrypoint).

For macOS users, ensure gnu-sed is installed via brew install gnu-sed if you intend to use the automated migration command.

import "playwright-odiff/setup"

The recommended cross-platform way to install Odiff is via the odiff-bin npm package. The package includes platform-specific binaries and a post-install script that automatically links the correct binary for your current platform.

Note: The package name is odiff-bin, but the command-line tool is odiff.

npm install odiff-bin

You can manually replace expect(...).toHaveScreenshot() with expect(...).toHaveScreenshotOdiff().

If you are on macOS and have gnu-sed installed, you can use the following command to automatically update all .spec.ts files in your project:

To run performance benchmarks for image difference tools, ensure you have the following tools installed:

1. odiff
2. pixelmatch
3. ImageMagick
4. hyperfine (used to execute and compare performance tests)

On macOS, you can install hyperfine using Homebrew:

brew install hyperfine

Odiff can be used as a command-line tool to perform visual regression testing by comparing a base image against a comparison image. It supports various modes including terminal graphics display, saving diff outputs to files, and parsable stdout for automation.

Exit Codes

• 0: Images are identical.
• 21: Images have different dimensions (layout mismatch).
• 22: Images have pixel differences.
• 1: An error occurred (e.g., file not found, unsupported format, or invalid arguments).

Parsable Output Format

When using the --parsable-stdout flag, the tool outputs data in a machine-readable format: count;percentage[;lines][;cols]

• count: Number of different pixels.
• percentage: Percentage of different pixels.
• lines: Comma-separated list of different line indices (if requested).
• cols: Comma-separated list of different column indices (if requested).

To use playwright-odiff, you must register the custom matchers globally by importing the setup file (typically located at ./dist/setup.js in the package distribution) within your playwright.config.ts. This enables the Odiff-specific assertion capabilities within your Playwright tests.

// Register custom matchers once globally
import './dist/setup.js';

import { defineConfig } from '@playwright/test';

export default defineConfig({
  // ... rest of config
});

ODiff can be run in a server mode where it reads JSON requests from stdin and writes JSON responses to stdout. This is useful for integrating ODiff into a pipeline or a long-running process.

When the server starts, it immediately emits a {"ready":true} response to signal it is ready for commands.

If using "type": "buffer", you must provide the length and format for both the base and comparison images. The server reads the exact number of bytes specified from stdin immediately following the JSON command line.

Note: The server uses readSliceAll to ensure it reads the exact byte count, as binary data may contain newline characters.

Required fields for buffer mode:

• baseLength (integer): Size of the base image buffer in bytes.
• baseFormat (string): Format of the base image (e.g., png, jpeg, jpg, bmp, tiff, webp).
• compareLength (integer): Size of the comparison image buffer in bytes.
• compareFormat (string): Format of the comparison image.

Odiff is a SIMD-accelerated pixel-by-pixel image comparison tool. You can run it from the command line by providing a base image and a comparison image. Optionally, you can specify a path for the diff output.

Basic Usage: odiff <base_image> <comp_image> [diff_output] [options]

Exit Codes:

• 0: Images match
• 21: Layout difference (if --fail-on-layout is used)
• 22: Pixel differences found