Self-healing tests in TestInspector automatically detect when a test step fails due to a changed selector and use AI to propose and apply a replacement selector, then retry the step without manual intervention. The feature is controlled by an auto_retry flag on each test record and works by querying the AI with the page's current DOM structure alongside the original step intent, selecting the best matching element, storing the correction for future runs, and marking the run as self-healed. Broken selectors are the primary cause of test suite maintenance overhead after UI changes, and self-healing reduces the time spent on that maintenance significantly.

Why Selectors Break and Why It Matters

Browser tests interact with the DOM through selectors — CSS selectors, XPath expressions, or element attributes like id and data-testid. A selector that worked when the test was written will fail if a developer changes a class name, restructures the page hierarchy, removes an id attribute, or migrates to a component library that generates different markup. None of these changes break application functionality; they only break the test's ability to locate the element it needs.

In a large test suite, even infrequent UI refactors can produce dozens of broken steps. Each one requires a QA engineer to open the test, inspect the failure, load the page, find the correct selector for the renamed or restructured element, edit the step, and re-run to confirm. Multiplied across a full regression suite, this activity consumes significant engineering time that would be better spent on new coverage.

The cost is not limited to direct repair time. Suites with high selector fragility develop a culture of low trust: engineers run tests expecting failures, begin ignoring red test results, and lose the early-warning value that automated testing provides. For background on building sustainable test suites, see Astaqc's test automation services and the complete software testing guide.

How Self-Healing Works in TestInspector

TestInspector's self-healing mechanism activates after any step failure when the test's auto_retry flag is set to true. The process runs entirely within the existing Celery worker executing the test — no separate service, no external queue.

When a step fails, the self-healing module captures three inputs: the original step's command, target, and value; the error message returned by Selenium (typically a NoSuchElementException or ElementNotInteractableException); and the current page's DOM structure captured immediately after the failure. These inputs are assembled into a prompt for the AI and sent to the configured language model, which is Claude Sonnet 4.6 by default via OpenRouter.

The AI analyzes the DOM against the step's intent and returns one or more alternative selectors ranked by confidence. TestInspector attempts each in sequence. If a retry succeeds, the corrected selector is written back to the step record in the database and the run continues. The run report marks the step as self-healed, recording both the original and corrected selector for review. If no alternative succeeds, the step is marked as failed and the run stops (or skips, if the step is marked optional).

The Auto-Retry Flow: Step by Step

Understanding the execution flow helps set realistic expectations about what self-healing can and cannot recover from.

1. Step executes normally. TestRunner attempts the step using the stored selector.
2. Step fails. Selenium raises an exception — element not found, element not interactable, or stale element reference.
3. auto_retry check. If the test's auto_retry flag is false, failure is recorded and execution halts. If true, self-healing activates.
4. DOM snapshot. TestRunner captures the rendered page source at the point of failure.
5. AI query. The self-healing module sends the original step intent, the error, and the DOM snapshot to the language model requesting alternative selectors.
6. Retry with alternatives. Each suggested selector is attempted in order until one succeeds or all are exhausted.
7. Selector persistence. On success, the winning selector replaces the original in the database. Future runs use the corrected selector without re-querying the AI.
8. Run continues. Execution proceeds to the next step. The step result is tagged as self-healed in the run report.

The selector persistence step is significant. Once a selector is corrected, subsequent runs are not slower — they use the stored selector directly without triggering the AI query unless the new selector also breaks. Self-healing is an exception path, not the normal execution path.

What the AI Uses to Identify Alternative Selectors

The quality of selector suggestions depends on the richness of the DOM context provided to the AI and the stability of the attributes available on the target element.

TestInspector provides the AI with: the original selector and command type, the surrounding DOM structure near the expected element, the element's text content if the original step referenced visible text, and the step's value field if it describes expected text or an input value. From these inputs, the AI can identify candidate elements by semantic role, accessible name, visible label, or data attribute.

