> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/enterprise-application-testing/web-testing/self-healing.md).

# AI Self-Healing Tests

Configure ContextQA healing approvals, review proposed test repairs, preserve assertions, and verify the repaired test before accepting release evidence.

> **Documentation owner:** [Deep Barot](https://contextqa.com/academy/) · **Last updated:** November 11, 2026

## Quick answer

ContextQA self-healing helps recover test steps when the intended UI element changes. Review **Auto approve with auto heal** at organization level and its test-case override before deciding whether proposed changes may be accepted automatically. A recovered execution and an approved persistent test change are separate decisions. Inspect the original failure, proposed change, and rerun evidence.

## Key takeaways

* Preserve the business assertion when repairing a locator or step.
* Choose organization defaults and explicit case overrides deliberately.
* Approve repairs based on evidence, then rerun the same intended journey.

## Why use self-healing?

A renamed label or changed locator can break automation while the business flow still works. Healing can reduce this maintenance, but it must not redefine a successful outcome. A missing feature, incorrect total, permission violation, or server error still needs investigation.

## Configure automatic approval

1. Open **Settings → Organization → Test Execution**.
2. Review **Auto approve with auto heal**. Enable it only when the organization accepts automatic approval for the relevant tests.
3. Save the setting if you intend to change the policy.
4. Open a test case's settings and review its auto-approval override: **True**, **False**, or **Organization setting**.
5. Use the inherited organization setting for consistent defaults and an explicit override for cases requiring a different review policy.
6. Run a controlled case and inspect whether the resulting change and approval match that policy.

![Organization test execution controls including automatic healing approval and auto-fix](https://4255556216-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKlyaXxb76z3Dn47TrZkU%2Fuploads%2Fgit-blob-7cf823da170eece75575c31044b1afd07e0b4199%2Forganization-healing-and-autofix.jpg?alt=media)

The screenshot shows one workspace's settings, not recommended defaults for every organization. **Enable Auto-fix** and its rerun count govern a related recovery workflow; they do not replace the healing approval decision.

## Review a proposed repair

1. Open the failed execution and the affected step's analysis or healing proposal.
2. Compare the original action and target with the proposed replacement.
3. Inspect the screenshot and surrounding application state. Confirm the intended role, record, and business action are unchanged.
4. Use **Accept** for a correct proposal or **Modify & Accept** when the proposal needs an explicit correction.
5. Confirm the approval result before leaving the panel. Already-approved proposals disable repeated approval actions and retain approver information.
6. Rerun the case against the intended build. Preserve the original failed result and the new result.

Do not treat a displayed confidence score as a universal approval policy. This guide does not prescribe fixed 90% or 70% thresholds; the current approval controls and recorded result determine what happened.

## Keep genuine failures visible

| Observation                                     | Review decision                                          |
| ----------------------------------------------- | -------------------------------------------------------- |
| Equivalent control moved or changed attributes  | Consider the proposed locator repair                     |
| Several controls could match                    | Clarify the target and review manually                   |
| Expected amount, status, or permission is wrong | Investigate the product behavior; preserve the assertion |
| Login or environment is unavailable             | Repair the prerequisite or environment before retesting  |
| Business flow intentionally changed             | Update the requirement and test deliberately             |

## Validate the policy with a controlled test

Run a stable case, change only a locator detail in a disposable test environment, and run again. Confirm that recovery selects the same logical control. Then introduce a behavior defect while keeping the assertion: the test must still fail. Retain both results before broadening automatic approval.

## Frequently asked questions

### Does a passing recovered run mean the original test passed?

No. Preserve the initial result, recovery attempt, approval, and final result separately. See [execution journeys and auto-fix](https://learning.contextqa.com/enterprise-application-testing/reporting/execution-journey-and-auto-fix.md).

### Does every proposed change persist immediately?

Do not assume that. Inspect the configured approval policy, proposal status, and saved test definition. Verify persistence with a subsequent run.

### Can I review healing through an AI coding assistant?

Use the supported healing tools exposed by your connected [MCP server](https://learning.contextqa.com/contextqa-mcp/overview/tool-reference/execution-and-results.md), inspect their current schemas, and review the proposed mutation before approving it. Keep credentials and session material out of the handoff.

### What if the repair selects the wrong control?

Reject or correct the proposal, make the step intent more precise, and rerun it. Check similar cases that share the same prerequisite or step group before treating the release as ready.

## Related guides

[Failure analysis](https://learning.contextqa.com/enterprise-application-testing/reporting/failure-analysis.md) · [Test steps editor](https://learning.contextqa.com/enterprise-application-testing/web-testing/test-steps-editor.md) · [Release readiness](https://learning.contextqa.com/enterprise-application-testing/ship/release-readiness.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://learning.contextqa.com/enterprise-application-testing/web-testing/self-healing.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
