Applies to TestComplete 12.50, last modified on April 10, 2018

Each test project has the Name Mapping repository (the NameMapping project item). It contains all  the objects of your application that are used in your automated tests. TestComplete automatically adds objects to the Name Mapping repository when you are recording a test and uses the information stored in the repository to identify the objects during test runs.

What Is the Name Mapping Repository?

The Name Mapping repository contains properties and values used to uniquely identify objects during the test run. For example, web page URLs, object types (buttons, text boxes, grids, and so on), object names in the application, object text, and so on. Each object in the Name Mapping repository has a descriptive name (alias) used in tests and its image, so you can easily understand which object has been mapped.

Since the Name Mapping repository stores object identification information separately from the tests, there is no need to change the tests if your tested application has changed. This makes test maintenance easier.

All the objects stored in the Name Mapping repository are organized into a hierarchy, which reflects how the objects relate to each other inside the application. The hierarchy helps TestComplete find the objects faster and more accurately, because it shows in which exactly part of the application an object is located.

Desktop

Sample name map for a desktop application

Click the image to enlarge it.

Web

Sample name map for a web application

Click the image to enlarge it.

Mobile

Sample name map for a mobile application

Each project can have only one Name Mapping repository. To add Name Mapping data from another test project, you can merge the external Name Mapping repository into the local one.

How Name Mapping Works

TestComplete automatically adds objects to the Name Mapping repository when you are recording a test, but you can also add objects manually. For each mapped object, TestComplete selects the properties and values that uniquely describe this object in the application. TestComplete also generates aliases for all the mapped objects and uses these aliases in tests. TestComplete also stores images of mapped objects to the Name Mapping repository.

When you are recording a new test, TestComplete compares the recorded objects with the information stored in the Name Mapping repository and maps only those objects that are not in the Name Mapping repository.

When you run tests, TestComplete uses the information from the Name Mapping repository to find objects in your tested application. If TestComplete cannot find an object (for example, if the object properties have changed, or there are several objects with these property values), the test fails. In this case, you need to update the mapping criteria to use unique, unchangeable properties for object identification.

Adding Objects to the Name Mapping Repository

TestComplete automatically adds objects to the Name Mapping repository when you are recording and editing tests if the Map object names automatically option is enabled. You can also add objects to the Name Mapping repository manually from screen or from the Object Browser. For more information, see Adding Objects to the Name Mapping Repository.

Tip: To add all the objects of your tested application to the Name Mapping repository, you can record a dummy test that clicks all the objects.

Object Identification Criteria

Usually, TestComplete finds objects by their property values, but you can also use other conditions such as nested search or child objects. The supported conditions are:

  • One or more property-value pairs. For example, ObjectType=Page, URL=http://example.com.

    Tip: You can specify identification property values using wildcard patterns and project variables.
  • Conditional expressions with object properties. You can use them to specify multiple possible values for a property (for example, WndCaption = Open OR Select File), or use conditions other than equality (does not equal, greater than, and so on).

  • Extended search (useful for dynamic applications). It lets you search for an object on all the levels down the object hierarchy rather than just on the current level.

  • Required child objects. This condition matches an object only if it has specific child objects.

TestComplete tries to choose the best identification properties when adding objects to the Name Mapping repository. To customize the default identification properties used for different object types, you can create name mapping templates. When mapping objects manually (for example, from the Object Browser), you can also select the identification properties yourself.

If you are testing a multi-language application, you can create multiple configurations of the Name Mapping repository with language-specific values of the identification properties. You can switch configurations at design time in the Name Mapping editor and from tests. For more information, see Name Mapping Configurations.

Object Names

Each object in the Name Mapping repository has an alias – a user-defined name, for example, ButtonAdd, linkProducts, and so on. You use these aliases in automated tests to refer to objects.

Scripted tests use full aliases, which include full hierarchy path of the selected object. For example, Aliases.Orders.MainForm.OrdersView instead of just OrdersView. If you use keyword tests, you do not actually see this full notation, because TestComplete displays a shortened notation for easy viewing.

About the Mapped Objects and Aliases Trees

The Name Mapping repository shows the object hierarchy as a tree. In fact, there are two trees - Mapped Objects (upper) and Aliases (lower). The Mapped Objects tree is hidden from the default view, but it can be displayed using the down arrow button in the tree caption. Usually, both trees have the same object structure, but in some cases, they may slightly differ.

You can click an object in either of the trees to view its image in the lowermost panel of the editor.