Selectors suggested by the AI are prioritized in stability order: data-testid or data-cy attributes first (if present), then ARIA roles and accessible names, then visible text content, then position-based selectors. This ordering matches standard selector stability guidance and reduces the likelihood that the corrected selector will also break at the next UI change.

The AI approach is more robust than simple heuristics because it evaluates semantic intent. A button labeled Submit Order that has moved from a form footer to a modal is still identifiable by its label even though its DOM path has changed entirely. For teams evaluating test maintenance strategies more broadly, see TestInspector's product page, Astaqc's testing services, and the manual vs automated testing guide.

Self-Healing vs Manual Maintenance: Comparison

When Self-Healing Helps and When It Does Not

Self-healing is highly effective when the UI change was cosmetic or structural — a developer renamed a class, wrapped an element in an additional div, changed a button from an anchor tag to a button tag, or migrated to a new component library that generates different markup. In these cases, the element still exists, the user-facing intent is unchanged, and the AI can identify a reliable alternative selector.

Self-healing is not designed to handle tests that need to be rewritten because application behavior has changed. If a feature was removed, a flow was redesigned, or an assertion value is no longer correct, the test itself is wrong — not just its selector. Accepting a healed selector in these cases would produce a test that passes but no longer validates meaningful behavior. TestInspector's run report distinguishes self-healed steps clearly so engineers can review whether the correction reflects a legitimate UI refactor or masks a genuine regression.

Self-healing also has limits for highly dynamic interfaces: canvas-rendered elements, fully programmatically-generated ids, or elements that only appear after complex multi-step interactions may not provide enough DOM context for reliable selector identification. In these cases, the step will fail normally and require manual attention.

Enabling Auto-Retry in TestInspector

The auto_retry flag is set per test. Navigate to the test settings in the TestInspector dashboard, enable Auto-Retry, and save. The setting applies to all steps within that test. Selective enablement — turning auto_retry on for UI interaction steps prone to selector drift while leaving it off for assertion steps where unexpected changes likely indicate real bugs — is a common pattern that keeps healing focused on maintenance rather than masking real failures.

When reviewing run reports, the self-healed status on a step provides two signals: the test ran successfully without manual intervention, and a UI element changed. Teams that review self-healed steps periodically catch genuine application changes that may warrant updated test assertions or documentation. For broader test strategy guidance, see Astaqc's AI in software testing guide, manual testing services, and performance testing services.

Frequently Asked Questions

Does self-healing slow down test execution for every run?

No. Self-healing is an exception path. It only activates when a step fails. Successful steps run at normal speed without consulting the AI. Once a corrected selector is persisted, future runs use it directly unless that selector also breaks.

Are corrected selectors automatically applied or do they require approval?

In TestInspector's current implementation, corrected selectors are applied automatically when a retry succeeds. Engineers can review all self-healed steps in the run report, which records both the original and replacement selector, making it straightforward to audit or revert corrections manually.

Does auto_retry apply to assertion steps or only interaction steps?

The auto_retry flag applies at the test level and affects all steps. For assertion steps that check expected text or element state, enabling self-healing carries some risk of masking real regressions if the DOM change also changed user-visible behavior. A common practice is to set optional: true on assertion steps that are known to be UI-sensitive, and review self-healed assertions carefully in run reports.

How does TestInspector handle steps that use XPath rather than CSS selectors?

The self-healing module works with both CSS selector and XPath targets. The AI receives the step's original target format along with DOM context and returns alternative selectors in whichever format is most stable for the identified element.

Can I see the history of selector corrections across runs?

Each run report records the self-healed steps including the original selector, the corrected selector, and the timestamp. This history is accessible through the suite history view in TestInspector. For teams managing large suites, reviewing self-heal frequency per step identifies structurally fragile areas of the application under test. See Astaqc's QA team service for support with test architecture decisions.

Is self-healing available for all 36 step commands?

Self-healing applies to any step that references a DOM element via selector — click, assign, assertText, assertElementPresent, mouseOver, extract, and similar commands. Steps that do not use selectors (open URL, pause, eval, HTTP request steps) do not trigger self-healing when they fail because their failures are not selector-related.