AI Self-Healing Tests
Learn how ContextQA self-healing detects web element drift, applies or suggests reliable locator repairs, persists healed references, and preserves genuine failures.
Self-healing is ContextQA's AI capability that automatically detects and repairs broken test steps when the application UI changes. Instead of triggering a test failure every time a button is renamed or an element is moved in the DOM, the self-healing agent finds the correct element on the current page and updates the step's element reference — allowing execution to continue without human intervention. This dramatically reduces test maintenance overhead as applications evolve.
Quick answer
ContextQA self-healing handles routine web element-location drift during test execution. When the expected element cannot be found, the platform analyzes the current page, ranks semantically equivalent candidates, and either applies a sufficiently reliable repair or records a suggestion for review. It does not correct failed assertions, server errors, deleted workflows, or other genuine product failures.
Interactive demo: self-healing and conditional validation
Explore how ContextQA responds when a web element changes while the business expectation remains the same. The walkthrough also shows how conditional validation keeps alternate application states explicit instead of masking a product failure.
What to notice
Self-healing is limited to recoverable element-location drift; it does not rewrite the intended assertion.
Conditional validation models an approved alternate state and keeps both branches reviewable.
Execution evidence shows whether the original step, a healed element, or a conditional branch produced the outcome.
Prerequisites
You have test cases running against a live application.
You understand how test steps reference UI elements (see Test Steps Editor).
Self-healing is enabled by default for all workspaces. No configuration is required to activate it.
How Self-Healing Works
Self-healing activates automatically when a step execution fails to locate an expected element. The process runs within the normal execution pipeline as Stage 8 (see Platform Architecture).
The Healing Process
1. Element not found The step execution agent attempts to locate the element described by the step (e.g., "Click the Sign In button"). The element is not found at its previously known location in the DOM.
2. Page analysis The self-healing agent takes a full DOM snapshot and a screenshot of the current page state. It has access to the complete HTML structure, computed element attributes, and visual layout.
3. Semantic search The agent uses the step description ("Click the Sign In button") as a semantic query. It searches the current page for elements that are functionally equivalent to the one described, considering:
Visible text content
ARIA labels and roles
Input type and surrounding form labels
Position and visual context relative to other known elements
Historical element history (attributes recorded from previous successful runs)
4. Confidence scoring Each candidate element is scored against the step's intent and the historical element history. The confidence level reflects how likely the candidate is to be the same logical element the step originally targeted.
5. Auto-heal or flag
If the top candidate meets the confidence threshold: the step is automatically healed. The step's element reference is updated to the new locator, the step is re-executed against the healed element, and execution continues.
If the top candidate does not meet the confidence threshold: the step is marked as failed. The healing suggestion (the best candidate found and its confidence level) is recorded for manual review.
6. Persistent update When auto-healing succeeds, the updated element reference is saved to the test case definition. Future executions of the same test case start with the healed locator, so the same step does not need to be healed again.
What Triggers Self-Healing
Self-healing handles the routine UI drift that occurs as applications are maintained and redesigned.
Button text change
"Sign In" → "Log In"
Yes
Input placeholder change
"Enter email" → "Your email address"
Yes
CSS class rename
.btn-primary → .button-primary
Yes
ID attribute change
#submit-btn → #submitButton
Yes
data-testid rename
data-testid="login" → data-testid="signin-btn"
Yes
Element moved within DOM
Button relocated to different container
Yes (if same page)
Design system migration
Bootstrap → Tailwind CSS class changes
Yes
ARIA label update
Accessibility improvement renames aria-label
Yes
What Does NOT Trigger Self-Healing
Self-healing is designed to repair locator drift, not to handle genuine functional failures.
Element completely removed
Sign In button deleted, page now shows a different flow
No — genuine failure
Entire page replaced
Login page replaced by OAuth redirect
No — test needs rewriting
New multi-step flow introduced
Sign In now requires a CAPTCHA that wasn't there before
No — test needs updating
Data validation failure
Form submission fails with a server error
No — application bug
Low-confidence candidate only
Best match is only 65% confident
No — flagged for manual review
For changes in the bottom half of the table, the test failure is intentional and correct — it signals that the application has changed in a way that requires human review.
Viewing Healed Steps in the Execution Report
After an execution that included self-healing events, the execution report highlights healed steps with a distinct visual indicator.
Navigate to Plans → Test Plans → Run Results (or open the test plan execution results).
Click View Detailed Report on the relevant execution.
In the step-by-step results panel, steps that were auto-healed display a Auto-Healed badge.
Click on a healed step to expand its detail view. The detail panel shows:
Original locator — the element reference used before healing
Healed locator — the new element reference applied after healing
Confidence level — the AI's confidence that the healed element is the correct one (always at or above the threshold for auto-healed steps)
Screenshot before healing — the page state when the element was not found
Screenshot after healing — the page state after the healed step was re-executed
Healing Suggestions for Manual Review
When the confidence level for the best candidate does not meet the threshold, the self-healing agent records a healing suggestion rather than auto-healing. These suggestions appear in a dedicated panel in the execution report.
In the execution report, click the Healing Suggestions tab.
Each suggestion shows:
The step that failed
The proposed replacement element
The confidence level
A screenshot with the proposed element highlighted
Review each suggestion:
If the proposed element is correct, click Apply Healing to update the test step.
If the proposed element is wrong, click Dismiss and manually edit the test step.
Manual Healing Approval via MCP
If you are using the ContextQA MCP server with an AI coding assistant, you can retrieve and approve healing suggestions programmatically.
Retrieving Suggestions
Approving a Healing
Approving a healing via MCP has the same effect as clicking Apply Healing in the portal: the test step's element reference is updated persistently.
Programmatic Healing Review Workflow
A common pattern when using ContextQA with CI/CD pipelines is to check for healing suggestions after every run and automatically approve high-confidence ones while routing low-confidence ones to a human review queue:
Configuring Self-Healing
Self-healing is enabled by default at the workspace level.
Disabling self-healing for a specific test case
Open the test case.
Click the Test Case tab in the side panel.
Toggle Self-Healing to Off.
Save the test case.
Disabling self-healing for a test case means that if any element is not found, the step fails immediately without attempting to find an alternative. Use this for tests where you explicitly want failures when any UI element changes — for example, tests that validate a specific element's exact DOM structure as part of a design compliance check.
Tips & Best Practices
Do not disable self-healing globally. Self-healing saves significant maintenance time for typical application evolution. Only disable it for specific test cases where strict element matching is a test requirement.
Review healed steps periodically. Even when self-healing is correct, it is good practice to review healed steps after a sprint or release. Accumulating healed steps without review can obscure significant UI refactoring that warrants a deliberate test update.
Use descriptive, semantically rich step descriptions. Self-healing works by matching the step description's intent to the current page. The more specific your step descriptions ("Click the blue 'Add to Cart' button in the product card", not "click the button"), the more accurately the AI can locate the intended element even after changes.
Combine self-healing with Knowledge Base entries. If your application has a recurring UI pattern that consistently confuses the self-healing agent (e.g., multiple similarly-named buttons), add a Knowledge Base entry explaining which button to choose in which context.
Alert on low-confidence suggestions in CI/CD. If your CI/CD pipeline runs tests automatically, configure alerts (via Slack or Jira integration) when healing suggestions with low confidence are generated. These signals indicate UI changes significant enough to need human attention.
Validate self-healing before enabling broad use
Use a controlled experiment to prove that locator recovery preserves intent without hiding product failures:
Run a stable test and retain its result and assertion evidence.
Change only a non-semantic locator detail in a disposable environment—for example, a generated class or DOM position—while preserving the accessible control and behavior.
Run the unchanged test. Verify the healed step targets the intended control and the business assertion still passes.
Introduce a real behavior defect, such as preventing the save or showing the wrong total, without changing the test.
Run again. The intended assertion must fail; healing must not convert the defect into a pass.
Review the proposed before/after reference, result IDs, screenshots, and reviewer decision before allowing the change to persist.
Target identity
The healed control has the same user-visible purpose
Assertion integrity
No expected outcome was weakened or removed
Negative control
A seeded behavior defect still fails
Evidence
Original, healed, and failed-control runs are retained
Approval
A named reviewer accepted or rejected the repair
If the target is ambiguous, the flow changed materially, or the assertion no longer reflects the requirement, update the test deliberately instead of calling the change self-healing.
Troubleshooting
Self-healing is activating on elements that should not be changing Check if your application is generating dynamic id or class attributes (e.g., id="btn-1742831600"). Elements with non-deterministic attributes will appear to change on every page load. Add a Knowledge Base entry to instruct the AI to use stable attributes (ARIA labels, element text, visible label) for these elements instead.
Self-healing is consistently failing for the same step This usually indicates one of two things: (1) the element has genuinely changed enough that the AI cannot confidently identify it, or (2) the step description is too vague for the AI to have a clear search target. Edit the step description to be more specific, and manually update the element reference by editing the step.
The healed locator was applied incorrectly — it healed to the wrong element In very rare cases, a high-confidence healing can select the wrong element (for example, two buttons with nearly identical text on the same page). If you notice an incorrect healing in the report, apply the correct element reference manually via the step editor and file feedback with ContextQA support so the edge case can be addressed in the AI model.
Healing suggestions are not appearing in the Healing Suggestions tab The Healing Suggestions tab only appears in executions where at least one step failed the element lookup and a suggestion was generated. If all steps either passed or failed for non-locator reasons (network errors, verification failures), the tab will not appear.
Related Pages
Frequently asked questions
Last updated
Was this helpful?