Description

The Region.Check method performs a pixel-by-pixel comparison of the RegionObj image against the specified image. If the images are identical, the method returns True and posts a success message to the test log. Otherwise, it returns False and logs an appropriate message along with both images.

The Region.Check method is a simplified version of the Regions.Compare method. It requires that only the image to compare with be specified (since the RegionObj instance is treated as the baseline image) and has fewer parameters.

To learn more about comparing images, see the How Image Comparison Works topic.

Declaration

RegionObj.Check(Picture, Transparent, Mouse, PixelTolerance, ColorTolerance, Mask)

RegionObj	An expression, variable or parameter that specifies a reference to a Region object
Picture	[in]	Required	Variant
Transparent	[in]	Optional	Boolean	Default value: False
Mouse	[in]	Optional	Boolean	Default value: False
PixelTolerance	[in]	Optional	Integer	Default value: 0
ColorTolerance	[in]	Optional	Integer	Default value: 0
Mask	[in]	Optional	Variant
Result	Boolean

Applies To

The method is applied to the following object:

Region

Parameters

The method has the following parameters:

Picture

Specifies the image to compare with. The parameter value can be one of the following:

The name of the Regions collection’s item (if the image is stored in this collection).
A Picture object.
A window or onscreen object.
A RegionInfo object.
The fully-qualified path to the image file. The following file types are supported:
- BMP
- JPEG
- PNG
- TIFF
- GIF
- ICO

Transparent

False by default. If it is True, the top left pixel of the baseline image (to which the Region object relates) 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 method 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 the 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. The mask is specified by an image whose pixels can be either black or white. If a mask is specified, the routine works in the following way: white pixels on the mask are taken into account during the comparison, whereas black pixels are ignored. The parameter value can be one of the following:

The name of the Regions collection’s item (if the image is stored in this collection).
A Picture object.
The fully-qualified path to the image file. The following file types are supported:
- BMP
- JPEG
- PNG
- TIFF
- GIF
- ICO

Result Value

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

If the image specified by the Picture parameter is not found, Check returns False and generates an error string which can be retrieved using the Region.LastError property.

Remarks

By default, if the Check method cannot find or access the image to be compared, or the image does not match its baseline copy, the method will wait for the image to become accessible and for the comparison to complete successfully for the period the Tools > Current Project Properties > Playback > Auto-wait timeout setting specifies. If the method fails to access the image, or if the image does not match its baseline copy within this period, the comparison will fail.

If the method compares a stored image with a Window, Onscreen or RegionInfo object, TestComplete waits for an image match for the time period specified in the Auto-wait timeout setting. That is, the test engine captures an image of the object and performs comparison until 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. If the method compares a stored image with the Picture object, the test engine performs image comparison only once and returns the results immediately.

If comparison fails while the images seem to be identical, read the Why Image Comparison Fails and Factors Affecting Image Comparison help topics to determine the cause of the failure.

Example

The following code compares two images stored in the Regions collection using the Region.Check method. To specify the images, we use their names in the collection.

JavaScript, JScript

function Test()
{
if (! Regions.Image1Name.Check("Image2Name"))
Log.Error("The compared regions are not identical.");
}

Python

def Test():
  if not Regions.Image1Name.Check("Image2Name"):
    Log.Error("The compared regions are not identical.")

VBScript

Sub Test
  If Not Regions.Image1Name.Check("Image2Name") Then
    Log.Error "The compared regions are not identical."
  End If
End Sub

DelphiScript

procedure Test;
begin
if not Regions.Image1Name.Check('Image2Name') then
Log.Error('The compared regions are not identical.');
end;