Applies to TestComplete 14.10, last modified on June 5, 2019

This topic describes how the TestComplete image comparison engine works. The same comparison engine is used by region checkpoints, image-based testing, by a number of scripting methods and by the test log when it displays images captured by Test Visualizer during recording and playback. Since the procedure of finding one image within another also implies image comparison, the same comparison engine is used to perform both tasks.

The topic contains the following sections:

General Idea of Comparison Algorithm

The general idea is very simple - pixel-by-pixel comparison.

The comparison engine gets the color of pixels that have the same coordinates within the image and compares this color. If the color of each pixel of both images coincides, TestComplete considers the two images to be identical.

Pixel-by-pixel comparison

Comparison Engine Parameters

The comparison engine has a number of parameters. Each of the parameters enables additional processing of bitmaps, which makes comparison more flexible.

Below is a list of the comparison engine's parameters and their descriptions. You specify these parameters when creating a region checkpoint or when calling scripting methods that perform image comparison. The parameters are not used by the test log when it compares images that were captured during recording and playback and posted to the log by Test Visualizer.

  • Pixel Tolerance - Defines the allowed number of dissimilar pixels. If the number of different pixels is less than or equal to PixelTolerance, then TestComplete considers the images to be identical.

    For instance, in the image below, one bitmap differs from another by two pixels. If the PixelTolerance value were 2, TestComplete would consider these bitmaps to be identical.

  • Color Tolerance - Specifies an acceptable color difference at which two pixels should be treated as identical. The color difference is represented as an integer value within the range 0…255 that specifies an acceptable difference for each color component (red, green and blue) of the compared pixels. Two pixels are considered identical if the difference between intensities of each of their color components does not exceed the specified value.

    When ColorTolerance is 0, which is the default value, the compared pixels are considered identical only if they have exactly the same color. When ColorTolerance is 255, pixels of any color are considered identical.

  • Include Mouse Pointer - (Not available via the Region Checkpoint wizard and in image-based tests) Defines whether TestComplete should capture the mouse cursor when it gets the image to be compared. By default, screenshots are taken without the image of the cursor. This makes image comparison independent of the mouse cursor position.

    However, if the cursor position is significant for you, you can enable the Mouse comparison parameter. In this case, TestComplete will include the mouse pointer in the captured image.

    Note: When the Mouse parameter is enabled, the comparison succeeds only if both the baseline and compared images contain the mouse pointer image in the same position.
  • “Transparent” Color - (Not available via the Region Checkpoint wizard and in image-based tests) If this parameter is True (enabled), TestComplete treats the color of the upper-left pixel of the baseline image as a transparent color and does not compare all the pixels that have the same coordinates in the compared image as the transparent pixels have in the baseline image. This parameter is similar to the way transparency is implemented in the .ICO and .GIF formats.

    For instance, if the top-left pixel is gray, then all gray pixels of the first image will match pixels of any color that have the same coordinates in the second image:

  • Comparison Mask - (Not available in image-based tests) Specifies which areas of bitmaps should be compared. A mask is another image (the Picture object) whose pixels can be either black or white. If a mask is specified, the comparison engine works in the following way: white pixels on the mask are taken into account during comparison, whereas black pixels are ignored. In contrast to using the Transparent parameter, you do not need to modify the baseline image, you just create a separate image instead.

    For example, the following two different bitmaps can be considered identical if a mask is used.

  • Alpha Channel - It is an implicit parameter of the comparison engine. In addition to the color for each pixel, BMP, PNG and TIFF images may also contain information that denotes pixels' transparency - the so called alpha channel. Depending on the alpha value, a pixel may range from fully transparent (0%), through semi-transparent to fully opaque (100%).

    If the baseline image contains the alpha channel, the comparison is performed regarding the pixel’s transparency. Fully transparent pixels are ignored during the comparison, opaque pixels should have the same color to be reported as matching, and the colors of semi-transparent pixels should resemble one another to some degree (at that, the degree of conformity is determined by the alpha value).


    TestComplete takes into account alpha channel data of the baseline image. It ignores alpha channel data of the second image. If the images have the same data in their RGB channels and they differ only by their alpha channel data, TestComplete considers these images identical.

Factors Affecting Comparison

Pixel-by-pixel comparison is considered successful only if the compared image and the baseline image are absolutely identical. To improve the quality of image comparison, you should capture the image you want to compare in the same conditions the baseline image was captured.

Sometimes, the compared image and the baseline one seem to be identical, however, the comparison of the images fails when you do not expect a failure. There are some factors that affect image comparison and that may lead to unexpected comparison results. For detailed information on these factors, see Factors Affecting Image Comparison. You can also find information on the most probable reasons of image comparison failures in the Why Image Comparison Fails topic.

See Also

Region Checkpoints
About Region Checkpoints
Factors Affecting Image Comparison
Why Image Comparison Fails
Comparing and Finding Images - Specific Tasks
Alternatives to Region Checkpoints
Finding an Image Within Another Image

Highlight search results