Name Mapping

The Name Mapping repository stores all the objects of your tested applications that your automated tests use. For each object, the Name Mapping repository has an alias (a descriptive name used in tests), the object’s position in the application’s object hierarchy, the criteria by which TestComplete identifies the object in the application uniquely, and (optionally) an image:

Desktop

Web (Cross-platform)

Web (Classic)

Mobile

Mobile (Legacy)

Desktop

Click the image to enlarge it.

Web (Cross-Platform)

Click the image to enlarge it.

Web (Classic)

Click the image to enlarge it.

Mobile

Click the image to enlarge it.

Mobile (Legacy)

Click the image to enlarge it.

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.

The Name Mapping repository stores object identification information separately from tests making test maintenance easier. If your application changes, you will not have to change your tests. You will only have to update the Name Mapping repository.

You can also specify user-friendly names (aliases) for your tested objects. This way your tests will be shorter and easier to read and maintain.

When recording tests, TestComplete adds objects to the Name Mapping repository automatically. You can also add objects manually at design time. For each object, TestComplete specifies criteria that describe this object in the application uniquely. When mapping objects, TestComplete compares them with the objects stored in the Name Mapping repository and maps only those objects that are not mapped.

When running tests, TestComplete uses 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.

• Automatically - By default, TestComplete adds objects to the Name Mapping repository when you are recording and editing tests. See Mapping Objects Automatically.

• Manually - You can add objects to the Name Mapping repository from screen or from the Object Browser. See Mapping Objects Manually.

Tip: The easiest way to map multiple objects quickly is to record user actions over these objects. TestComplete will map all the objects with which you have interacted automatically.

The object identification criteria that the repository stores and that TestComplete uses to search for objects in the applications can be:

• Property-value pairs. For example, ObjectType=Page, URL=http://example.com.

• Conditional expressions. For example, WndCaption = Open OR Select File.

• Selectors (for web and mobile applications) For web applications, it can be XPath expressions and CSS selectors, for example, //input[@id='instasearch'] or #instasearch. For mobile applications, it can be the object class name, accessibility identifier, or an XPath expression, for example, XCUIElementTypeStatusBar or //*[@name="Orders"].

• Extended search. Search for an object on all the levels down the object hierarchy rather than just on the current level.

• Required child objects. Search for an object that has specific child objects.

To customize the default identification properties that TestComplete uses to map objects, you can create templates.

The Name Mapping repository includes two trees:

Click the image to enlarge it.

• Mapped Objects (hidden by default) - Shows all the objects (windows, dialogs, pages, and controls) found in your tested application.

  Typically, the Mapped Object tree matches the application’s object hierarchy. However, for web and mobile applications, it can omit some intermediate levels.

  The mapped name shows the object position in the Mapped Objects tree:

  

  You can use the mapped name to address objects from tests. However, it is more convenient to use aliases for this purpose (see below).

  If your application’s object hierarchy changes, update the Mapped Objects tree to reflect the changes. See Update Name Mapping. If your tested application’s hierarchy changes dynamically, you can move an object to the first stable parent skipping all the dynamic levels and then configure TestComplete to search for the object on all the levels down the hierarchy. See Name Mapping - Extended Search.

• Aliases - Objects in the Name Mapping repository can have an alias – a user-friendly name, for example, ButtonOK or linkProducts. Aliases are used to refer to objects in tests.

  

  In script tests, you use full aliases, that is, the full hierarchy path of the object in the Aliases tree. In keyword tests, you do not actually see the full hierarchy path, because TestComplete shows a short notation for easy viewing.

  Accessing objects by their aliases from keyword tests Click the image to enlarge it.

  Accessing objects by their aliases from script tests Click the image to enlarge it.

  You can exclude intermediary objects from the Aliases tree to shorten object names. Suppose, you have an object with the fully-qualified alias Aliases.Orders.OrderForm.Group.groupBox1.Total. To exclude the intermediary Group and groupBox1 levels, you can move the Total item up the Aliases tree to the OrderForm item. In this case, to address the object from tests, you will use the object’s new alias – Aliases.Orders.OrderForm.Total.

  

  If you change the object hierarchy in the Aliases tree, the name used to address the corresponding objects in your tests must be updated as well. In keyword tests, TestComplete will suggest to update the name automatically. In scripts, you will have to update the name manually.

  By default, TestComplete generates an alias when you add an object to the Name Mapping repository (it is based on the object type) and text and/or a native name. You can change the default alias, for example, to a more descriptive name. See Rename Objects in the Name Mapping Repository.

You change the hierarchy in the Aliases and Mapped Objects trees by using drag-and-drop. To move an item to a different hierarchy level, drag it to the target location in the tree. TestComplete will move it along with all its child items.

How TestComplete searches for mapped objects

When a test tries to get an object by its alias, TestComplete does the following:

1. In the Mapped Objects tree, it finds an item that corresponds to the alias.

2. Searches for the corresponding object in your system, starting from the top-level item in the Mapped Objects tree and moving down the hierarchy to the target item. It searches for each item on the appropriate level of the application hierarchy. If Extended Find is enabled, it will also search for the item on the following hierarchy levels as well.

   To find each item, it uses its specified identification criteria.

Click the image to enlarge it.

Notes

If the object hierarchy or property values used as identification criteria have changed in the application and they differ from the ones the Name Mapping repository stores, TestComplete will not be able to find tested objects. To learn how to check whether the hierarchy and identification criteria in your Name Mapping repository are correct and how to update them, if needed, see Update Name Mapping.

Automated tests can also work with objects that are not in the Name Mapping repository. To refer to such objects, you can use various approaches. See Object Browser Naming Notation.

To prevent TestComplete from storing your tested objects in the Name Mapping repository, you can disallow TestComplete to add objects to it automatically when you are recording or editing tests. To do this, disable the Engines > Name Mapping > Map object names automatically option.