Mapped Objects and Aliases trees
The Mapped Objects and Aliases Trees

The Mapped Objects tree matches the object hierarchy displayed in the Object Browser, including the top-level objects Sys and Mobile. TestComplete needs to know the exact hierarchy to find the needed object. Some object identification options, such as Extended Find, are configured only in the Mapped Objects tree.

The Aliases tree can have a shorter hierarchy. You can exclude intermediary objects to shorten full aliases. You can rearrange the Aliases hierarchy by dragging the objects up the tree (provided that you preserve the parent-child relationship). The object’s full alias includes the names of only those objects that are in the Aliases tree. If an object is present in the Mapped Objects tree and is skipped in the Aliases tree, TestComplete will use the object's search criteria, but will not use the object's name in full aliases.

Notes:

  • An object can have different names in the Aliases and Mapped Objects trees. In this case, only the name from the Aliases tree is used in tests.

  • If an object is in the Mapped Object tree but not in the Aliases tree, its full name starts with the NameMapping.Sys or NameMapping.Mobile prefix rather than with the Aliases prefix.

  • The hierarchy of mapped objects and aliases must not contradict the parent-child relationships of the corresponding objects in the application.

Working With Objects That Are Not in the Name Mapping Repository

Automated tests can also work with objects that are not in the Name Mapping repository. To refer to such objects, you can use the syntax used in the Object Browser. This syntax includes the object type (Process, WinFormsObject, Device and so on) and the values of standard identification properties for this object type. For example:

JavaScript, JScript

Sys.Process("notepad").Window("Notepad", "Untitled - Notepad").Maximize();

Python

Sys.Process("notepad").Window("Notepad", "Untitled - Notepad").Maximize()

VBScript

Sys.Process("notepad").Window("Notepad", "Untitled - Notepad").Maximize

DelphiScript

Sys.Process('notepad').Window('Notepad', 'Untitled - Notepad').Maximize;

C++Script, C#Script

Sys["Process"]("notepad")["Window"]("Notepad", "Untitled - Notepad")["Maximize"]();

For more information about this syntax, see Default Naming.

This syntax also lets you search for objects using arbitrary properties:

Desktop

JavaScript, JScript

Sys.Process("notepad").FindChild("WndClass", "Edit", 1).Keys("Hello");

Python

Sys.Process("notepad").FindChild("WndClass", "Edit", 1).Keys("Hello")

VBScript

Sys.Process("notepad").FindChild("WndClass", "Edit", 1).Keys("Hello")

DelphiScript

Sys.Process('notepad').FindChild('WndClass', 'Edit', 1).Keys('Hello');

C++Script, C#Script

Sys["Process"]("notepad")["FindChild"]("WndClass", "Edit", 1)["Keys"]("Hello");

Web

JavaScript, JScript

Sys.Browser().Page("http://www.example.com").FindChildByXPath("//INPUT[@type='button']").Click();

Python

page = Sys.Browser().Page("http://www.example.com").FindChildByXPath("//INPUT[@type='button']").Click()

VBScript

Sys.Browser.Page("http://www.example.com").FindChildByXPath("//INPUT[@type='button']").Click

DelphiScript

Sys.Browser.Page('http://www.example.com').FindChildByXPath('//INPUT[@type="button"]').Click();

C++Script, C#Script

Sys["Browser"]()["Page"]("http://www.example.com")["FindChildByXPath"]("//INPUT[@type='button']")["Click"]();

Mobile

JavaScript, JScript

Mobile.Device().Process("smartbear.example.orders").FindChild("ViewID", "newButton", 3).Touch();

Python

Mobile.Device().Process("smartbear.example.orders").FindChild("ViewID", "newButton", 3).Touch()

VBScript

Mobile.Device.Process("smartbear.example.orders").FindChild("ViewID", "newButton", 3).Touch

DelphiScript

Mobile.Device.Process('smartbear.example.orders').FindChild('ViewID', 'newButton', 3).Touch;

C++Script, C#Script

Mobile["Device"]()["Process"]("smartbear.example.orders")["FindChild"]("ViewID", "newButton", 3)["Touch"]();

For more information about the search methods, see:

Searching for an Object

Common Tasks for Web Testing

Note: If you do not want to use the Name Mapping repository, you can prevent TestComplete from automatically adding objects to it when you are recording and editing tests. To do this, disable the Map object names automatically option.

See Also

Name Mapping
About Name Mapping Editor

Highlight search results