Naming Controls and Objects

In terms of the operating system, controls that are displayed on an application’s forms are also windows. So, the way in which TestComplete names controls is very similar to the way, in which it names windows. These names depend on whether the control is mapped or not (see Name Mapping). If it is mapped, then TestComplete uses the mapped name or alias to address this control. Otherwise, it uses the control’s ordinary (unmapped) name.

If the Map object names automatically setting is enabled in the Name Mapping Options dialog (by default, this setting is enabled), TestComplete automatically maps window names during test recording or at design time, when you add operations to keyword tests or when you create checkpoints. After the object name is mapped, TestComplete uses the mapped name to address this object in keyword tests and scripts. The ordinary (unmapped) name can also be used, though.

For more information on mapping object names, see Name Mapping. The rest of this topic will describe the principles that TestComplete uses to recognize controls and to form ordinary names.

Like window names, names of controls depend on whether the application under test is an Open Application (white-box) or non-Open Application (ordinary, black-box).

Open Applications

If the tested application is an Open Application, you can address controls and objects using special methods provided by TestComplete. The method names depend on the development tool and libraries that were used to create the application: WinFormsObject for .NET applications, VBObject for Visual Basic applications, VCLObject for Delphi and C++Builder controls, SwingObject for Java applications created with the Swing library, and so on. These methods let you address the desired window by using the value specified by the application’s Name property, or by using the class name, caption, and index. For complete information on using these methods, see the following topic:

Addressing Objects of Open Applications

Black-Box Applications

Since controls are windows, all the principles that are used to name windows are also applied to controls. To recognize them, TestComplete uses attributes of window objects: the class name, caption, and index. Like window names, the control names consist of the word Window followed by recognition attributes in parentheses:

To specify the class names and captions, you can use wildcards (* and ?). This feature lets you specify the names that are resistant to changes that occur during the application run or between the runs. This functionality is the same as the one used to address windows. For more information, see Naming Windows.

The image above displays the general format of the control's name. The format that will be used in keyword tests and scripts depends on the scripting language used in the project. The following sample demonstrates how to address controls in scripts:

processObj = Sys.Process("MyApp")
# Obtains a top-level window
windowObj = processObj.Window("WndClass", "WndCaption", 1)
# Obtains a control on the top-level window
windowObj2 = windowObj.Window("ControlWndClass", "ControlText", 1)

The methods we use in the above example address the controls using the standard recognition attributes: the class name, caption, and index. But, you can also use other properties or a combination of properties to obtain a reference to a control, for instance, you can use the control's identifiers. The control identifier is an application-defined integer value associated with a control (window). It can be retrieved with the GetWindowLong(hwndCtrl, GWL_ID) or GetDlgCtrlID(hwndCtrl) Windows API functions.

The control identifier can be specified by a developer (for example, this is typically done for dialogs designed in Visual Studio) or by the development tool itself (for instance, if the development tool does not support manual setting of the identifier). If the application under test uses the control’s identifiers, you can use them to obtain the desired control.

In TestComplete, the control identifier is returned by the ControlId property of the window object that corresponds to the desired control. To obtain a control by its control identifier, call the FindChild method of the window object, to which the control belongs. This method obtains a child object by one or a combination of property values. For example, the following sample demonstrates how you can obtain a control by using the ControlId property. For a code sample that searches using a combination of properties, see the method description :

p = Sys.Process("Notepad")
w1 = p.Window("Notepad", "Untitled - Notepad", 1) 
w2 = w1.FindChild("ControlId", 15, 1); # Obtains a child window by ControlId

To call the FindChild method in a keyword test, you can use the Call Object Method or Run Code Snippet operation.

A possible alternative to obtain an object by its property values in keyword tests is to use the Find Object operation.

Though the identifier seems to be a persistent window attribute, it may be unspecified (0), its value may change from one application run to another or the program may return the same identifier for two different controls. If you do not find the identifier helpful, you can use the window caption, class name, and index to find the desired window.

The hierarchy of windows depends on the Object tree model option of your TestComplete project. For complete information about the supported tree models, see Object Tree Models. We recommend reading this topic since knowing the tree model is essential for running tests. Tests created for the Flat model will run incorrectly if the Tree model is active and vice versa.

To obtain a control by custom property values, you can also use the Name Mapping feature (we mentioned it at the beginning of the topic). Name mapping lets you visually specify the combination and values of the properties that will be used for recognition and to assign custom names to objects that will match the specified recognition condition. Once you map an object, you can address this object in tests using the mapped name, rather than the object’s default name. For more information, see Name Mapping.

See Also

Object Browser Naming Notation
About Object Browser Naming Notation
Naming Windows
Window Object
Name Mapping