One of the biggest challenges in test automation is flaky tests. Often, your test scripts fail because of UI changes (like modified element locators, renamed IDs, or shifted elements). Fixing these broken tests manually consumes a lot of time and effort.

This is where Healenium comes in.

Healenium is an open-source AI-powered self-healing library for Selenium and Appium. It can automatically detect broken locators at runtime and replace them with the most relevant working ones. This means fewer test failures and less time spent fixing automation scripts.

How Healenium Works?

• You write your Selenium tests as usual.
• When a locator breaks, Selenium would normally throw an exception.
• Instead, Healenium intercepts this error.
• It queries its AI-powered backend (running via Docker), which maintains historical locator information.
• Healenium finds the closest match and updates the locator automatically.
• Your test continues without interruption 🚀.

Setting Up Healenium

1. Prerequisites

• Java 8 or higher
• Maven (or Gradle)
• Selenium WebDriver
• Docker (to run the Healenium backend)

2. Add Dependency in Maven

Add the following in your pom.xml:

<dependency>
    <groupId>com.epam.healenium</groupId>
    <artifactId>healenium-web</artifactId>
    <version>3.4.0</version>
</dependency>

3. Update WebDriver Initialization

Instead of using the standard Selenium driver, wrap it inside Healenium’s SelfHealingDriver:

import com.epam.healenium.SelfHealingDriver;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

public class HealeniumDemo {
    public static void main(String[] args) {
        WebDriver baseDriver = new ChromeDriver();
        SelfHealingDriver driver = SelfHealingDriver.create(baseDriver);

        driver.get("https://example.com");
        driver.findElement(By.id("loginButton")).click();

        driver.quit();
    }
}

4. Run Healenium Backend with Docker

Healenium requires a backend service for storing locator history and applying healing.

Run this command:

docker run -p 7878:7878 -p 7879:7879 healenium/hlm-backend:3.4.0

5. Optional Configuration File

Create a healenium.properties file under src/test/resources:

serverHost=localhost
serverPort=7878
heal-enabled=true

6. Run Your Test Suite

Now run your tests. If a locator breaks, instead of failing, you’ll see logs like:

Your script continues running without failure.

✅ Example in Action

Let’s say your test script uses this locator:

driver.findElement(By.id("loginButton")).click();

Without Healenium → Test fails with NoSuchElementException.
With Healenium → Test passes because it finds a matching button using AI-based locator history.

Benefits of Using Healenium

• No need to constantly update broken locators.
• Reduces test maintenance effort.
• Works with Selenium and Appium.
• Open-source and community-supported.

Another Example: Healing a Changed XPath

driver.findElement(By.xpath("//input[@name='username']")).sendKeys("Yash");

Without Healenium: Test fails with NoSuchElementException.
With Healenium: Healenium automatically heals it to → By.xpath("//input[@name='user_name']")

Why Use Healenium Over Traditional Selenium?

• Traditional Selenium fails on any UI change.
• Healenium reduces test flakiness by auto-healing.
• Saves maintenance cost and effort.

Healenium Architecture

SelfHealingDriver → Healenium Backend (via Docker) → AI Healing → Updated Locator → Continue Execution.

Supported Features

• Works with Selenium (Web) and Appium (Mobile).
• Supports Java currently (with Selenium).
• Logs original and healed locators for debugging.
• Stores locator history in DB for future reference.

When to Use Healenium?

• Agile projects with frequent UI changes.
• Large-scale automation suites.
• Mobile/web apps with dynamic elements.

Limitations of Healenium

• Currently works best with Java + Selenium.
• Needs Docker for backend.
• Healing isn’t 100% accurate for complex DOM changes.
• Still requires some manual validation.

Best Practices

• Use unique locators as much as possible.
• Monitor logs for correct healing.
• Run backend service before execution.
• Combine with Page Object Model (POM).

Comparison With Commercial AI Tools

Compared with Mabl, Testim.io, Applitools → Healenium is open-source and cost-effective.

Pro Tip