How 3-Tier Locator Healing Works
UI changes are inevitable. Here's exactly how SentinelFlux keeps your test suite alive without requiring a human to manually hunt down new selectors.
The most common reason automated UI tests break isn't a bug in the product — it's a locator that no longer matches an element. A class name was renamed during a CSS refactor. An ID was removed. An aria-label was updated for accessibility. The test fails, a human investigates, realises nothing is actually broken, updates the selector, and commits. Multiply that by 50 tests and you have a maintenance tax that compounds every release.
Why locators break in the first place
Most test frameworks select DOM elements by CSS selectors, XPath, or IDs. These are tied directly to implementation details — the very things that change most frequently during UI development. Even a well-intentioned refactor (moving to semantic HTML, adding BEM naming, extracting a component) can silently break dozens of tests.
The root cause isn't the tests themselves — it's that they're coupled to implementation rather than intent. A test that says "find the element with class btn-primary-v2" is fragile. A test that says "find the submit button on the login form" is robust, if the right locator strategy backs it.
Tier 1: Primary locators
SentinelFlux's AppExplorerAgent crawls your live application before generating tests and maps every interactive element to a ranked set of locators. The primary tier uses the most semantically stable attributes: data-testid, aria-label, role, and name. These are attributes developers add specifically for testing or accessibility — they rarely change as a side-effect of styling work.
When a test runs, it tries the primary locator first. If it resolves, the test proceeds normally. Most of the time, this is sufficient.
Tier 2: Alternative locators
If the primary locator fails to resolve, SentinelFlux automatically tries the ranked alternatives stored in the locator file: id, name, placeholder, CSS path, and finally positional XPath as a last resort. This fallback happens transparently during test execution — no human intervention, no test failure.
If an alternative locator succeeds, SentinelFlux records which alternative was used and flags the locator as needing an update — so you can promote a stable alternative to primary on your next run.
Tier 3: AI healing
If all stored locators fail, the LocatorHealerAgent activates. It launches a headless browser, navigates to the relevant page, and uses AI to analyse the live DOM and identify the most likely match for the element based on its semantic role, surrounding context, and text content. It then proposes a new primary locator.
Critically, this proposal goes into the Approvals queue in the dashboard — it is not committed automatically. A human reviews the suggestion, sees the old locator, the new proposal, and the page context, and either approves or rejects it. Only approved heals are written back to the locator files.
Why the human approval step matters
Fully autonomous healing sounds appealing until the AI heals to the wrong element — perhaps a visually similar button on the same page. Without human review, that bad heal silently ships, and your test passes while testing the wrong thing. The approval queue is the safeguard that keeps "self-healing" from becoming "self-deceiving".
The practical result: UI refactors that used to cause weekend fire-drills become a five-minute approval workflow on Monday morning.