Self-healing tests in Katalon Studio

requirements

An active Katalon Studio Enterprise license

When the application under test (AUT) changes, object locators might be broken or unable to identify the target element. Hence, creating and using correct, resilient locators are crucial to the success of Web UI test automation.

Katalon Studio supports the self-healing mechanism to tackle the issue of broken locators during execution. This feature can reduce your test maintenance effort substantially, especially when test cases run in batch overnight.

This article guides you through:

• Understanding the self-healing mechanism
• Configuring and executing a test with the self-healing mode
• Viewing self-healing insights and replacing broken locators

We also offer a sample project for you to try out. You can clone or download this sample project from our GitHub repository: Self-healing sample project.

Note:

Learn more with our Katalon Academy course: Self-Healing Mechanism in Test Automation.

Self-healing mechanism

With self-healing enabled, when Katalon Studio fails to find an object with its default locator, Katalon tries other pre-configured locators associated with that object.

If Katalon Studio finds an object by any alternative locators, the test continues running. Once the broken object is self-healed, the alternative locator that successfully finds the object will be used for the remaining execution. This helps shorten execution time by preventing self-healing from happening again and again with the same broken object.

When the test execution is over, Katalon Studio suggests replacing the broken locator with the locator that found the object. Unless Katalon Studio can find the target object, depending on the failure handling option that you have designed, the test execution may stop or keep going. To learn more about the failure handling options, see Failure Handling.

Note:

• Self-healing suggestions with Smart Locators that are not approved in version 9.3.1 will not be visible when the project is opened in previous versions.

Configure Self-Healing Tests for WebUI

Configure Test Design for WebUI

1. Go to Project Settings > Test Design > WebUI.

2. Choose a default locator strategy. Under the Default element locator value of test objects generated by Recorder or Spy section, select one of the following locator strategies (XPath is selected by default):

tip

Select the strategy that works best with your application structure. XPath is flexible but can be fragile in dynamic DOMs. CSS and Smart Locator may offer better resilience.

3. (Optional) In the Recorder Plus section, exclude specific class or attribute name patterns from being used in auto-generated locators.

4. (If you select XPath) Set your locator priorities. You can drag and drop the locator types to change their evaluation order, or click Reset Default to revert the order back to the original Katalon default.

tip

Move the most stable or unique locators higher in the list to improve test resilience.

5. (If you select Attributes) Configure attribute-based locators to specify which HTML attributes should be considered when detecting objects.

tip

Prioritize attributes that are consistently used and unique (e.g., id, name). Avoid using dynamic values like class if they frequently change.

You can also use these actions to add, delete or clear a custom HTML attribute.

6. Click Apply and close to save your test design configuration for WebUI.

   Click Restore Defaults to revert all locator settings to original values.

For more information about configuring the test design for WebUI, see Selection methods for Web objects.

Enable and disable WebUI Self-healing mode

The Self-healing mode is enabled by default. To disable the self-healing mode:

1. Go to Project Settings > Self-Healing > WebUI, then clear the checkbox for Enable Self-healing execution.

You can also click the Self-Healing icon in the main navigation panel to open the Project Settings dialog.

2. Click Apply and Close to save your changes.

Locator methods for WebUI objects

You can decide which alternative locator method is tried first when a locator fails by setting a priority order in global settings.

1. In the Element locator method table, select or check the box one or multiple selection methods used for self-healing tests:

• XPath
• Smart Locator
• Attributes
• CSS
• Image

2. Reorder the locator methods by moving them up or down to set their priority.

3. If you click on Configure default locator, you are redirected to the Test Design section. See Configure test design for WebUI.

Override in Object view

In an object view, you can decide the default selection method for detecting that object during execution. This configuration overrides the Self-Healing global settings.

Configure Self-Healing Tests for Mobile

To learn how to configure test design for Mobile, see Locator strategies for Mobile objects.

Configure Test Design for Mobile

1. Go to Project Settings > Test Design > Mobile.

2. (For iOS only) Configure object tree display in Mobile Recorder and Spy. Click the dropdown to select either Full or Minimal display.

Notes

• If you select Minimal, the display shows a simplified object hierarchy.
• If you select Full, the display shows the complete object hierarchy, including all parent and nested UI elements.
• Frequently switching between display options may affect test execution stability.

3. Set the default locator type for mobile object generation. From the dropdown, choose your preferred locator strategy. This setting determines how Katalon Studio identifies and saves elements during mobile recording/spying:

4. Click Apply and close to save your test design configuration for Mobile.

   Click Restore Defaults to revert all locator settings to original values.

For more information about configuring the test design for Mobile, see Locator strategies for Mobile objects.

Enable and disable Mobile Self-healing mode

note

As of Katalon Studio version 10.3.0, Image Locator is currently not supported for Mobile Self-healing.

The Self-healing mode is enabled by default. To disable the self-healing mode, there are two ways:

1. Go to Project Settings > Self-Healing > Mobile, then clear the checkbox for Enable Self-healing execution.

