Getting Started with Healenium: Self-Healing Selenium Tests

Getting Started with Healenium: Self-Healing Selenium Tests

Selenium tests break. Not because your test logic is wrong, but because a developer renamed a CSS class, moved a button one level deeper in the DOM, or changed an ID during a refactor. The test still describes valid behavior — but the locator is stale.

Healenium solves this. It wraps your existing WebDriver and, when a locator fails, uses a machine learning algorithm to find the closest matching element in the current DOM. Your test passes. A healing report logs what changed. You fix the locator when you have time — not under incident pressure at 2am.

This post covers what Healenium is, how the self-healing mechanism works at a high level, and how to wire it into a real project using Maven or Gradle.

What Is Healenium?

Healenium is an open-source library that sits between your Selenium test code and the browser. It intercepts findElement calls, and when an element cannot be found using the original locator, it searches the DOM tree for the closest structural match using a path-similarity algorithm.

The key insight: instead of throwing NoSuchElementException immediately, Healenium asks "does something similar exist right now?" If the similarity score exceeds a configurable threshold, it uses that element and records the healing event in a PostgreSQL database. On your next run, it can use the healed locator directly.

This is not magic. Healenium works best when elements have moved or been renamed while retaining most of their structural context. It won't rescue you from a complete page redesign. But for the typical causes of locator rot — class renames, minor DOM restructuring, ID generation changes — it eliminates most false failures.

Architecture Overview

Healenium has two runtime components:

  • healenium-web — the Java library you add as a dependency. Provides SelfHealingDriver, which wraps RemoteDriver or any standard WebDriver.
  • healenium-backend — a Spring Boot service + PostgreSQL database that stores locator history and healing reports. Runs as a Docker container alongside your tests.

Your test code talks to SelfHealingDriver exactly like a normal WebDriver. The backend is called automatically when healing occurs.

Prerequisites

  • Java 11+
  • Docker (for the backend + database)
  • An existing Selenium project, or willingness to start one
  • Maven or Gradle

Step 1: Start the Healenium Backend

Create a docker-compose.yaml in your project root:

version: '3'
services:
  healenium:
    image: healenium/hlm-backend:3.4.4
    platform: linux/amd64
    ports:
      - "7878:7878"
    environment:
      DB_HOST: db
      DB_PORT: 5432
      DB_NAME: healenium
      DB_USER: healenium_user
      DB_PASS: YDk2nmNs4s
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: healenium
      POSTGRES_USER: healenium_user
      POSTGRES_PASSWORD: YDk2nmNs4s
    volumes:
      - healenium-db:/var/lib/postgresql/data

volumes:
  healenium-db:

Start it:

docker compose up -d

Confirm the backend is running:

curl http://localhost:7878/healenium/healenium-proxy/status

You should get a 200 OK with status info.

Step 2: Add the Dependency

Maven (pom.xml):

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

Gradle (build.gradle):

implementation 'com.epam.healenium:healenium-web:3.4.4'

Also add the Healenium configuration file. Create src/test/resources/healenium.properties:

heal-enabled=true
score-cap=0.5
heal-backend-url=http://localhost:7878
  • heal-enabled — master switch. Set to false in production if needed.
  • score-cap — minimum similarity score (0.0–1.0) required to accept a healed locator. 0.5 is a sensible default.
  • heal-backend-url — where the backend service is running.

Step 3: Wrap Your WebDriver

The only code change required is swapping your driver instantiation. Before:

WebDriver driver = new ChromeDriver();

After:

import com.epam.healenium.SelfHealingDriver;

WebDriver delegate = new ChromeDriver();
WebDriver driver = SelfHealingDriver.create(delegate);

That's it. Every findElement and findElements call on this driver now goes through Healenium's healing logic. Your existing test code requires no other changes.

Step 4: Write (or Run) a Test

Here's a minimal example that demonstrates healing in practice:

import com.epam.healenium.SelfHealingDriver;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.chrome.ChromeDriver;
import org.testng.annotations.AfterMethod;
import org.testng.annotations.BeforeMethod;
import org.testng.annotations.Test;

public class LoginTest {

    private WebDriver driver;

    @BeforeMethod
    public void setUp() {
        WebDriver delegate = new ChromeDriver();
        driver = SelfHealingDriver.create(delegate);
        driver.manage().window().maximize();
    }

    @Test
    public void testLogin() {
        driver.get("https://example.com/login");

        WebElement username = driver.findElement(By.id("username"));
        username.sendKeys("testuser");

        WebElement password = driver.findElement(By.id("password"));
        password.sendKeys("secret");

        driver.findElement(By.cssSelector("button.login-btn")).click();

        // assertion...
    }

    @AfterMethod
    public void tearDown() {
        if (driver != null) driver.quit();
    }
}

Run this once against a working page. Healenium records the locator paths into PostgreSQL. Now simulate a DOM change — rename login-btn to btn-login. Run again. Instead of failing, Healenium finds the button by structural similarity, logs the healing event, and the test passes.

Step 5: View Healing Reports

Healenium generates HTML reports for each healing event. By default they land in target/healenium/:

target/healenium/
  report-2024-01-15T10-30-00/
    index.html
    healing-detail-1.html

Open index.html in a browser. Each report shows:

  • The original (failed) locator
  • The healed locator that was used
  • A screenshot of the element in context
  • The similarity score

Use this report to update your source locators before the similarity degrades further.

Common Setup Issues

Backend not reachable: Check that port 7878 isn't blocked and the container is healthy. docker compose ps should show Up for both services.

Healing not triggering: Confirm heal-enabled=true in healenium.properties and that the file is on the classpath (check src/test/resources).

Score too aggressive / too lenient: If healing fires on unrelated elements, raise score-cap to 0.7 or higher. If valid heals are being rejected, lower it toward 0.3.

ChromeDriver path: Healenium doesn't manage WebDriver binaries. Use WebDriverManager or set the system property manually.

When to Use Healenium

Healenium is a good fit when:

  • Your app UI changes frequently but test logic stays valid
  • Locator rot is a major source of false negatives in your pipeline
  • You have Java-based Selenium tests and can add a Docker dependency

It's not a replacement for good locator strategy. If your tests rely entirely on unstable auto-generated IDs, Healenium will help but won't fully compensate. Add data-testid attributes where you control the frontend — then Healenium becomes a safety net rather than a crutch.

What's Next

Once Healenium is running locally, the logical next step is getting it into CI. That means persisting the PostgreSQL locator database between pipeline runs and surfacing healing reports as build artifacts — covered in a later post in this series.

If you're also maintaining no-code or cross-functional test coverage alongside your Selenium suite, tools like HelpMeTest let non-engineers write and run tests in plain English — complementing your Healenium-backed Selenium layer without requiring anyone to touch Java or locators.

Read more

Start now free