How Healenium Self-Healing Works: Locator Algorithms and ML Under the Hood

How Healenium Self-Healing Works: Locator Algorithms and ML Under the Hood

Most people who add Healenium to their project treat it as a black box — locator breaks, Healenium fixes it, test passes. That works fine until healing starts misfiring: the wrong element gets selected, a score just above the threshold causes a false pass, or the backend history grows stale with locators from a UI that no longer exists.

Understanding how Healenium actually works makes you a better user of it. This post covers the tree-path algorithm, how similarity scoring works, what gets stored in PostgreSQL, how to read healing reports, and where the confidence threshold matters.

The Core Problem: Locators Are Fragile

A Selenium locator like By.cssSelector("div.login-form > button.submit") is a structural contract with the DOM. When the DOM changes — even slightly — the contract breaks. The typical response is manual locator maintenance: find every failing test, find the new selector, update the code, push, repeat.

Healenium's approach: instead of failing immediately, search the current DOM for the element that best matches the historical record of what you were originally looking for.

How Healenium Captures Locator History

The first time your test runs with SelfHealingDriver, Healenium records every successful findElement call into its PostgreSQL backend. It stores:

  • The locator expression (CSS selector, XPath, ID, etc.)
  • The full DOM path to the element — a sequence of node descriptors from root to target
  • A timestamp and a reference to the test method that used it

Each node in the path is described by tag name, attributes (id, class, name, type, etc.), and position among siblings. This path is the reference fingerprint Healenium uses later when the original locator stops working.

The Tree-Path Algorithm

When a findElement call fails, Healenium doesn't just scan the DOM randomly. It applies a tree-path similarity algorithm based on the stored node path.

Here's the conceptual process:

  1. Retrieve the stored path for the failed locator from PostgreSQL.
  2. Walk the current DOM and generate candidate paths — one for each element that shares the same tag name as the target.
  3. Compare each candidate path against the stored path using a similarity function.
  4. Score all candidates and select the highest-scoring one above the threshold.

The similarity function compares node-by-node along the path, scoring matches on:

  • Tag name match (highest weight)
  • Attribute value matches (id, class, name each contribute)
  • Relative position among siblings
  • Path length difference (shorter divergence = higher score)

The algorithm is essentially a weighted edit-distance calculation on sequences of DOM node descriptors. It's not a neural network — it's a deterministic similarity metric, which is why "ML-based" is slightly misleading in some marketing material. The intelligence is in the path encoding and weighting scheme, not a trained model.

Similarity Scoring in Practice

Every candidate element gets a score between 0.0 and 1.0. The score-cap property in healenium.properties sets the minimum acceptable score.

score-cap=0.5

With score-cap=0.5, an element must be at least 50% similar to the stored path to be used as a healed locator. The default is usually sensible, but you'll want to tune it:

Score cap Behavior
0.3 Aggressive healing — accepts weak matches. Risk of wrong element.
0.5 Balanced default — works well for minor DOM changes.
0.7 Conservative — only heals clearly equivalent elements.
0.9 Very strict — mostly catches attribute renames, not structural moves.

If your app goes through heavy redesigns, a high score cap will reject most healing attempts (which is correct — a fully restructured page should prompt locator rewrites, not guesses). For minor refactors — class renames, button moves within a form — 0.5 to 0.6 is usually right.

What Healenium Stores in PostgreSQL

The backend uses three main tables:

selector — one row per unique locator seen across all test runs:

  • selector — the original locator string
  • node_path — JSON array of node descriptors (the stored path)
  • heal_locator — the last successfully healed locator expression (null until first healing)
  • score — the similarity score of the last healing

healing_result — one row per healing event:

  • selector_id — FK to selector
  • healed_selector — what was actually used
  • score — similarity score at healing time
  • failed_locator — the locator that triggered the healing

screenshot — binary blob of the page screenshot at healing time, linked to healing_result.

This history accumulates across test runs. The same locator is referenced by its string value, so if you change a locator in your test code, Healenium starts fresh for that locator. The old history isn't deleted — it just becomes orphaned.

Healing Reports

After a test run that triggered any healing events, Healenium generates an HTML report. Default output path: target/healenium/.

Each report entry contains:

  • Original locator — what your test code specified
  • Healed locator — what was actually used (a generated XPath or CSS selector for the matched element)
  • Similarity score — how confident the match was
  • Screenshot — annotated image showing the matched element highlighted in context
  • Test class and method — so you know exactly which test was affected

The healed locator in the report is your signal to go update your source code. It's not enough to let Healenium keep re-healing the same locator indefinitely — if the page has changed, your tests should reflect the current state.

The Healing Decision Flow

Here's the complete decision tree when SelfHealingDriver.findElement(by) is called:

1. Try original locator
   → Found: return element, record path to DB (if not already there)
   → Not found: proceed to step 2

2. Query DB for stored path of this locator
   → No path found: throw NoSuchElementException (can't heal without history)
   → Path found: proceed to step 3

3. Scan current DOM for candidates matching the target tag
4. Score each candidate against stored path
5. Filter candidates with score >= score-cap
   → No candidates above threshold: throw NoSuchElementException
   → Candidates found: select highest-scoring one

6. Return healed element
7. Log healing event to DB + generate report entry

The critical implication: Healenium cannot heal a locator it has never seen succeed. The first run must be clean. If you add a test and immediately break the locator before ever running successfully, Healenium has nothing to reference.

Confidence Thresholds and Edge Cases

Multiple elements at similar score: Healenium selects the highest-scoring candidate. If two elements score identically (rare but possible in heavily repeated DOM structures like list items), the first match in DOM order wins.

findElements (plural): Healenium also heals multi-element queries. Each element in the result set goes through individual path comparison against the stored multi-element history.

iframes: Healenium operates within the currently focused frame context. Frame switching is your responsibility — Healenium heals within whatever frame the driver is currently focused on.

Shadow DOM: Standard Healenium doesn't pierce shadow roots. If your app uses Web Components with shadow DOM, Healenium's path algorithm won't traverse into shadow subtrees.

Dynamic elements (modals, tooltips): These are high-risk for false heals. An element that appears and disappears frequently accumulates many different path snapshots. Consider higher score caps or exclusions for such elements.

When Healing History Goes Stale

The PostgreSQL database persists locator history indefinitely. After a major UI rewrite, old paths may produce low-quality heals or false positives. Strategies:

  • Periodic truncation: TRUNCATE selector CASCADE; before a major release cycle. Healenium rebuilds from the first post-rewrite run.
  • Environment isolation: Use separate PostgreSQL instances for staging vs. production pipelines. Staging heals shouldn't pollute production locator history.
  • Score cap adjustment: Raise score-cap during a post-rewrite stabilization period to avoid accepting stale heals.

Summary

Healenium's self-healing is a path-similarity algorithm, not a trained neural network. It works by storing full DOM paths on successful runs and comparing them against the current DOM when a locator fails. The PostgreSQL backend is the memory, the similarity scorer is the brain, and the score-cap threshold is your confidence dial.

Understanding this means you can tune it properly, interpret healing reports accurately, and know exactly when to let Healenium handle a locator change versus when to update your tests manually.

For teams also running non-Selenium tests — exploratory, visual, or cross-functional — HelpMeTest provides a no-code layer where QA and product teams can write tests in plain English, complementing the Healenium-backed Selenium suite without requiring locator knowledge at all.

Read more

Start now free