You can also click the Self-Healing icon in the main navigation panel to open the Project Settings dialog.

2. Click Apply and Close to save your changes.

Locator methods for Mobile objects

You can decide which alternative locator method is tried first when a locator fails by setting a priority order in global settings.

1. In the Element locator method table, select or check the box one or multiple selection methods used for self-healing tests for Android and/or iOS:

2. Reorder the locator methods by moving them up or down to set their priority.

tip

Place the most stable and unique locators (e.g., ID, Accessibility ID, Predicate String) higher in the list to improve self-healing accuracy.

3. If you click on Configure default locator, you are redirected to the Test Design section. See Configure test design for Mobile.

Exclude objects used with keywords

In some scenarios, you may not want the test engine to try out different locators to find an object that doesn't exist.

To handle this, Katalon Studio allows you to exclude specific keywords from self-healing. When an object is used with one of these keywords, Katalon Studio skips the self-healing process.

To exclude WebUI or Mobile objects from self-healing when used with certain keywords:

1. Go to the Exclude objects used with the following keywords section in Project Settings > Self-Healing.

2. Click Add and enter the keyword you want to exclude. Objects used with this keyword will not trigger self-healing when their locator is broken.

When an object is used with a keyword listed in this section, Katalon Studio will not try to self-heal that object during execution.

For example: You add the verifyElementPresent keyword to the exclusion list. Suppose the input_Username_username object has a broken locator. You run the following script:

WebUI.openBrowser('https://katalon-demo-cura.herokuapp.com/')
WebUI.click(findTestObject('null'))
def username = findTestObject('Object Repository/Page_CURA Healthcare Service/input_Username_username')
WebUI.setText(username, 'John Doe')
WebUI.verifyElementPresent(username, 5)

Since verifyElementPresent is in the exclusion list, Katalon Studio will not attempt self-healing on the username object, and the test fails as expected.

Auto-excluded keywords (Non-Editable)

The following keywords are automatically excluded from self-healing by default. These are predefined and cannot be added or removed by users:

Web Auto-Excluded Keywords	Mobile Auto-Excluded Keywords
VerifyOptionNotPresentByLabelKeyword	verifyElementExist
VerifyOptionNotPresentByValueKeyword	verifyElementNotExist
VerifyOptionNotSelectedByIndexKeyword	verifyElementVisible
VerifyOptionNotSelectedByLabelKeyword	verifyElementNotVisible
VerifyOptionNotSelectedByValueKeyword	verifyElementAttributeValue
VerifyOptionPresentByLabelKeyword	verifyElementHasAttribute
VerifyOptionPresentByValueKeyword	verifyElementNotHasAttribute
VerifyOptionSelectedByIndexKeyword	verifyElementChecked
VerifyOptionSelectedByLabelKeyword	verifyElementNotChecked
VerifyOptionSelectedByValueKeyword	verifyElementText
VerifyOptionsPresentKeyword	verifyElementPresent
VerifyTextNotPresentKeyword	WaitForElementNotPresent
VerifyTextPresentKeyword	WaitForElementNotHasAttribute
VerifyElementAttributeValueKeyword	WaitForElementHasAttribute
VerifyElementCheckedKeyword	WaitForElementPresent
VerifyElementClickableKeyword	ScrollToText
VerifyElementHasAttributeKeyword
VerifyElementNotCheckedKeyword
VerifyElementNotClickableKeyword
VerifyElementNotHasAttributeKeyword
VerifyElementNotPresentKeyword
VerifyElementNotVisibleInViewportKeyword
VerifyElementNotVisibleKeyword
VerifyElementPresentKeyword
VerifyElementTextKeyword
VerifyElementVisibleInViewportKeyword
VerifyElementVisibleKeyword
WaitForElementAttributeValueKeyword
WaitForElementClickableKeyword
WaitForElementHasAttributeKeyword
WaitForElementNotClickableKeyword
WaitForElementNotHasAttributeKeyword
WaitForElementNotPresentKeyword
WaitForElementNotVisibleKeyword
WaitForElementPresentKeyword
WaitForElementVisibleKeyword

Self-healing Insights

After running your test with self-healing enabled, you can view the Self-healing Report in the Log Viewer.

Next to the Log Viewer tab, the Self-healing Insights tab displays a table containing suggestions for replacing broken locators. The table includes the following columns:

• Test Object ID: The ID of the broken test object.
• Broken Locator: The original locator that failed to detect the object during execution.
• Proposed Locator: The alternative locator that successfully located the object. If the object was found using its screenshot, this value is a newly generated smart XPath.
• Recovered By: The selection method Katalon Studio used to detect the object.
• Screenshot: When an object is located using an alternative locator, Katalon captures a screenshot of the test object so you can verify if it is correct. Click Preview to review the healed object.
• Select: Choose the locator(s) you want to take action on.

After verifying that the found object is correct, you can select one or more suggested locators and click:

• Approve: Save the proposed locator as the new default.
• Discard: Reject the proposed locator.