Bitmap checkpoint comparer Interfaces

Relevant for: GUI tests and components

Your custom comparer must implement the interfaces described in this section. UFT One calls these interfaces' methods when creating or running a bitmap checkpoint that uses your custom comparer.

IVerifyBitmap Interface

This interface contains the CompareBitmaps method that you need to implement to perform the bitmap comparison for the checkpoint.

The CompareBitmaps method receives the actual and expected bitmaps that need to be compared for the bitmap checkpoint, and a string that can contain configuration input for the custom comparer.

The method must compare the bitmaps according to the comparison algorithm for which this custom comparer is designed, and return the results to UFT One.

The results include:

  • An indication whether the bitmaps match and the checkpoint should pass.

  • A text string that contains information about the results of the bitmap comparison.

  • A bitmap that reflects the differences between the actual and expected bitmaps.

UFT One displays the results that this method returns in the run results. For details, see the section on Use run results.

Method syntax

HRESULT CompareBitmaps ([in] IPictureDisp* pExpected, 
				[in] IPictureDisp* pActual, 
				[in] BSTR bstrConfiguration, 
				[out] BSTR* pbstrLog, 
				[out] IPictureDisp** ppDiff, 
				[out, retval] VARIANT_BOOL* pbMatch);

Method Parameters

Parameter Description
pExpected

A picture object (input).

The expected bitmap stored in the checkpoint.
pActual

A picture object (input).

The actual bitmap captured from the application being tested.

bstrConfiguration

A text string (input).

A string that contains configuration input for the custom comparer. This is the string displayed in the Input box in the advanced settings in the Bitmap Checkpoint Properties dialog box.

The string can be the default configuration string that the custom comparer provides to UFT One in the GetDefaultConfigurationString method described below, or an input string entered by the UFT One user.

The bstrConfiguration string can have any format you choose (XML, comma separated, or ini file style). Make sure that the default configuration string returned by the GetDefaultConfigurationString method matches the format expected in the CompareBitmaps method. Additionally, make sure that the documentation you provide for your custom comparer explains the format that the UFT One user must use when editing this string in the Input box.
pbstrLog

A text string (output).

A string that contains information about the results of the bitmap comparison. UFT One displays this string in the run results.
ppDiff

A picture object (output).

A bitmap (created by the custom comparer) that reflects the difference between the actual and expected bitmaps. UFT One displays this bitmap in the run results along with the actual and expected bitmaps.
pbMatch

A boolean value (output).

A value that indicates whether the bitmaps match and the checkpoint should pass.

Possible values:

  • VARIANT_TRUE. Actual and expected bitmaps match, checkpoint passes.

  • VARIANT_FALSE. Actual and expected bitmaps do not match, checkpoint fails.

Return Value

The HRESULT that this method returns indicates whether the comparison ran successfully (and not whether the bitmaps match).

Back to top

IBitmapCompareConfiguration Interface

This interface contains the methods that you need to implement to support the custom comparer options that UFT One displays in the advanced settings in the Bitmap Checkpoint Properties dialog box.

The GetDefaultConfigurationString Method

The GetDefaultConfigurationString method must return the default configuration string for your custom comparer. For details on configuration strings, see Implement the CompareBitmaps method.

UFT One displays this string in the Input box in the advanced settings in the Bitmap Checkpoint Properties dialog box when a user creating a new bitmap checkpoint selects your custom comparer.

If the UFT One user does not modify the input string in the dialog box, the string provided by GetDefaultConfigurationString is passed to the custom comparer's CompareBitmaps method. You must therefore make sure that the default configuration string matches the format that your custom comparer expects to receive in the CompareBitmaps method.

Method syntax: 

HRESULT GetDefaultConfigurationString ([out, retval] BSTR* pbstrConfiguration);

The GetHelpFilename Method

The GetHelpFilename method must return a path to the documentation that contains information about your custom comparer for UFT One users.

UFT One displays the documentation when a user selects your custom comparer in the advanced settings in the Bitmap Checkpoint Properties dialog box and clicks Details. Make sure that when your custom comparer is installed, the documentation that you provide is installed in the location specified by the GetHelpFilename method.

The path can be one of the following:

  • A full path to a file.

  • A relative path to a file (UFT One searches for this path relative to <UFT One installation folder>\bin).

  • A URL.

If you do not provide documentation for your custom comparer, this method should return the HRESULT E_NOTIMPL. For details on the type of information you should provide, see Implement IBitmapCompareConfiguration.

Method syntax: 

HRESULT GetHelpFilename ([out, retval] BSTR* pbstrFilename);

Back to top