Microsoft KB Archive/88379

= Microsoft Knowledge Base =

INF: Using TestDlgs Correctly
Last reviewed: October 19, 1994

Article ID: Q88379

This information applies to:

- Microsoft Test for Windows, versions 1.0 and 2.0

SUMMARY
This article provides information on how TestDlgs works, describes some of its processes, and defines some of the options and terminology used by the TestDlgs utility and TESTDLGS.DLL.

MORE INFORMATION
TestDlgs is a set of routines that uses the internal Windows structure for windows, dialog boxes, controls, and menus to perform comparisons of objects. Because these routines deal with the internal structure of an object rather than its visual image, they are capable of making a &quot;fuzzy&quot; match--recognition that the two objects are equal, even though their visual representation may appear different. (For example, a dialog box location that changes due to machine differences in screen resolution.)

Three different results to the compare operation are possible:

  Exact match: All criteria between the BASE image and COMPARE image match exactly.   Fuzzy match: Most criteria between the BASE image and COMPARE image match, namely the text, class name, and state.   No match: Text, class name, or state differed between the BASE image and COMPARE image. 

For more information on TestDlgs functionality, see the &quot;Microsoft Test User's Guide&quot; manual.

Term Definitions
BASE image (or &quot;base line&quot; image): A set of selected windows,

controls, or menus (or their                                  children,) captured to a dialog file for later comparison against a                                  COMPARE image.

COMPARE image:            A set of selected windows, controls, and menus (and/or their                                  children,) captured from a running application that is compared against a previously saved BASE image.

Option Definitions
  Full Dialog option: Found in the New Dialog dialog box under the Dialog menu option.

If the Full Dialog option is selected, the type and number of  controls in the COMPARE image must exactly match those of the BASE image for a successful comparison.

If the &quot;Full Dialog&quot; option is not selected, TestDlgs performs a  partial compare. A partial compare means that the COMPARE image may have controls and/or dialogs that are not included in the BASE image and still return a successful compare, as long as everything in the BASE image is represented in the COMPARE image.   Grab mode: Found in the &quot;New Dialog&quot; dialog box under the Dialog menu option.

Grab mode has three options: Individual control, All children of  window, and Menus.

- Individual control: Only a selected window or control is added to the BASE image; no children (if any) of                         the selected window/control are included in                          the BASE image. With this grab mode, multiple windows/controls can be added to                         the BASE image one at a time.

- All children of window: Creates a new BASE image (any existing                             information in the BASE image will be                              lost) that includes only information about the children of a selected window or control. Information about the window or control itself is not included in the BASE image.

- Menus:       Creates a new BASE image (any existing                          information in the BASE image will be lost) containing all the menus of the selected window or control (including the system                         menu, if one exists.)   INCLUDE PARENT IN COMPARISON Option: Found in the &quot;Compare Dialogs&quot; dialog box under the Dialog menu option.

- Off: Sets COMPARE image to include ONLY the children (if any) of          the selected control/dialog.

- On: Sets COMPARE image to include all children (if any) of the selected control/dialog AND the selected control/dialog itself. 

Getting the Comparison Result You Want
It is important to match the &quot;Grab mode&quot; and the &quot;Include parent in comparison&quot; options correctly to get accurate comparisons.

For example, to perform a comparison that does not include children (that is, comparing windows or controls themselves), select &quot;Individual control&quot; as the grab mode when capturing the BASE image, and select &quot;Include parent in comparison&quot; when performing the comparison.

To perform a comparison that includes only children of windows or controls, choose &quot;All children of window&quot; as the grab mode when capturing the BASE image, and do not select &quot;Include parent in comparison&quot; when performing the comparison.

To compare both parents and children at once, select &quot;All children of window&quot; and capture all the children of the desired window. Next, select &quot;Individual control&quot; grab mode and add the parent control itself to the BASE image. Finally, select the &quot;Include parent in comparison&quot; when performing the comparison.

Note: If the &quot;Grab mode&quot; for the BASE image is set to &quot;Individual control,&quot; but the &quot;Include parent&quot; option for the COMPARE image is not selected, a comparison of two identical windows or controls will not result in a match. This happens because without the &quot;Include parent&quot; option selected, only the children of the control or window are included in the COMPARE image, whereas the BASE image consists of the control itself and its children.