NashTech Insights

Healenium – Self-healing locator tool for automation test

Tien Nguyen Anh
Tien Nguyen Anh
Table of Contents
Healenium Logo

Currently, we have a lot of tools supporting self-healing locator like Healenium, Mabl, Katalon. Each tool has different solution for self-healing. Today, I’ll share with you the Healenium because it’s an open-source and free which applies AI and machine learning and very easy to integrate with any Selenium-based automation framework.

It leverages AI and machine learning technology to integrate with Selenium-based frameworks to detect and heal the failure caused by the change in the UI.

1. Why do we need Healenium?

Nowadays, technologies change continuously, and our applications are updated frequently. Let’s see the below example.

Many projects schedule automated tests on a CI/CD tool during nighttime. If the login form changes and tests fail, it disrupts the automation framework. So, we must address the locators in the scripts promptly to avoid potential release delays. To prevent issues and streamline test script maintenance, self-healing locator technology assists in finding alternative elements when the defined ones cannot be located. This proves especially valuable close to release deadlines by minimizing flakiness and reducing the effort needed for investigation.

Here are the main features of Healenium:

  • Adopts test to UI changes: Healenium can replace the broken locator with the new one and make our test case more stable, especially the E2E test cases.
  • Update test code base: When we use IntelliJ as IDE, there’s a plugin of Healenium that will support us to update the test script automatically.
  • Support mobile: Healenium supports not only the web application but also the mobile application.
  • Report: After doing self-healing, Healenium will generate a report to share with us the locator that Healenium has worked on. The screenshot of the element is attached so that we can check if the self-healing function works correctly.

2. Healenium architecture

There are 2 approaches for using Healenium:

Healenium Proxy:  This is compatible with multiple programming languages such as Java, C#, Python, and JavaScript. It involves the usage of a proxy server positioned between Selenium and the web application. To implement this solution, we need to define the RemoteWebDriver and establish a connection to the Healenium Proxy instance.

Healenium Web: This supports Java only. We can integrate Healenium directly into our code with this solution. In this article, I focus on this approach. Let’s explore the key components of Healenium:

HLM-CLIENT: This component enhances Selenium by intercepting the findElement method to handle any errors encountered during element identification. When an element is successfully located, its information is sent to HLM-BACKEND. If the defined element cannot be found, HLM-CLIENT communicates with HLM-BACKEND to retrieve locator-related information. AI and machine learning techniques are employed in this component, specifically in the Tree-comparing component, to suggest new locators.

HLM-BACKEND: It’s responsible for parsing the information of a successful locator and storing the information in the database.

HLM-PLUGIN: This component will support to generate the report for self-healing activities.

HLM-IDEA: it’s a plugin for IntelliJ. It supports updating the locator in the script automatically instead of manually. HLM-IDEA will get the information about the locator from HLM-BACKEND and suggest user update the script. However, the suggested locators are CSS locators, so we need to check if the suggested locator is robust before using them.

PostgreSql: the database to store the locator information.

3. How does Healenium work?

3.1 Healenium workflow:

Let’s assume that we have a button whose Id is “btn”. When the automation script is run, it will find the element with method findElement(“btn”)). After finding the element successfully, HLM-CLIENT will send the locator to HLM-BACKEND to store it into database.

Unfortunately, the button ID changes to “button” one day. The automation script can’t find the element. The HLM-CLIENT will ask for the data of the previous run from HLM-BACKEND. Based on the current web page and data from HLM-BACKEND, Tree-comparing will suggest a similar button for the script to continue running the test.

How Healenium works?

3.2 Tree comparing:

As we know, the web page is an HTML file with the structure of tag and attribute. We can display them as the tree format as below:

During the execution of our automation script, the database stores the locator details such as locator type, class, method name, page content, and result. In the event of a locator-related issue, the tree comparing functionality comes into play. It retrieves the stored data and compares it with the current state of the web page to identify similar elements. The comparison is based on attributes such as tag, longest common sequence, ID, class, value, index, and other relevant attributes. Each attribute is assigned a specific weight, which contributes to calculating a point score for each element. Once the point scores are computed for all elements on the web page, the tree comparing component suggests the element with the highest score as the potential match.

3.3 Report:
After running self-healing activities, there is the report as below. We can see all the elements which are healed here with the attached screenshot. If it’s not the element we expect, we can toggle the Success button to Failed. The self-healing result will be updated to the database.

4. Integration with Selenium

In this section, I share how to integrate Healenium into Java Selenium framework.  I choose the installation by using Docker because it’s much easier and faster. After the installation, we can see the Healenium service is running on our machine.  For more information, it can be found at

4.1 Add Project dependency:
We need to add the dependency for Healnium Web into our pom file so that Maven will add it to our project.

Healenium - dependency

4.2. Add the Healenium configuration:
Create the with following content and add it to src/test/resources folder.

Healenium - properties

  • recovery-tries: number of proposed healed locator
  • score-cap: the minimum score to enable healing with predefined probability of match.
  •  heal-enabled: Flag to enable/disable self-healing
  •  hlm.server.url: Healenium backend server URL.
  •  hlm.imitator.url: Selector-imitator service URL

Please make sure that the URLs are matched with the information defined in the docker-compose file in the installation step.

4.3. Initialize the Selenium WebDriver:
In our code, we only need to wrap the Selenium WebDriver with the SelfHealingDriver. We don’t need to update other existing code because SelfHealingDriver extends the Selenium WebDriver and has all methods and properties of Selenium WebDriver. In our code, we go to the place where we initialize the Selenium WebDriver and define the SelfHealingDriver as below.

Healenium - test

After that, we’ll interact with the application through the SelfHealing Driver, not the original WebDriver.

4.4. Add report plugin:
To generate the Self-Healing report, we need to add the plugin into the pom file:

Healenium - report plugin

4.5. Text execution:
When we run test, if there’re any self-healing activities, they will be logged to console. The element which is used for self-healing will be highlighted.

Healenium - test execution


Healenium is a very useful tool to overcome to the challenges related to the project which UI changes frequently. It helps us to save time for script maintainability and make our test script more stable. It’s easy to integrate with any Selenium/Appium based framework. However, we need to be proactive in updating the locators in the script instead leaving these activities for the tool.
Healenium, being an open-source solution, may entail potential delays in addressing bug fixes, introducing new features, or obtaining support for setting up and integrating it into your automation framework. If expedited support from the Healenium team is desired, exploring the plans offered by Healenium is advisable.


Tien Nguyen Anh

Tien Nguyen Anh

I'm an Automation Test Manager with more than 10 years in software testing and development. Currently, I'm responsible for managing automation testing team, building their skills and supporting them to overcome issues. I also research the new automation testing technologies to share with team or conduct the training in NashTech.

Leave a Comment

Your email address will not be published. Required fields are marked *

Suggested Article

%d bloggers like this: