Self-healing tests in Katalon Studio

This article guides you through Katalon Studio's different self-healing mechanisms of broken object locators while maintaining test cases.

requirements

An active Katalon Studio Enterprise license

When the application under test (AUT) changes, some object locators might no longer work due to UI changes, and the test case fails to identify target elements that worked before.

To assist with test maintenance, Katalon Studio supports different self-healing mechanisms to self-heal broken object locators during executions.

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 mechanisms

With self-healing enabled, Katalon Studio tries other pre-configured locators of that object, to try to detect it. If it finds one alternative locator that works, the test continues, and Katalon Studio suggests replacing the locator with the broken one, once the test finishes.

Katalon Studio also supports self-healing with AI, as a fallback when self-healing fails to detect a locator the classic way. This feature uses a Large Language Model (LLM) to read inputs such as page source, accessibility tree, full-page screenshot, and element screenshots to try and locate the element.

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

Self-healing Execution for WebUI

1. Go to Project Settings > Test Design > WebUI and enable Self-healing execution. This is enabled by default.

2. Enable and drag the locators to set priorities. Katalon Studio checks locators in this order, to find the suitable alternative locators.

tip

• Move the most stable or unique locators higher in the list to improve test resilience.
• XPath is flexible but can be fragile in dynamic DOMs. CSS and Smart Locator may offer better resilience.
• If you select Attributes, configure attribute-based locators to specify which HTML attributes should be considered when detecting objects.

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

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

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

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

AI Self-healing for WebUI

requirement

• Personal OpenAI's API key.

Setup steps:

1. Enable AI-self healing in Project > Self-healing > WebUI.
2. Allow different input data sources for the AI. Selecting more sources increases healing accuracy but may slightly increase processing time.

3. Provide an OpenAI's API key. AI Self-Healing currently supports OpenAI models only, and requires a personal API key.

   • You can declare the API key in Project Settings > Execution > Launch Arguments and enter: -DOPENAI_API_KEY=${{ YOUR_API_KEY }}. This method is convenient, but risks exposing your OpenAI's API key.
   • Or, you can store your API key in a Global Variable, then declare the AI model and API key include the following script in your test case or a test listener:

   //set the AI model. If you dont, system falls back to "gpt-4o-mini"
   System.setProperty("SELF_HEALING_AI_MODEL", "${{ YOUR_AI_MODEL }}");
   //set the API key for your AI model. 
   System.setProperty("OPENAI_API_KEY", "${{ YOUR_API_KEY }}")

   Replace ${{ YOUR_AI_MODEL }} and ${{ YOUR_API_KEY }} with a model name and API key. Rather than hard-coding the API key, you can

Once enabled, if the default self-healing mechanism fails to detect the object, the AI self-healing feature will trigger to analyze your application’s current state, and attempt to generate a new locator. This reduces manual object maintenance and increases the chance of successful execution when the UI changes.

You can check the AI self-healing process in the Log viewer:

Then, review/approve the proposed locator in the Self-healing Insights tab as usual:

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.