Integrating Healenium with Existing Selenium Test Suites

Integrating Healenium with Existing Selenium Test Suites

Most teams don't start a new Selenium project from scratch when they adopt Healenium. They have an existing suite — hundreds of tests, page objects, utility classes, possibly multiple WebDriver configurations — and they want to add self-healing without rewriting anything.

The good news: Healenium is designed for exactly this use case. The SelfHealingDriver is a drop-in wrapper. In most projects, the driver instantiation happens in one place, and changing that one place is the entire migration.

This post covers the full integration path: Docker Compose setup, wrapping your existing driver, page object compatibility, and edge cases that trip people up.

The Minimal Change

Wherever you create your WebDriver instance, wrap it:

// Before
WebDriver driver = new ChromeDriver();

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

The SelfHealingDriver implements WebDriver, so every call to driver.findElement(...), driver.findElements(...), and driver.get(...) works exactly as before. No interface changes, no test rewrites.

If your project creates drivers in a factory or base test class, you change one method and everything inherits healing automatically.

Docker Compose Setup

Healenium requires a running backend service and PostgreSQL. Here's a production-quality docker-compose.yaml with health checks and named volumes for persistence:

version: '3.8'
services:
  healenium:
    image: healenium/hlm-backend:3.4.4
    platform: linux/amd64
    container_name: healenium-backend
    ports:
      - "7878:7878"
    environment:
      DB_HOST: healenium-db
      DB_PORT: 5432
      DB_NAME: healenium
      DB_USER: hlm_user
      DB_PASS: hlm_secure_pass
      SERVER_PORT: 7878
    depends_on:
      healenium-db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7878/healenium/healenium-proxy/status"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  healenium-db:
    image: postgres:15-alpine
    container_name: healenium-db
    environment:
      POSTGRES_DB: healenium
      POSTGRES_USER: hlm_user
      POSTGRES_PASSWORD: hlm_secure_pass
    volumes:
      - healenium-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U hlm_user -d healenium"]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  healenium-data:
    name: healenium-locator-history

Start in detached mode and wait for healthy status:

docker compose up -d
docker compose ps   # confirm both services are "healthy"

The named volume healenium-locator-history persists locator history across container restarts. If you're running in CI, you'll need to handle volume persistence explicitly — covered in the CI/CD post in this series.

Configuration File

Create src/test/resources/healenium.properties:

heal-enabled=true
score-cap=0.5
heal-backend-url=http://localhost:7878
recovery-tries=1
screenshot-uploading=true
  • recovery-tries — how many times Healenium attempts healing before giving up. Usually 1 is correct.
  • screenshot-uploading — sends screenshots to the backend for HTML reports. Set to false if report size is a concern.

To disable healing for a specific run (e.g., to confirm a real failure), either set heal-enabled=false or pass it as a system property:

mvn test -Dheal-enabled=false

Integrating with a Driver Factory

Most mature Selenium projects have a DriverFactory or WebDriverManager utility. Here's a typical pattern before and after:

Before:

public class DriverFactory {
    private static ThreadLocal<WebDriver> driverThread = new ThreadLocal<>();

    public static WebDriver getDriver() {
        if (driverThread.get() == null) {
            WebDriverManager.chromedriver().setup();
            ChromeOptions options = new ChromeOptions();
            options.addArguments("--no-sandbox", "--disable-dev-shm-usage");
            driverThread.set(new ChromeDriver(options));
        }
        return driverThread.get();
    }

    public static void quitDriver() {
        if (driverThread.get() != null) {
            driverThread.get().quit();
            driverThread.remove();
        }
    }
}

After — one line change in getDriver():

import com.epam.healenium.SelfHealingDriver;

public class DriverFactory {
    private static ThreadLocal<WebDriver> driverThread = new ThreadLocal<>();

    public static WebDriver getDriver() {
        if (driverThread.get() == null) {
            WebDriverManager.chromedriver().setup();
            ChromeOptions options = new ChromeOptions();
            options.addArguments("--no-sandbox", "--disable-dev-shm-usage");
            WebDriver delegate = new ChromeDriver(options);
            driverThread.set(SelfHealingDriver.create(delegate));  // wrapped here
        }
        return driverThread.get();
    }

