Applies to TestComplete 14.30, last modified on November 21, 2019

Automated tests may not always run as they are expected to. They can fail because of changes in the tested application or test environments. The most common issue one may face when running automated tests occurs when TestComplete cannot find an object in a tested application to simulate user actions over it.

How TestComplete finds tested objects

To simulate user actions on a window or control, TestComplete first finds this window or control in the system. To find this object, TestComplete uses recognition criteria (a combination of property-value pairs) that uniquely identify that object. TestComplete stores these identification criteria in the Name Mapping repository for each object that your tests use:

Self-healing tests in TestComplete: Identification criteria stored in the Name Mapping repository

Click the image to enlarge it.

If a tested application changes, the object’s recognition properties (like ID or caption) can also change. This makes identification properties in the Name Mapping repo obsolete, so TestComplete will be unable to find the object in the system.

About self-healing run mode

By default, if TestComplete fails to find an object, it posts an error message to the log and can stop the test run (this depends on your project’s Stop on error settings). So, you will have to fix the recognition settings and re-run failed and unexecuted tests. This might be inconvenient if you run lots of tests. To run tests smoothly, you can enable the self-healing run mode. When this mode is active, and if the test engine fails to find an object, it tries to find a similar object in the system:

  1. It will check all the objects on the same level of the hierarchy where the missing object resides. If the Extended Find is enabled, it will also check all the objects down the hierarchy levels.

  2. It will check whether the mapping criteria of the missing object have been changed. TestComplete will search for similar objects among objects of the same class and type as the missing one.

  3. Among all similar objects that TestComplete will find, it will select the one closest to the missing object by comparing them to the missing object’s screenshot that the Name Mapping repository stores (if any).

Note: When searching for an object, TestComplete ignores the Search for visible objects first option, that is, it doesn’t prefer visible objects over invisible ones.

If TestComplete succeeds and finds a suitable object, it will continue running the test using that similar object instead of the missing object. This way, the test will run smoothly without being interrupted by errors.

If TestComplete fails to find a suitable object (this can happen if a suitable object does not exist in the application), it will report the “The Object Does Not Exist” error and will not simulate user actions over the object. In addition, depending on the project’s Stop on error settings, it will stop the test run upon the error completely.

Update recognition settings

The test engine posts a warning message to the log for every replacement. This message contains information on the new recognition properties used:

Self-healing tests in TestComplete: Recognition criteria fixed automatically

Click the image to enlarge it.

These changes are not permanent. They are effective only during the current test run. After the test run is over, TestComplete restores the initial setting values to avoid possible confusion in case of false replacement.

To make the changes permanent, click Accept Intelligent Fix. TestComplete will update the recognition criteria in the Name Mapping repository and will use them in subsequent test runs:

Self-healing tests in TestComplete: Apply suggested changes

Click the image to enlarge it.

Of course, you can also update the recognition criteria in the Name Mapping editor manually.

We’d recommend that you not ignore the “self-healing” warnings and fix recognition settings in a timely manner. Else, further changes to the tested application might cause more severe errors in tests.

Enable and disable self-healing mode

The self-healing mode is in Beta and is disabled by default so far. To enable it:

  1. In the main menu of TestComplete, select Tools > Options.

  2. In the subsequent dialog, go to the Engines > Name Mapping options and select the Enable Self-Healing mode check box:

    Enable the self-healing mode

    Click the image to enlarge it.

    Save the changes.

To enable this mode from the command line, add the /SelfHealing parameter to the TestComplete command line.

To disable the self-healing mode, clear the “Enable Self-Healing mode” check box in the Tools > Options > Engines > NameMapping dialog.

When self-healing is not possible

Self-healing is applicable only for tests that use Name Mapping to locate tested objects in the application. If your test uses an object’s full name or various Find methods to locate the object, such a test cannot be self-healed. You will have to fix it manually.

See Also

Running Tests
Message - Object 'Object_Name' was replaced with a similar object
Handling the 'Object Does Not Exist' Error

Highlight search results