Healenium: Anti-flakiness potion
Test automation flakiness is a long-standing headache in UI testing. Selectors break, tests fail, and debugging becomes a frustrating ritual. Enter Healenium — a self-healing solution that enhances Selenium and Appium by automatically fixing broken locators at runtime.
In this article, you'll learn how Healenium integrates with your Java-based Selenium or Appium test framework, and how it transforms brittle tests into robust, maintainable assets.
What Is Healenium?
Healenium is an open-source library designed to augment web and mobile automation frameworks by enabling automatic healing of element locators. When a locator fails (due to minor UI changes, for instance), Healenium uses machine learning and history-based matching to find the most likely alternative, allowing the test to continue without failure.
Reference: healenium.io/docs
Core Features
- Automatic Locator Healing: Fixes broken XPath or CSS selectors on-the-fly.
- ML-based Matching: Uses previous DOM snapshots to find similar elements.
- Minimal Code Change: Simple integration into existing test frameworks.
- Compatibility: Works with Selenium WebDriver and Appium.
- Self-Healing Report Dashboard: Visualizes healed selectors and statistics.
- Multilingual Support via Proxy: Enables healing across various languages using Healenium-Proxy.
☕ Healenium + Selenium-Java: Integration Guide
1. Add Maven Dependencies
<dependency>
<groupId>com.epam.healenium</groupId>
<artifactId>selenium</artifactId>
<version>3.5.5</version>//Update accordingly
</dependency>
2. Wrap Your Driver
WebDriver delegate = new ChromeDriver();
SelfHealingDriver driver = SelfHealingDriver.create(delegate);
Now driver.findElement(...) is backed by Healenium's self-healing engine.
3. Set Up Healenium Backend (Optional but Recommended)
Healenium stores and compares locator history. To do this, run the backend via Docker:
docker-compose -f docker-compose-local.yml up
Includes:
- Healing Service
- Postgres DB
- UI Dashboard at
http://localhost:7878
Configure Healing Behavior (Optional)
Create a custom configuration file named healenium.properties under the test/resources directory:
recovery-tries = 1
score-cap = 0.5
heal-enabled = true
hlm.server.url = http://localhost:7878
hlm.imitator.url = http://localhost:8000
Config Parameter Explanations:
- recovery-tries – Number of proposed healed locators to try.
- score-cap – Healing only proceeds if the match score is >= this threshold (e.g., 0.5 means 50%).
- heal-enabled – Enables/disables healing (can be overridden using
-Dheal-enabled=false).
- hlm.server.url – Address of the Healenium backend.
- hlm.imitator.url – Address of the imitate service.
Disable Healing for Specific Methods
Use the @DisableHealing annotation to skip healing for specific methods:
@DisableHealing
public boolean isButtonPresent() {
try {
return driver.findElement(By.cssSelector(".test-button")).isDisplayed();
} catch (NoSuchElementException e) {
return false;
}
}
Healenium Report
Healenium generates a detailed HTML report after each Selenium session, accessible via browser.
Local URL: http://localhost:7878/healenium/report/
Report Sections Include:
- Path to healed locator
- Failed locator value
- Healed locator value
- Screenshot of healed locator on page
- Healing success confirmation (correct/not correct)
- Score of the healing result
⚠️ Note: The Maven/Gradle report plugins are deprecated and no longer supported.
Healenium + Appium
Healenium supports Appium too, using the same SelfHealingDriver. Simply delegate your mobile driver (like AndroidDriver or IOSDriver) to SelfHealingDriver.create(...). For example:
AppiumDriver delegate = new AndroidDriver<>(url, capabilities);
SelfHealingDriver driver = SelfHealingDriver.create(delegate);
Ensure that Appium and Healenium versions are compatible. Use native locators (like XPath, accessibility ID) for best results.
Real-World Usage Tips
- Store all your element locators centrally to monitor which ones heal frequently.
- Use Healenium’s dashboard to identify flaky elements and clean up your selectors.
- Combine with Allure Reports to attach healed screenshots and diagnostics.
Beyond Java: Other Language Support
Healenium-Proxy enables healing across all Selenium-supported languages, such as Python, JavaScript, C#, and more.
To use Healenium in other languages, simply create a RemoteWebDriver and connect it to the Healenium-Proxy instance. This allows clients in any language to benefit from Healenium's healing capabilities without needing native library support.
from selenium import webdriver
options = webdriver.ChromeOptions()
driver = webdriver.Remote(
command_executor='http://localhost:7878/wd/hub',
options=options
)
This approach allows teams to integrate healing logic regardless of the language or test framework they use.
Enable Console Debug with SimpleLogger
To see detailed Healenium logs during test execution, configure simplelogger.properties as follows:
org.slf4j.simpleLogger.log.healenium=debug
Place this file in your test/resources directory. This enables console-level debug logging for Healenium's internal operations, helping with troubleshooting and development.
Last Thoughts
Healenium empowers your automation framework with self-healing capabilities, helping reduce flaky failures, improve resilience, and speed up debugging. Whether you're working with Selenium for web or Appium for mobile, Healenium is a lightweight but powerful addition.
Official Docs | GitHub
