Implement the bitmap comparer Interfaces

Relevant for: GUI tests and components

This task describes how to implement the bitmap comparer interfaces so that your custom comparer COM object performs the following:

In this topic:

Prerequisite - Reference the type library

In the COM object that you develop, reference the type library that UFT One provides (located in <UFT_One_installdir>\dat\BitmapCPCustomization\BitmapComparer.tlb)

Back to top

Implement the CompareBitmaps method

UFT One calls the CompareBitmaps method in the IVerifyBitmap interface to pass the expected and actual bitmaps to the custom comparer for comparison.

Method syntax:

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

Implement the the CompareBitmaps Method method to perform the following:

• Accept and compare two bitmaps according to a predefined algorithm that you define based on the testing requirements.

• Accept a text string that can contain configuration information provided by the UFT One user (in the Bitmap Checkpoint Properties dialog box, Advanced settings), and use it in the comparison. For example, the string could contain tolerance specifications, acceptable deviations in size or location of the image, or any other information that you want to affect the comparison.

The string can have any format you choose (XML, comma separated, or INI file style). Make sure that the documentation you provide for the custom comparer describes the format. The configuration input that the UFT One user enters in the advanced settings in the advanced settings in the Bitmap Checkpoint Properties dialog box must conform to this format.

Back to top

Implement the CompareBitmaps method

UFT One displays the results of bitmap checkpoints in the run results.

When you implement the The CompareBitmaps Method method in the IVerifyBitmap interface to compare the bitmaps, you must also return the following information:

• Whether the bitmaps match and the checkpoint should pass.

• A text string that UFT One displays in the run results.

  The purpose of this string is to provide information about the comparison to the UFT One user, but while you develop and test your comparer, you can use this string for debugging purposes as well.

• A bitmap that visually represents the difference between the actual and expected bitmaps.

  The purpose of this bitmap is to help the UFT One user understand why the checkpoint failed. The custom comparer can create this bitmap using any visualization approach you choose. For example, the default UFT One comparer creates a black-and-white bitmap containing a black pixel for every pixel that is different in the two images.

Back to top

Implement IBitmapCompareConfiguration

When a UFT One user selects a custom comparer in the advanced settings of the Bitmap Checkpoint Properties dialog box, UFT One displays an input text box, and, optionally, a link to documentation provided for the custom comparer. For details, see Fine-tuning the bitmap comparison.

To support these options, you can implement the IBitmapCompareConfiguration interface to provide the necessary information for the dialog box.

• Implement the GetDefaultConfigurationString method to return the default configuration string for your custom comparer.

  Method syntax:

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

  UFT One displays this string in the Input box in the advanced settings in the Bitmap Checkpoint Properties dialog box.

  The format of this string must be the same as the format of the configuration string that the comparer expects as input.

• Implement the GetHelpFilename method to return a path to the documentation about your custom comparer. A UFT One user can then access the documentation from the advanced settings in the Bitmap Checkpoint Properties dialog box.

  Method syntax:

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

  The documentation can be in any format that you choose. UFT One opens the documentation using the program associated with the provided file type on the user's computer. Therefore, you should provide the documentation in a format for which you expect the UFT One user to have the necessary program.

  The documentation should provide the UFT One user with the following information:

  • The type of comparison the custom comparer performs (to enable the user to determine when to use it to run a bitmap checkpoint).

  • The required format for the configuration string and the possible values it can contain.

  • An explanation of the comparison result information that is displayed in the run results (text string and difference bitmap).

  Back to top