    public static void quitDriver() {
        if (driverThread.get() != null) {
            driverThread.get().quit();
            driverThread.remove();
        }
    }
}

Every test that calls DriverFactory.getDriver() now uses the self-healing driver. Zero changes to test classes or page objects.

Page Object Compatibility

Page objects that use @FindBy annotations or PageFactory.initElements() work with Healenium, but with a caveat: PageFactory initializes WebElement proxies at instantiation time, before any findElement call. Healenium intercepts at the findElement level, so the healing logic still fires when the element is actually accessed.

public class LoginPage {
    @FindBy(css = "button.login-btn")
    private WebElement loginButton;

    @FindBy(id = "username")
    private WebElement usernameField;

    public LoginPage(WebDriver driver) {
        PageFactory.initElements(driver, this);  // driver is SelfHealingDriver
    }

    public void login(String user, String pass) {
        usernameField.sendKeys(user);  // healing fires here if needed
        loginButton.click();           // and here
    }
}

This works correctly. The SelfHealingDriver intercepts the underlying findElement calls that PageFactory proxies eventually make.

Remote WebDriver and Selenium Grid

If your tests run against a Selenium Grid or cloud provider (BrowserStack, Sauce Labs), wrap the RemoteWebDriver the same way:

URL gridUrl = new URL("http://selenium-hub:4444/wd/hub");
DesiredCapabilities caps = new DesiredCapabilities();
caps.setBrowserName("chrome");

WebDriver delegate = new RemoteWebDriver(gridUrl, caps);
WebDriver driver = SelfHealingDriver.create(delegate);

The Healenium backend still runs locally (or in your infrastructure). Only the browser execution is remote. Locator paths are recorded from the DOM as seen by the remote browser, which is correct behavior.

Handling Edge Cases

Parallel test execution: Each thread should have its own SelfHealingDriver instance. The backend handles concurrent requests correctly — PostgreSQL serializes writes. Use ThreadLocal<WebDriver> as shown in the factory example above.

Tests that use explicit waits: Healenium doesn't interfere with WebDriverWait. If you use:

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
WebElement element = wait.until(ExpectedConditions.elementToBeClickable(By.id("submit")));

The driver here is SelfHealingDriver. The wait will retry findElement until the element appears or timeout. If the element ID has changed, healing fires on the first failed attempt within the wait loop. Be aware that a healing event inside a wait may log multiple findElement failures before the healed locator is tried — this is normal.

JavascriptExecutor: Healenium doesn't intercept executeScript calls. If you're clicking elements via JS as a workaround for flakiness, those calls bypass Healenium entirely.

// This bypasses Healenium — no healing possible
((JavascriptExecutor) driver).executeScript("arguments[0].click()", element);

Use standard Selenium interactions where possible so healing can apply.

StaleElementReferenceException: This is a different error from NoSuchElementException. Healenium handles NoSuchElementException (locator doesn't match anything). StaleElementReferenceException (reference to a previously found element is no longer valid) is not handled by Healenium — handle stale references with standard retry logic.

Verifying the Integration

After wiring in SelfHealingDriver, run your test suite once cleanly (against a working app state). Then check the backend:

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

You should see locator counts increasing in the database. To verify directly:

docker exec healenium-db psql -U hlm_user -d healenium -c "SELECT COUNT(*) FROM selector;"

A non-zero count confirms Healenium is recording locator paths successfully.

To verify healing fires, temporarily change a locator in one test to a broken value, run that test, then change it back. The healing report at target/healenium/ should contain an entry showing the healed selector.

Migration Checklist

  • healenium-web dependency added (Maven or Gradle)
  • healenium.properties in src/test/resources
  • Docker Compose file in project root, services started
  • SelfHealingDriver.create(delegate) in driver factory
  • First clean run executed (locator history seeded)
  • Verify backend has locator records
  • Confirm healing report directory created after any healing event

Most teams complete this migration in under an hour. The ongoing cost is maintaining the Docker Compose services and periodically reviewing healing reports.

When your team includes non-engineers who need to run or author tests without touching Selenium or locators at all, HelpMeTest fills that gap — letting product and QA teams write test scenarios in plain English while the Healenium-backed Selenium layer handles the technical execution.

Read more

Start now free