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 the global tolerance, which is 0 by default

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 values in args are optional, you only need to overwrite the options which you want to customize.

All options that are currently supported by pixelmatch:

args = {
    threshold: 0.05,
    alpha: 0.5,
    includeAA: false,
    aaColor: [128, 128, 128],
    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.

Defaults to the global threshold, which is 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.

Default is 0.5.

args.includeAA

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

Default is false.

args.aaColor

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

Default is [128, 128, 128].

args.diffColor

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

Default is [255, 0, 0].

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.

Default is null.

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).

Default is false

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 the global dumpIntermediateImage flag, which is false by default.

captureActual

Whether to capture a new screenshot and use it as actual image, instead of loading the image from the dirActual folder. This happens before the image comparison.

The new screenshot is saved to the dirActual folder before comparison, and will replace an existing file with the same name!

Possible values: true will always capture the screenshot, false never captures the screenshot, "missing" captures the screenshot if the image file does not exist.

Defaults to the global captureActual flag, which is "missing" by default.

captureExpected

Whether to update the expected base image with a current screenshot before starting the comparison.

The new screenshot is saved to the dirExpected folder, and will replace an existing file with the same name!

Possible values: true will always capture the screenshot, false never captures the screenshot, "missing" captures the screenshot if the image file does not exist.

Defaults to the global captureExpected flag, which is "missing" by default.

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,

    // Whether to take a screenshot for the actual image before comparison.
    captureActual: "missing",

    // Whether to take a screenshot for the expected image before comparison.
    captureExpected: "missing"
}

---

← Method: takeScreenshot() | Comparison Results →