I was super excited to use the Self-Healing feature in Katalon Studio because my team’s application updates its UI constantly. I thought this would save my scripts from breaking, but it’s actually causing a nightmare.
I have a form where the user fills out some data and needs to click a “Confirm” button. Yesterday, the developers changed something in the HTML structure of that page. Instead of throwing an error or letting me know the element was missing, Katalon’s Self-Healing kicked in. The logs said it successfully healed the object using an alternative XPath… but it ended up clicking the “Cancel” button instead! Because it clicked Cancel, all the data was wiped out, and my subsequent test steps failed because the next page never loaded.
The issue you are experiencing stems from how Katalon Studio’s Self-Healing mechanism prioritizes alternative locators. When the primary locator (e.g., XPath) fails, the Self-Healing engine sequentially attempts the alternative locators configured in your object’s definition (such as Attributes, Neighbor XPath, or CSS).
If your “Confirm” and “Cancel” buttons share similar hierarchical structures or attributes (e.g., both are <button> tags inside the same <div>), a generic fallback locator like a relative neighbor XPath can accidentally match the “Cancel” button. To the engine, a valid DOM element was found, so it proceeds with the action, completely unaware of the semantic difference between “Confirm” and “Cancel”.
The Solution
To resolve this globally and robustly, you need to configure your Self-Healing Insights and Settings to prioritize strict, unique locators, and exclude weak ones.
Refine Global Self-Healing Settings: Go to Project > Settings > Self-Healing > Web UI. Look at the Locator Method list. Demote or uncheck generic locators like XPath: link text or vague Attributes if your app has highly dynamic text. Prioritize XPath: id relative or robust CSS selectors.
Configure Exclusions: In the same settings menu, you can exclude specific keywords or object IDs from being healed automatically if they are critical to business logic (like form submissions).
Strengthen the Test Object: Ensure your primary Object uses a robust XPath that specifically contains the text or an immutable attribute unique to “Confirm” (e.g., //button[text()='Confirm']).
1. Refine Global Self-Healing Settings (Recommended)
Go to Project > Settings > Self-Healing > Web UI
In the Locator Method list:
Demote or uncheck generic locators like “XPath: link text” or vague attributes if your app has dynamic text
Prioritize robust options like “XPath: id relative” or CSS selectors [web-post:1]
2. Configure Exclusions
In the same settings menu, exclude specific keywords or object IDs from automatic healing if they’re critical to business logic (like form submissions)
3. Strengthen the Test Object
Ensure your primary object uses a robust XPath that specifically contains unique text or an immutable attribute:
//button[text()='Confirm']
4. Manual Selection Option (Community Request)
One user noted Self-Healing should ideally provide an option to manually select which element to use, but this feature isn’t available yet
Root Problem
Generic fallback locators aren’t unique enough. You need to demote weak locators and strengthen your primary object definition to prevent Self-Healing from matching the wrong element when UI changes occur
Just make sure your fallback selectors are also strict and unique to “Confirm” only.
Right now self-healing is picking a generic XPath that matches both buttons.
Keep self-healing ON, but remove weak locators and use text-based or ID-based ones so it can’t accidentally choose “Cancel”.
Your issue is nothing but he classic example of locator selection in self healing of katalon.
Self-Healing is designed to keep your test running when the original locator no longer works, but it does not understand business intent. It only tries to find the “closest matching element” based on the locator strategies available. If multiple elements look similar, Katalon may heal to the wrong element, which appears to be exactly what happened in your case.
Why did Katalon click “Cancel” instead of “Confirm”?
and the developers removed the id, Self-Healing may fall back to another locator strategy such as:
//button[@class='btn btn-primary']
Now both buttons match. Depending on the DOM structure, Katalon may select the first match it finds, which could be the Cancel button.
The test continues running because Self-Healing found an element, but not necessarily the correct element.
How to prevent this?
1. Use more unique locators
Avoid generic XPath expressions such as:
//button[contains(@class,'btn')]
Instead, target something unique:
//button[normalize-space()='Confirm']
or
//button[@data-testid='confirm-button']
You can even ask developers to provide stable attributes such as:
data-testid="confirm-button"
These attributes rarely change and are ideal for automation.
Katalon’s TestObject allows you to use CSS Selector as its locator as well as XPath. If you are new to both of CSS Selector and XPath, and if you want to choose one to get started, I would recommend you to learn CSS Selector rather than XPath.
If you want to learn CSS Selector, please read the following article:
the real fix is at the test object level, not the global settings. If your Confirm and Cancel buttons share class and structure, no amount of reordering locator strategies will save you. The fallback locators generated by Katalon are inherently generic.
add a unique selector to each test object as the primary locator. Use //button[normalize-space()='Confirm'] or a data-testid attribute. If your primary locator is solid, self-healing rarely kicks in for that object in the first place.
for objects where a wrong heal would be catastrophic (payment confirms, deletions), you can disable self-healing per execution in Project > Settings > Self-Healing > Web UI by unchecking the locator types that tend to produce ambiguous matches. After a run, review the Self-Healing insights in TestOps and reject any wrong suggestions so they do not get promoted to new default locators.
You should sit down and study the CSS Selector or XPath technology for a few days to build up your skill. Then you would be able to rewrite any problematic locators. See the following articles as study materials.
Provided that you’ve built a good skill about the locator technologies, you can make good use of the generation tools — Web Recording, Spy which would guess what you want and propose a candidate locator string. You would evaluate the proposals and rewrite them manually to make them robust against possible HTML changes in future. That’s the way I use the Web Recording tool as assistant.
I would never expect the tools can forecast HTML changes in future. It’s only you who can think about possible changes in your target HTML and prepare yourself. I don’t know if any AI can do that sort of magic.
I never use the Self-Healing feature, as I do not think it can help me. No need to tell @znikolaus why, I think.
You need to find a balance between a robust locator strategy and a self-healing setup that suits you and the SUT.
I would recommend talking with the dev team and suggesting that they add a specific testID attribute, as @depapp mentioned. (Now you have an additional challenge: convincing the dev team to do this )
Last but not least, if the UI is constantly changing, that could be the main problem here. Maybe you should rethink your automation approach, perform a feasibility analysis for the test scripts, and prioritize them based on their complexity and likelihood of change.
That will enable you to automate while considering the cost and value of each script.
With this approach, you would pay less attention to the individual HTML elements. Therefore the visual testing is insensitive against the changes in the DOM structure.
You shouldn’t look into the too much details. You should have a bird’s-eye view just to see how a web page looks like.
With this approach, you would take screenshots of pages; and compare the current image and the baseline image; find out the visual difference. If the tool notified you of any difference, you would review the difference and think. The tool does not make judgements. You are the one who judges the results. You should check whether the visual differences you see on the screen are as expected. It is up to you to determine whether the difference is significant.
)