vitest-screenshot
Interfaces
ComparatorRegistry
Comparator names and their options. Augment this interface when registering a custom comparator.
Properties
| Property | Type | Description |
|---|---|---|
metrics | MetricsOptions | Options of the metrics comparator. |
pixelmatch | PixelmatchOptions | Options of the default pixelmatch comparator. |
Type Aliases
Comparator
type Comparator<Options> = (reference, actual, options) => ComparatorResult;
A comparator, with the signature Vitest browser mode uses for comparators.
Type Parameters
| Type Parameter | Default type | Description |
|---|---|---|
Options extends object | Record<string, unknown> | The comparator's own options, taken from comparatorOptions. |
Parameters
| Parameter | Type | Description |
|---|---|---|
reference | RgbaImage | The baseline image. |
actual | RgbaImage | The image under test. |
options | Options & object | The comparator options plus createDiff, which says whether a diff image is wanted. |
Returns
Whether the images match, with an optional diff image and message.
ComparatorResult
type ComparatorResult = object;
What a comparator returns, as in Vitest browser mode: diff is written next to the baseline on failure.
Properties
diff
diff: RgbaImage | null;
An image of the differences, written as <name>.diff.png on failure, or null for none.
message
message: string | null;
A description of the result, included in the failure message.
pass
pass: boolean;
Whether the two images count as the same.
ComparatorSelection
type ComparatorSelection =
| { [Name in ComparatorName]: { comparatorName: Name; comparatorOptions?: ComparatorOptions<Name> } }[ComparatorName]
| {
comparatorName?: undefined;
comparatorOptions?: ComparatorOptions<ComparatorName>;
};
Which registered comparator judges the images. pixelmatch is the default.
Union Members
{ [Name in ComparatorName]: { comparatorName: Name; comparatorOptions?: ComparatorOptions<Name> } }[ComparatorName]
Type Literal
{
comparatorName?: undefined;
comparatorOptions?: ComparatorOptions<ComparatorName>;
}
| Name | Type | Description |
|---|---|---|
comparatorName? | undefined | Omitted: the comparator chosen in extendMatchers() applies, or pixelmatch by default. |
comparatorOptions? | ComparatorOptions<ComparatorName> | Options for the default comparator. |
ImageSource
type ImageSource =
| RgbaImage
| {
readPixels(): Promise<RgbaImage>;
}
| {
getImageData(): RgbaImage;
}
| {
decode(): Promise<void>;
};
A source of pixels: an RgbaImage / ImageData, a WebGPU HeadlessCanvas (readPixels()), a node-webgl
Canvas (getImageData()), or a node-webgl Image (decoded with decode()).
Union Members
Type Literal
{
readPixels(): Promise<RgbaImage>;
}
| Name | Type | Description |
|---|---|---|
readPixels() | () => Promise<RgbaImage> | Reads the pixels back from the GPU, as the WebGPU environment's HeadlessCanvas does. |
Type Literal
{
getImageData(): RgbaImage;
}
| Name | Type | Description |
|---|---|---|
getImageData() | () => RgbaImage | Returns the canvas pixels synchronously, as node-webgl's Canvas does. |
Type Literal
{
decode(): Promise<void>;
}
| Name | Type | Description |
|---|---|---|
decode() | () => Promise<void> | Decodes the image so its pixels can be read, as node-webgl's Image does. |
Metric
type Metric = "AE" | "PAE" | "MAE" | "MSE" | "RMSE" | "PSNR" | "SSIM" | "DSSIM";
ImageMagick compare -metric names. Upper bounds: AE PAE MAE MSE RMSE DSSIM. Lower bounds: PSNR SSIM.
MetricsOptions
type MetricsOptions = object;
Options of the metrics comparator: error bounds named as in ImageMagick's compare -metric. Give any subset.
Properties
AE?
AE?: number;
Absolute error: pixels differing by more than fuzz. Default bound when no metric is given: 0.
DSSIM?
DSSIM?: number;
Structural dissimilarity, (1 - SSIM) / 2.
fuzz?
fuzz?: number;
ImageMagick -fuzz: per-channel RMS colour distance (0..1) within which two pixels count as equal. Default 0.
MAE?
MAE?: number;
Mean absolute error, 0..1.
MSE?
MSE?: number;
Mean squared error, 0..1.
PAE?
PAE?: number;
Peak absolute error, 0..1.
PSNR?
PSNR?: number;
Peak signal-to-noise ratio in dB (lower bound). Infinity for identical images.
RMSE?
RMSE?: number;
Root mean squared error, 0..1.
SSIM?
SSIM?: number;
Structural similarity, 1 = identical (lower bound). Gaussian 11x11 window, sigma 1.5, over RGB.
PixelmatchOptions
type PixelmatchOptions = NonNullable<Parameters<typeof pixelmatch>[5]> & object;
Options of the default pixelmatch comparator, named as in Vitest browser mode.
Type Declaration
| Name | Type | Description |
|---|---|---|
allowedMismatchedPixelRatio? | number | Fraction (0..1) of pixels allowed to differ. |
allowedMismatchedPixels? | number | Number of pixels allowed to differ. With both limits given the stricter wins; with neither, none may differ. |
Reference
type Reference = string | ImageSource;
A baseline: a file path with extension (relative to baselineDir or absolute), or an in-memory ImageSource.
RgbaImage
type RgbaImage = object;
Anything with RGBA8 pixels, top row first: ImageData, node-webgl's canvas.getImageData(), or a WebGPU readback.
Properties
data
data: Uint8Array | Uint8ClampedArray;
RGBA8 bytes, four per pixel, row by row from the top.
height
height: number;
Height in pixels.
width
width: number;
Width in pixels.
ScreenshotConfig
type ScreenshotConfig = ComparatorSelection & object;
Defaults for every assertion plus custom comparators, like test.browser.expect.toMatchScreenshot in Vitest config.
Type Declaration
| Name | Type | Description |
|---|---|---|
comparators? | { [Name in ComparatorName]?: Comparator<ComparatorOptions<Name>> } | Custom comparators, keyed by the name used in comparatorName. |
ScreenshotOptions
type ScreenshotOptions = ComparatorSelection & object;
Options for one toMatchScreenshot() assertion: the comparator selection plus where baselines live.
Type Declaration
| Name | Type | Description |
|---|---|---|
baselineDir? | string | Directory relative reference paths and diff images live in. Default: __screenshots__ beside the test file. |
update? | boolean | Override Vitest's snapshot update mode. true creates/overwrites; false prevents both. |
Variables
pixelmatchComparator
const pixelmatchComparator: Comparator<PixelmatchOptions>;
comparatorName: 'pixelmatch' (default): Vitest browser mode's built-in comparison.
Functions
extendMatchers()
function extendMatchers(config?): void;
Registers toMatchScreenshot() on Vitest's expect. Call it once per test file, or from a setup file.
Parameters
| Parameter | Type | Description |
|---|---|---|
config? | ScreenshotConfig | Default comparator and options for every assertion, and any custom comparators. |
Returns
void