Description

Use the Region Checkpoint operation to compare images of windows or controls or rectangular areas within them, with images that are stored in the Stores | Regions collection of a TestComplete project. The operation compares the images pixel by pixel. If the images are identical, the operation posts a success message to the test log. Otherwise, it posts a failure message. In both cases, the Picture panel in the test log displays the baseline image stored in the Stores | Regions collection and the image compared with the baseline one. Switching to the Comparison mode in the Picture panel allows you to view the difference between the images (if any). For more information on this, see Generic Test Log - Picture Panel.

You can also use the operation to update the stored images. The functioning mode of the operation is specified by the Update regions setting (you can modify it in the Stores Options dialog). By default the setting is disabled, and the operation performs the comparison. To use the operation for updating a stored image, enable the setting and check the Update box for the image in the Regions Editor. If the setting is enabled, but the Update check box is clear, the operation works in comparison mode.

The operation can compare or update the images of the following formats:

BMP
JPEG
PNG
TIFF
GIF
ICO

Operation Result

In comparison mode, if the comparison procedure reports that the images are identical, the operation returns True and posts a checkpoint message () to the test log. Otherwise, the operation returns False and posts an error message () to the log.

In update mode the operation always returns True.

Scripting Analogue

The operation is analogue to the Region.Check scripting method.

Child Operations

The operation cannot have child operations.

Operation Parameters

The Region Checkpoint operation uses the following parameters:

Picture

Specifies the image to be compared with the baseline image stored in the Regions collection. To specify this parameter, you can use the following values:

The name of the Regions collection’s item (if the image is stored to this collection of your project).
The full name of a window or onscreen object.
An expression that returns or value that holds a reference to the RegionInfo object.
An expression that returns or value that holds a reference to the Picture object.
The fully-qualified name of the image file on hard drive.

If the operation works in update mode, then the parameter cannot specify an item of the Regions collection.

Transparent

False by default. If it is True, the top left pixel of the baseline image stored in the Regions collection will be treated as the “transparent” (background) color in this image. Therefore, any transparent pixels in the baseline image will be excluded when being compared with another image. All pixels of this color are excluded from comparison.

Mouse

The Mouse parameter specifies whether the mouse pointer is included into the image used for comparison. By default this parameter is False. If it is True and the Picture parameter specifies an object (for example, a window, onscreen or RegionInfo object) with the mouse pointer over this object, then the mouse pointer is included in this image for comparison. The operation will return True only if the other image also contains the mouse pointer image in the same position.

PixelTolerance

Lets you ignore slight differences between the images during the comparison. If the number of different pixels is less than or equal to PixelTolerance, then TestComplete considers the images to be identical. 0 is the default value; it means that no differences between the bitmaps except for those set by the Transparent parameter are ignored.

Note:

Using the PixelTolerance parameter with non-zero values may slow down the comparison process.

ColorTolerance

Allows ignoring hue differences when comparing bitmaps. The parameter specifies an acceptable color difference under which two pixels of a certain color should be treated as identical. The color difference is represented as an integer value in 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 differences between intensities of each of their color components do not exceed the specified value.

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

Mask

Specifies which areas of bitmaps should be compared. A mask is a 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 the comparison, whereas black pixels are ignored.

When you add the operation to your test, TestComplete displays the Checkpoint wizard that helps you set up the operation. For more information about using the wizard, see Checkpoint Wizard.

After adding the operation to your keyword test, you can invoke the Operation Parameters dialog. In this dialog, you can specify the parameters by using various value types and modes (Constant, Code Expression, Last Operation Result and so on). For more information on working with the dialog and assigning parameter values in it, see Specifying Operation Parameters.

To invoke this dialog:

Double-click the operation in the Keyword Test editor.

-- or --

Select the operation in the Keyword Test editor.
Click the Value cell twice (not a double-click), or select the Value cell and press F2. This will activate the in-place editor.
Click the ellipsis button in the in-place editor.

After you specified the desired values in the Operation Parameters dialog, click OK to close the dialog and to apply the changes. To save the changes, press Enter within the in-place editor. Pressing Esc will close the editor and discard any changes.

Remarks

By default, if the Region Checkpoint operation cannot find or access the image it verifies, it waits for the image for a period that the Playback > Auto-wait timeout property of your project specifies. If the image has not been found by the end of the period, the operation fails.

If the operation compares the stored image with a Window, Onscreen or RegionInfo object, TestComplete waits for an image to match for the delay specified by the Auto-wait timeout setting. That is, the test engine captures an image of the object and performs a comparison until the verification passes or until the timeout elapses. This allows you to synchronize the test with the application without using hard-coded delays. For example, you can wait for an animation to get completed or the object's appearance to change.

The image the Picture object contains is not updated during comparison. Therefore, if the operation compares a stored image with the Picture object, the test engine performs image comparison only once and returns the result immediately.

For information on region checkpoints and comparison of images, see topics of the About Region Checkpoints section.

Region Checkpoint Operation