Name Mapping

Applies to TestComplete 15.62, last modified on March 14, 2024

What is the Name Mapping repository?

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

Mapped objects of a desktop application

Click the image to enlarge it.

Web (Cross-Platform)

Mapped objects of a web application (cross-platform web testing mode)

Click the image to enlarge it.

Web (Classic)

Mapped objects of a web application

Click the image to enlarge it.

Mobile

Mapped objects of a mobile application

Click the image to enlarge it.

Mobile (Legacy)

Mapped objects of a mobile application

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.

Why use name mapping

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.

How name mapping works

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.

Adding objects to the Name Mapping repository

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.

Object identification criteria

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.

Aliases and mapped objects

The Name Mapping repository includes two trees:

Mapped Objects and Aliases 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:

    Mapped name in the Name Mapping repository

    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.

    Alias in the Name Mapping repository

    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

    Accessing objects by their aliases from keyword tests

    Click the image to enlarge it.

    Accessing objects by their aliases from script tests

    Accessing objects by their aliases from keyword 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.

    Excluding intermediary levels from the Aliases tree

    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.

How TestComplete searches for mapped objects

Click the image to enlarge it.

Notes
  • The object hierarchy in the Aliases tree and in the Mapped Objects tree must not contradict the parent-child relationships of the corresponding objects in the application.

  • Unlike aliases, mapped objects cannot be moved to the topmost hierarchy level. The topmost mapped objects can be Sys or Mobile.

  • You can refer to objects in tests by their names both in the Aliases tree and in the Mapped Object tree. In the latter case, precede the object name with NameMapping.Sys or NameMapping.Mobile rather than with the Aliases prefix.

  • If an object does not have an alias, TestComplete will address it by its name in the Mapped Objects tree. If an object has several aliases, TestComplete will use the first alias with the shortest mapped name it finds.

Keeping the Name Mapping repository up to date

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.

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 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.

Related Topics of Interest

Adding and Removing Project Items and Their Child Elements

Explains how you can add the NameMapping project item to your project. This is done in the same way you add any other project item.

Mapping Web Elements With Extended Find Enabled

Explains the structure of the Name Mapping repository generated for web applications.

Object Browser Naming Notation

Describes the naming syntax for objects that are not in the Name Mapping repository.

See Also

Object Identification
Aliases Object

Highlight search results