Join Wintertainment 2021 to share your stories, have fun, earn community badges, and more!

Self-Healing Tests

Applies to TestComplete 15.10, last modified on December 07, 2021

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.

Video Tutorial


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

Before the self-healing mode was introduced, if the test engine failed to find an object, it would post an error message to the test log and could stop the test run (depending on the project’s Stop on error settings). Therefore, you had to fix recognition settings and re-run failed and unexecuted tests. This might be inconvenient if you run many tests.

That is why the self-healing mode exists. When the mode is active and 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.

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


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

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

    You can enable the add-on during the TestComplete installation. If you did not enable the add-on during the installation, you can do this at any moment later via the File > Install Extensions dialog.

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

    If you experience issues with self-healing tests support in your tests, select File > Install Extensions from the TestComplete main menu and make sure these plugins are enabled (you can find them in the Intelligent Quality group). If any of the plugins is disabled, enable it.

  • Your computer must have access to the web service.

    If you have firewalls or proxies running in your network, they should allow your computer to access the web service. This web service is used to search for a replacement object by the text contents of the missing control image.

  • Your firewall must allow traffic through port 443.

  • The Enable Self-Healing mode option must be enabled in TestComplete (see below).

  • Your test must use mapped objects.

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

Enable and disable self-healing mode

  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.

  • For objects that have their image stored in the Name Mapping repository. If your Name Mapping repository does not store the images of mapped objects, tests that use those mapped objects will not be self-healed. However, if any replacement object is found by Intelligent Fix, it will be posted to the test log. See Handling the 'Object Does Not Exist' Error.

Self-healing is not applicable to web objects mapped by using XPath expressions and CSS selectors. You can update the recognition criteria for such objects manually by editing them in the Name Mapping editor or by pointing out web objects on the screen.

See Also

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

Highlight search results