Post-run Agent
LocatorHealer
Automatically re-discovers broken DOM selectors using a headless browser and proposes healing patches — eliminating the manual selector-hunting that kills test suite health.
Trigger
LocatorHealer is triggered in two cases:
- A test fails with a locator-related error (element not found, selector timeout, no such element)
- FlakyDetector raises a locator instability flag on an unstable test
How healing works
- Navigate — LocatorHealer launches a headless Chromium session and navigates to the page where the locator failed, using the authenticated session from the test's fixture
- Discover candidates — it searches for the target element using multiple selector strategies in priority order:
data-testid, ARIA role + name, text content, CSS class, and XPath - Score candidates — each candidate selector is scored on uniqueness (does it match exactly one element?), stability (is it likely to survive UI changes?), and semantic correctness (does it refer to the right element type?)
- Generate patch — the highest-scoring selector replacement is compiled into a script diff (healing patch)
- Queue for approval — the patch is placed in the Approvals queue with the confidence score, the old selector, the proposed new selector, and a visual screenshot of the matched element
Healing patch review
In the Approvals queue, each LocatorHealer patch shows:
- The affected test script (scenario ID)
- The broken selector (old)
- The proposed replacement selector (new)
- Confidence score (0–1) and explanation
- A screenshot annotating the matched element on the live page
- Alternative candidate selectors if you prefer a different option
LocatorHealer patches always require manual approval — they are never applied automatically. This ensures a QA engineer reviews the proposed selector change before it is committed to the test suite.
Confidence score thresholds
| Confidence range | Interpretation | Recommendation |
|---|---|---|
| 0.90 – 1.0 | High confidence — unambiguous element match with stable selector | Safe to approve directly |
| 0.70 – 0.89 | Good confidence — clear match, slightly less stable selector | Review quickly and approve |
| 0.50 – 0.69 | Moderate confidence — multiple candidates, best one selected | Review carefully; consider adding data-testid |
| < 0.50 | Low confidence — element may have changed significantly | Inspect the screenshot; may require manual fix |
Best practice: When LocatorHealer proposes a CSS-class-based selector as its best option (low stability), take the opportunity to add a data-testid attribute to the element in your codebase. This permanently improves selector stability and reduces future healing activations.