Fine-tuning the bitmap comparison

Relevant for: GUI tests and components

When running a bitmap checkpoint, UFT compares the area that you are checking in the application with the bitmap stored in the checkpoint, pixel by pixel. By default, if any pixels are different, the checkpoint fails. The advanced settings in the Bitmap Checkpoint Properties dialog box provides various options for fine-tuning the bitmap comparison:

RGB Tolerance

NOTE: This functionality is available only when comparing expected bitmaps with runtime bitmaps. It is not available when locating a specified bitmap within the runtime bitmap.

The RGB (Red, Green, Blue) tolerance determines the percent by which the RGB values of the pixels in the runtime bitmap can differ from those of the expected bitmap and allow the checkpoint to pass. (The RGB tolerance option is limited to bitmaps with a color depth of 24 bits.)

For example, a bitmap checkpoint on identical bitmaps could fail if different display drivers are used when you create your checkpoint and when you run your test. Suppose one display driver displays the color white as RGB (255, 255, 255) and another driver displays the color white as RGB (231, 231, 231). The difference between these two values is about 9.4%. By setting the RGB tolerance to 10%, your checkpoint will pass when running your test with either of these drivers.

UFT applies the RGB tolerance settings when comparing each pixel in the expected and runtime bitmaps. The Red, Green, and Blue values for each pixel are compared separately. If any of the values differs more than the tolerance allows, the pixel fails the comparison.

Pixel Tolerance

NOTE: This functionality is available only when comparing expected bitmaps with runtime bitmaps. It is not available when locating a specified bitmap within the runtime bitmap.

The pixel tolerance determines the number or percentage of pixels in the runtime bitmap that can differ from those in the expected bitmap and allow the checkpoint to pass.

For example, suppose the expected bitmap has 4000 pixels. If you define the pixel tolerance to be 50 and select the Pixels radio button, up to 50 pixels in the runtime bitmap can be different from those in the expected bitmap and the checkpoint passes. If you define the pixel tolerance to be 5 and select the Percent radio button, up to 200 pixels (5 percent of 4000) in the runtime bitmap can be different from those in the expected bitmap and the checkpoint passes.

Image Similarity

NOTE: This functionality is available only when locating a specified bitmap within the runtime bitmap. It is not available when comparing expected bitmaps with runtime bitmaps.

Image similarity settings can enable a checkpoint to pass, even if the exact bitmap is not found in your application. UFT attempts to locate the specified bitmap in the runtime bitmap of the object in your application during the run session. If UFT locates an exact match to the specified bitmap, then the checkpoint passes.

If an exact match cannot be found and you specified less than 100% in the Similarity option in the advanced settings of the Checkpoint Properties Dialog Box, UFT adjusts the comparison according to the similarity level. If the possible candidate has a similarity that is equal to or greater than the percentage that you defined, the checkpoint passes.

Custom Comparers

A custom comparer is a COM object that you or a third party can develop to run the bitmap comparison in the checkpoint according to a more specific algorithm. If you use a custom comparer to perform the bitmap checkpoint, UFT sends the comparer two bitmaps to compare: A screen capture of the object, created with the checkpoint and saved as the expected bitmap, and a screen capture of the object as it appears in the application during the run session. The comparer then compares these two bitmaps according to the specifications in its algorithm. If you use a custom comparer, you cannot use the Checkpoint Properties Dialog Box to specify tolerance or similarity settings, or areas of the object to compare or ignore.

If one or more custom comparers are installed and registered on the UFT computer, the Advanced Settings Dialog Box (Bitmap Checkpoints Dialog Box) includes a Comparer option.

The Comparer option enables you to select the UFT default comparer or a custom comparer that performs the bitmap comparison according to your testing requirements. For an example of when it can be useful to create a custom comparer, see Custom comparer for images whose location changes - Use-case scenario. For details on developing or installing custom comparers, see Developing Custom Comparers for Bitmap Checkpoints.

If you select a custom comparer, some of the options in the Bitmap Checkpoint Properties Advanced Settings dialog box are different.

If you define both RGB and pixel tolerances, the RGB tolerance is calculated first. The pixel tolerance then defines the maximum number of pixels that can fail the RGB criteria and allow the checkpoint to pass.

For example, suppose you define an RGB tolerance of 10 percent and a pixel tolerance of 5 percent, for a bitmap that has 4000 pixels. For the checkpoint to pass, each pixel in the runtime bitmap must have RGB values that are no greater than or no less than 10 percent of the RGB values of the expected bitmap. If that criterion fails, UFT checks that the number of pixels that failed are less than 200. If that criterion passes, the checkpoint passes.