Description

The behavior of the Compare method depends on whether the update feature is enabled.

The Regions.Compare method performs a pixel-by-pixel comparison of the two specified images. If the images are identical, the method returns True and posts an informative message to the test log. Otherwise, it returns False and logs the appropriate message along with both images.

If neither image is found, Compare returns False and generates an error string, which you can retrieve using the Regions.LastError property.

To learn more about image comparison, read the How Image Comparison Works topic.

The Compare method also lets you update images stored in the project’s Stores | Regions collection. TestComplete does this if the update feature is enabled, that is if both the global Update regions option and the stored image’s Update option are checked. Also, one of the Compare method parameters should be the image stored in the Stores | Regions collection; another parameter should be the image that will replace the stored image. In this case, Regions.Compare will replace the stored image with the specified one, post a message reporting that the image was updated to the log and return True.

Note: The order in which you specify the files does not matter; just keep in mind that only one file should be the Stores element. In any other cases, the Compare method will perform a comparison of the specified files.

Declaration

Regions.Compare(Picture1, Picture2, Transparent, Mouse, ReportDifference, PixelTolerance, MessageType)

Picture1	[in]	Required	Variant
Picture2	[in]	Required	Variant
Transparent	[in]	Optional	Boolean	Default value: False
Mouse	[in]	Optional	Boolean	Default value: False
ReportDifference	[in]	Optional	Boolean	Default value: True
PixelTolerance	[in]	Optional	Integer	Default value: 0
MessageType	[in]	Optional	Variant	Default value: lmWarning
Result	Boolean

Applies To

The method is applied to the following object:

Regions

Parameters

The method has the following parameters:

Picture1 and Picture2

Specify the images to be compared. Each of these parameters can be one of the following values:

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

-- or --

Specify the stored image and the image it will be replaced with. Only one of these parameters can be the name of the stored image; another should be either the Picture, Window, onscreen or RegionInfo object. The other method parameters are ignored.

Transparent

False by default. If it is True, then the top left pixel of the Picture1 image will be treated as the “transparent” (background) color in this image. Therefore, any transparent pixels in the first image will be excluded when being compared to the second image. All pixels with 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. will return True only if the other image also contains the mouse pointer image in the same position.

ReportDifference

After the comparison is over, TestComplete posts two images to the test log: the expected and the actual one. You can also obtain the difference between these images. For this purpose, activate the comparison mode by clicking the View Comparison Result button in the Actual Image section of the Picture panel.

Once the comparison mode is activated, the Actual Image picture shows the difference between the images. The following color highlighting is used:

Identical pixels are filled with white color, lightened or darkened according to the selected comparison mode.
The pixels that differ from one image to another are highlighted with red.
The excess areas (when the images have different height or width) are highlighted with fuchsia.
Dissimilar pixels that were skipped due to the PixelTolerance parameter are highlighted with blue.
The pixels that were skipped due to the Transparent parameters are filled with grey color.

If ReportDifference is True (this is the default value), the difference image contains all the colors described above. In other words, all the parameters (including PixelTolerance and Transparent) are considered. If ReportDifference is False, the difference image contains white, red and fuchsia pixels only. This means that PixelTolerance and Transparent parameters are not considered in this case.

PixelTolerance

Lets you ignore slight differences between the images during the search. 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.

MessageType

The type of message to be posted to the test log in case the comparison fails. Possible values:

Constant	Value	Description
`lmNone`	`0`	Do not post any message.
`lmMessage`	`1`	Post an informative message.
`lmWarning`	`2`	Post a warning message.
`lmError`	`3`	Post an error message.

Result Value

True if the compared images are identical and False otherwise.

Also True if Compare has updated the stored image.

Remarks

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 saves an image of the application’s MainForm object to the Regions collection and then compares the stored image to the active window:

JavaScript, JScript

function Test()
{


  var w1 = Sys.Process("MyApp").Window("MyWndClass", "MyWndCaption", 1);
  Regions.AddPicture(w1, "MyAppWnd");

  var w2 = Sys.Desktop.ActiveWindow();

  if (! Regions.Compare("MyAppWnd", w2))
    Log.Error("The compared regions are not identical.", w2.Name);

}

Python

def Test():
  w1 = Sys.Process("MyApp").Window("MyWndClass", "MyWndCaption", 1)
  Regions.AddPicture(w1, "MyAppWnd")
  w2 = Sys.Desktop.ActiveWindow()
  if not Regions.Compare("MyAppWnd", w2):
    Log.Error("The compared regions are not identical.", w2.Name)

VBScript

Sub Test

  Set w1 = Sys.Process("MyApp").Window("MyWndClass", "MyWndCaption", 1)
  Call Regions.AddPicture(w1, "MyAppWnd")

  Set w2 = Sys.Desktop.ActiveWindow

  If Not Regions.Compare("MyAppWnd", w2) Then
    Log.Error "The compared regions are not identical.", w2.Name
  End If

End Sub

DelphiScript

procedure Test;
var
  w1, w2 : OleVariant;
begin

  w1 := Sys.Process('MyApp').Window('MyWndClass', 'MyWndCaption', 1);
  Regions.AddPicture(w1, 'MyAppWnd');


  w2 := Sys.Desktop.ActiveWindow;

  if not Regions.Compare('MyAppWnd', w2) then
    Log.Error('The compared regions are not identical.', w2.Name);

end;