> ## Documentation Index
> Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-healing

> Momentic keeps tests passing by re-resolving locators and waiting for page stability before every action.

Momentic has two kinds of auto-healing, and they run at different times:

* **In-run auto-healing** (this page) keeps a single run passing while it
  executes. It re-resolves locators when the UI changes and waits for the page
  to stabilize. The fixes are ephemeral: they never edit your test files, and
  they persist only as [step-cache](/reliability/step-cache) entries when the
  run is eligible to save cache.
* **Post-run triage agent** ([`momentic ai triage`](/guides/auto-heal/in-ci))
  runs after a failed run, permanently rewrites the failing tests, and opens a
  pull request (or emits a patch) with the fix.

The rest of this page covers in-run auto-healing, which is two behaviors working
together: **locator resolution** keeps element targeting accurate when your UI
changes, and **smart waiting** removes the need for explicit **Wait** steps.

## Locator resolution

On each step, Momentic checks whether the originally targeted element still
exists on the page. If it doesn't, the agent searches for a replacement that
matches the original natural-language description.

The re-resolved target is [ephemeral by default](#persisted-vs-ephemeral-heals):
it keeps the current run passing without touching your test file, and is saved
for reuse only when the run is eligible to save cache.

<Frame caption="Auto-heal resolution in the run viewer">
  <img src="https://mintcdn.com/momentic-docs/74ZfuO1WWXQIVJ6H/images/reliability/auto-heal-diff.png?fit=max&auto=format&n=74ZfuO1WWXQIVJ6H&q=85&s=501b6ba15a0556d46433ea741d96ba85" alt="Auto-heal diff" className="w-full" width="994" height="1166" data-path="images/reliability/auto-heal-diff.png" />
</Frame>

## Smart waiting

Momentic waits for the page to stabilize before acting. Defaults to 3 seconds
and is configurable per test.

Inputs that influence stability:

* Navigation events
* `load` events
* Page screenshots
* DOM mutations
* Same-origin requests

## After a successful heal

When the healing agent repairs a test, the **On successful heal** behavior in
[Settings > Healing](https://app.momentic.ai/settings/healing) decides what
happens to the proposed changes:

| Behavior               | What it does                                                                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pull request**       | Opens a pull request with the proposed test changes.                                                                                              |
| **Draft pull request** | Opens a draft pull request with the proposed changes.                                                                                             |
| **Direct commit**      | Commits and pushes the changes directly to the checked-out branch. Runs on `main` or a GitHub-protected branch open a draft pull request instead. |
| **Patch**              | Prints a git patch to stdout that you can apply with `git apply`.                                                                                 |
| **Leave on disk**      | Writes the changes to disk without committing or opening a pull request.                                                                          |

## After a failed heal

When the agent can't repair a test, the **On failed heal** behavior in
[Settings > Healing](https://app.momentic.ai/settings/healing) decides how the
run ends:

| Behavior | What it does                                                                |
| -------- | --------------------------------------------------------------------------- |
| **Warn** | Reports that healing failed and surfaces the agent's reasoning. Exits zero. |
| **Fail** | Keeps the run blocking and exits with code 1.                               |

## Persisted vs ephemeral heals

Every in-run heal starts out ephemeral: the agent resolves the target for the
current run only and never edits your test file. Whether that resolution is kept
depends on the run.

**Ephemeral heal.** Used for this run, then discarded, so the next run
re-resolves from scratch. This is what happens whenever the run is not eligible
to save cache:

* Local runs on `main` or a
  [protected branch](/configuration/momentic-config#gitprotectedbranches)
* Runs started with [`--disable-cache`](/reliability/step-cache#disabling-cache)
* [Never-cached steps](/reliability/step-cache#never-cached), such as **AI
  check** or steps with variables that change every run
* Any run that ends up failing (cache is saved only on a pass)
* In-run [failure recovery](/reliability/failure-recovery), which generates
  one-off steps to get past transient issues like cookie banners or race
  conditions

**Persisted heal.** When the run passes and is
[eligible to save cache](/reliability/step-cache#cache-saving-eligibility), the
resolved target is written to the [step cache](/reliability/step-cache) so
future runs replay in milliseconds without an AI call.

Neither kind edits your tests. To turn a fix into a permanent change to the test
itself, use the post-run [triage agent](/guides/auto-heal/in-ci).

## Pull request descriptions

When auto-heal opens a pull request with fixed tests, it uses your repository's
`.github/PULL_REQUEST_TEMPLATE.md` (if present) so the generated description
matches what your team expects. See
[Pull request templates](/integrations/github#pull-request-templates) for
details on the format and location Momentic respects.