AI Self-Healing

How ContextQA's self-healing AI detects broken test steps caused by UI changes and automatically repairs them, including how to view healed steps, configure thresholds, and approve suggested healings

Who is this for? Testers and SDETs who want to reduce test maintenance overhead — letting AI automatically repair broken locators when the application UI changes.

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.

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.

Change Type	Example	Healed?
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.

Change Type	Example	Healed?
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.

1. Navigate to Test Development → Execution History (or open the test plan execution results).

2. Click View Detailed Report on the relevant execution.

3. In the step-by-step results panel, steps that were auto-healed display a Auto-Healed badge.

1. 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.

1. In the execution report, click the Healing Suggestions tab.

2. Each suggestion shows:

   • The step that failed

   • The proposed replacement element

   • The confidence level

   • A screenshot with the proposed element highlighted

1. 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

# Get all pending healing suggestions for an execution
suggestions = get_auto_healing_suggestions(execution_id=12345)

# Returns a list of suggestions:
# [
#   {
#     "healing_id": "heal_abc123",
#     "step_id": 456,
#     "step_description": "Click the Sign In button",
#     "original_locator": "#sign-in",
#     "proposed_locator": "#log-in-button",
#     "confidence": 0.87,
#     "screenshot_url": "https://..."
#   },
#   ...
# ]

Approving a Healing

# Apply a specific healing suggestion to the test case
approve_auto_healing(
    healing_id="heal_abc123",
    execution_id=12345
)

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:

# After test suite execution completes
result = get_execution_status(execution_id=suite_execution_id)

if result["has_healing_suggestions"]:
    suggestions = get_auto_healing_suggestions(execution_id=suite_execution_id)
    for s in suggestions:
        if s["confidence"] >= 0.85:
            # High enough confidence — auto-approve
            approve_auto_healing(
                healing_id=s["healing_id"],
                execution_id=suite_execution_id
            )
        else:
            # Route to human review via Slack or Jira
            create_defect_ticket(
                title=f"Manual healing review needed: {s['step_description']}",
                description=f"Confidence: {s['confidence']}, Proposed: {s['proposed_locator']}"
            )

---

Configuring Self-Healing

Self-healing is enabled by default at the workspace level.

Disabling self-healing for a specific test case:

1. Open the test case.

2. Click the Settings tab.

3. Toggle Self-Healing to Off.

4. 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.

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

• Platform Architecture

• Test Steps Editor

• Running Tests

• MCP Server

• Core Concepts

70% less manual test maintenance with AI self-healing. Book a Demo → — See ContextQA create and maintain tests for your web application.