Comparison Options

Both methods checkVisualDifferences() and getVisualDifferences() accept an object that specifies custom comparison options. The following options are available:

Details

tolerance

Percentage of pixels that are allowed to differ between both images.

Default is 0

compareWith

Defines a custom comparison image name.

Default is empty.

element

Only compare a single HTML element. Used to calculate a bounding box.

Default is empty.

bounds

Only used, when element is not set. Only pixels inside this box are compared.

Tip: Dimensions are automatically retrained inside the image - if your ignore-box is wider or taller than the image, the box is internally resized to match your image. For example, it's possible to set the width to something really big to ensure the entire image-width is covered.

// Compare a 800x600 area with an offset 
// of 120 (left) and 200 (top).
bounds = {
    left: 120,
    top: 200,
    width: 800,
    height: 600 
}

// Compare a 100-pixel column at the left edge of the image.
bounds = {
    left: 0,
    top: 0,
    width: 100,
    height: 99999 
}

ignore

List of boxes to ignore. Each box is an object that defines the following attributes: left, top, width, height. Dimensions behave identical as in the bounds box above.

Default is an empty array.

Example:

// This configuration ignores two areas: 
// (1) the top-most 120 pixels
// (2) a 100x100 square that's 200px from the left and 200px 
//     from top corner.
ignore = {
    {left: 0,   top: 0,   width: 99999, height: 120},
    {left: 200, top: 200, width: 100,   height: 100}
}

args

Arguments that are passed to the pixelmatch library. All args are optional, you only need to overwrite only the options which you want to customize.

All options that are currently supported by pixelmatch:

args = {
    threshold: 0.1,
    alpha: 0.5,
    includeAA: false,
    aaColor: [255, 255, 0],
    diffColor: [255, 0, 0],
    diffColorAlt: null,
    diffMask: false
}

args.threshold

(float) - Matching threshold, ranges from 0 to 1. Smaller values make the comparison more sensitive. 0.1 by default.

args.alpha

(float) - Blending factor of unchanged pixels in the diff output. Ranges from 0 for pure white to 1 for original brightness. 0.1 by default.

args.includeAA

(boolean) - If true, disables detecting and ignoring anti-aliased pixels. false by default.

args.aaColor

(RGB-array) - The color of anti-aliased pixels in the diff output in [R, G, B] format. [255, 255, 0] by default.

args.diffColor

(RGB-array) - The color of differing pixels in the diff output in [R, G, B] format. [255, 0, 0] by default.

args.diffColorAlt

(RGB-array) - An alternative color to use for dark on light differences to differentiate between "added" and "removed" parts. If not provided, all differing pixels use the color specified by diffColor. null by default.

args.diffMask

(boolean) - Draw the diff over a transparent background (a mask), rather than over the original image. Will not draw anti-aliased pixels (if detected).

dumpIntermediateImage

Whether to save the intermediate images to the global output folder, after applying the bounds and ignore-boxes. That way, you can see, which parts of the image are actually compared.

This is useful for debugging your tests, but not recommended for production usage.

Intermediate images are always saved to the output directory, and are named <image>.expected.png and <image>.actual.png

Defaults to false

Defaults

The full list of all available options with their defaults:

options = {
    tolerance: 0,

    // Defines a custom comparison image name.
    compareWith: '',

    // Only compare a single HTML element. Used to calculate a
    // bounding box.
    element: '',

    // Only used, when element is not set. Only pixels inside
    // this box are compared.
    bounds: {
        left: 0,
        top: 0,
        width: 0,
        height: 0
    },

    // List of boxes to ignore. Each box is an object with 
    // {left, top, width, height}.
    ignore: [],

    // Arguments that are passed to the pixelmatch library.
    args: {
        threshold: 0.1,
        alpha: 0.5,
        includeAA: false,
        diffMask: false,
        aaColor: [255, 255, 0],
        diffColor: [255, 0, 0],
        diffColorAlt: null
    },

    // Whether to dump intermediate images before comparing them.
    dumpIntermediateImage: false
}