Name Mapping - Selectors

Applies to TestComplete 15.64, last modified on May 16, 2024

The Name Mapping repository stores all your tested objects with their custom name and with their identification criteria. TestComplete uses the criteria to locate the objects in your tested application before simulating user actions over the objects. TestComplete stores the criteria in the Name Mapping repository automatically when you record tests or when you add objects to the repository manually.

About selectors

To locate elements in web applications and objects in mobile applications running in device clouds, TestComplete uses search expressions called selectors.

For web applications, a selector can be an XPath expression or a CSS selector. You can view the selector type in the appropriate column in the Name Mapping editor.

For mobile applications, it can be an object identifier, a class name, or an XPath expression.

For each selector, TestComplete shows a brief description that explains how the selector works and for which object it searches.

When locating the object, TestComplete will go through the specified selectors one after another in the order the Name Mapping editor lists them until it finds an object that matches the selector or until there are no more selectors left.

Web (Cross-Platform)

A web object recognized by its XPath expression and CSS selectors

Click the image to enlarge it.


An object in a mobile application recognized by its identifier and XPath expression

Click the image to enlarge it.


For web applications

Starting from version 14.50, TestComplete locates web elements by selectors in all new projects by default.

You can control this:

For mobile applications

In mobile applications running in device clouds, TestComplete always locates objects by using selectors.

Edit mapping criteria

To add a new selector

By default, when an object is mapped, TestComplete adds all possible selectors that can be used to locate the object to the repository automatically. To add a selector manually:

  1. Select a mapped web object whose identification criteria you want to modify (you can select the object in the Mapped Objects tree or in the Aliases tree).

  2. To the right of the selector list, click Add.

  3. For web objects, in the drop-down list, select the selector type: an XPath expression or a CSS selector.

  4. Enter an expression to use to locate the mapped object.

    TestComplete will validate the expression. The Annotation section in the lower part of the editor will show a brief description of the selector. If the specified expression is not valid, the Annotation section will show a notification about it.

  5. If needed, change the selector priority by using the Move Up and Move Down buttons.

To modify a selector

Click the selector in the list of mapping criteria and type the new search expression. If needed, change the selector type.

To use variables in selectors

Replace the entire selector expression or a part of it with the name of the project variable that stores the needed value. Use the following syntax:

For variables of a simple type (string, integer, double, boolean)

Enclose the variable name in %. For example, //input[@id='%myvar%'].

For DB table variables

Enclose the variable name in % and specify the name of the column from which the needed data will be extracted. For example, //input[@id='%myvar(Column1)%'].

If the test includes a single iteration, the variable will get the data from the first row of the specified column. If the test includes several iterations (a data-driven test), the variable will get the data from the specified column one row after another.

If you specify the variable that does not exist in your project, your test will report an error.

TestComplete caches mapped objects. If the variable value is updated during the test run, TestComplete may not update the mapped object’s criteria, and your test will continue using the cached object. To avoid possible issues, add the RefreshMappingInfo method to your test to command TestComplete to clear the cache and search for the object with the updated mapping criteria.

To disable a selector

To temporarily exclude a selector from the list of mapping criteria, clear the check box next to the selector.

To change the selector priority

When trying to locate a tested web object, the test engine checks the selectors in the order they are listed by the editor.

Select the selector whose priority you want to change and click Move Up or Move Down respectively.

To delete an expression

Select a selector in the list and click Remove.

Update mapping criteria (for web objects only)

If a tested web object in the application has been modified, to keep the identification criteria valid, you can update them to match the actual state of the object:

Automatically, by using Intelligent Fix

When applicable
  • An active license for the TestComplete Intelligent Quality add-on.

  • The Intelligent Quality add-on must be enabled in TestComplete.

  • Optical Character Recognition support and Self-Healing Tests support must be enabled in TestComplete.

  • Your computer must have access to the web service and Your firewall must allow traffic through port 443..

  • The Name Mapping repository must store images of mapped objects.

How automatic updates are applied

During the test run, if TestComplete fails to find a tested object, it will try to resolve the issue automatically by finding a similar object.

Depending on the Enable Self-Healing mode option, TestComplete will either use the found object to proceed the test run or report the “The Object Does Not Exist” error. In any case, after the test run is over, it will suggest that you update the object’s recognition criteria to match the found object:

Updating Name Mapping by using Intelligent Fix

Click the image to enlarge it.

In the test log, examine the suggested recognition criteria changes. If needed, examine the image of the found object to make sure that it is the right one.

Apply the suggested changes.

Manually, by pointing out the object on the screen

  1. Before you start, make sure that you have one of the supported web browsers running, and a web page that contains the target web object is open in it.

  2. In the Name Mapping repository, select a mapped web object whose identification criteria you want to update.

  3. Click Update selectors on the repository toolbar.

  4. In the resulting Update Selectors from Object dialog, select one of the tools and use them to point to the target object on the screen.

  5. Click OK.

TestComplete will replace the existing identification criteria with the new ones to match the object you have pointed to on the screen.

See Also

Name Mapping
Name Mapping - Basic Mapping Criteria
Name Mapping - Conditional Mapping Criteria
About Cross-Platform Web Tests
About Mobile Tests

Highlight search results