> ## 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.
# AI test maintenance
> Use AI to escalate from in-run locator fixes to transient recovery, permanent healing, and quarantine.
Momentic starts with the least invasive response and escalates only when needed.
Re-resolve a stale target or wait for the page to settle. The current step
continues without editing the test.
Failure recovery generates temporary steps to clear an obstruction, then
retries the failed step. The test still does not change.
Classification and triage explain the failure, decide whether it is
healable, and permanently repair the test when possible.
Keep an unresolved flaky test running and collecting data without letting it
block CI.
Not every failure reaches every layer. Real product regressions and
infrastructure failures remain failures; quarantine is containment, not a
repair.
## Locator auto-healing
When a cached target no longer matches the page, the locator agent finds the
element again from the step's description. Smart waiting also waits for
navigation, requests, and page changes to settle before the action runs.
The resolution applies to the current run and never edits the test. After an
eligible successful run, Momentic can save it to the
[step cache](/docs/reliability/step-cache) for fast replay.
If the target is correct but a temporary condition still blocks the flow, the
next layer is [transient recovery](#transient-recovery).
## Transient recovery
Failure recovery is in beta and may change.
During eligible CI runs, **failure recovery** can generate temporary steps to
clear a cookie banner, wait out a transition, or handle another transient
obstruction. It then retries the failed preset step. Generated steps apply only
to that run and never edit the test.
Enable it in `momentic.config.yaml`:
```yaml momentic.config.yaml theme={null}
ai:
failureRecovery: true
```
When [in-flow classification](/docs/guides/auto-heal/in-flow-classification) is
enabled, the classifier investigates the failure first. Only failures mapped to
**heal** and judged recoverable trigger a recovery attempt. Without
classification, a built-in recovery planner makes that decision.
Recovery does not run in the editor and stops after three recoveries in one run.
Only failed preset steps are eligible, including preset steps inside modules;
module containers and **AI action** steps are not. It does not hide product
regressions, configuration errors, network outages, 5xx responses, CAPTCHAs, or
browser crashes. See [AI configuration](/docs/configuration/ai#ai-failurerecovery)
for the full reference.
Recovery can also clear a stale
[AI action cache](/docs/reliability/step-cache#ai-action-caches). When a later step
fails because an earlier AI action replayed its cached steps without reaching
the goal, recovery repairs the page for the current run and drops that entry, so
the next run resolves the goal again instead of replaying the same flow.
Frequent recovery is a flakiness signal. Use
[permanent healing](#permanent-healing) to find and fix the cause.
## Permanent healing
Classification and triage form one post-run maintenance loop:
1. **Classify** examines run artifacts, repository changes, prior runs, and any
service logs in the results directory. It assigns a category, reasoning, and
the configured **heal**, **warn**, or **fail** action.
2. **Triage**, when it runs, groups related failures, repairs the affected
tests, and verifies each change. Recovered runs are included when triage can
replace the temporary recovery with a test change.
3. **Deliver** ships each accepted repair according to your
[Triage settings](https://app.momentic.ai/settings/triage). See
[After a successful heal](#after-a-successful-heal).
Run tests into a results directory, then triage failures from that directory:
```bash theme={null}
npx momentic run --output-dir test-results
npx momentic ai triage test-results --yes --timeout-minutes 10
```
Triage can also revise a classification while it works. If live browser evidence
disproves the original diagnosis, the repair attempt carries the corrected
category with it, and the revision only lands if that attempt does. Triage never
overwrites a category you set by hand in the run viewer.
Classification behavior is configured in
[`ai.classification`](/docs/configuration/ai#ai-classification). Category actions and
project-specific classification guidance live in
[Classification settings](https://app.momentic.ai/settings/classification). You
can override an incorrect category from the run viewer.
To keep CI passing while a heal is pending, in-flow classification can return a
successful exit code for failures routed to **heal** or **warn** while failures
routed to **fail** still block the build. See
[Let the verdict gate CI](/docs/guides/auto-heal/in-flow-classification#let-the-verdict-gate-ci).
For CI, make sure triage runs even when the test step fails. Each repair attempt
starts a browser, so if browsers run locally, size the runner for up to one
browser per `--parallel` worker (one by default):
```yaml .github/workflows/momentic.yml theme={null}
- name: Run tests
continue-on-error: true
run: npx momentic run --output-dir test-results
- name: Triage failing tests
if: always()
run: npx momentic ai triage test-results --yes --timeout-minutes 10
```
The complete
[auto-maintenance workflow](https://github.com/momentic-ai/examples/blob/main/.github/workflows/test-ai-heal-demo.yml)
includes authentication, permissions, checkout, and browser setup. See the
[GitHub Actions guide](/docs/running-tests/ci/github-actions) or another
[CI integration](/docs/running-tests/ci/custom-setups) for runner setup. The
[`momentic ai` reference](/docs/cli-reference/momentic/commands/ai#triage) covers
alternative run selectors, queue filters, parallelism, delivery overrides, and
exit codes.
### After a successful heal
The **On successful heal**
[Triage setting](https://app.momentic.ai/settings/triage) controls how an
accepted repair leaves the CI runner. Outside CI, every mode leaves the changes
on disk instead.
* **Pull request** (default): open a pull request with the repairs.
* **Draft pull request**: the same, opened as a draft.
* **Direct commit** (`direct-commit-except-main`): commit and push to the branch
under test. On the main branch or a protected branch it opens a draft pull
request instead of pushing.
* **Patch**: print a git patch to stdout, to apply with `git apply`.
* **Nothing**: leave the changes on disk.
* **Follow triage skill**: let a matching [skill](/docs/ai/skills) in
`.momentic/skills` choose one of the behaviors above per repair, with a pull
request as the fallback.
* **AI routing**: let triage decide where each repair goes based on what caused
the failure. See [AI routing](#ai-routing).
When a heal opens a pull request, two optional toggles in the same settings
control who is added to it: **Assign original commit authors to pull requests**
assigns the original authors of the healed tests as assignees, and **Request
original commit authors as reviewers** requests those same authors as reviewers.
Both draw on the same participants (the source pull request's assignees plus the
commit authors and co-authors that GitHub resolves for the change) and default
to off.
The [`--on-heal-success`](/docs/cli-reference/momentic/commands/ai#triage) flag
overrides the first five modes for one run. **Follow triage skill** and **AI
routing** can only be enabled from the dashboard.
### AI routing
Set [**On successful heal**](https://app.momentic.ai/settings/triage) to **AI
routing** in Triage settings, and triage no longer delivers every repair the
same way. It groups the run's failures into distinct issues, attributes each
one, and picks a delivery per issue:
* **The branch under test caused the failure.** The repair is committed to that
branch. When the run is on the main branch there is no feature branch to
commit to, so it opens a pull request instead.
* **Something else caused it.** Each issue opens its own pull request against
the main branch, assigned to the person the evidence points to. Separate
issues get separate pull requests, so one flaky suite no longer produces one
pull request mixing unrelated repairs.
* **A fix already exists.** When an open or merged pull request already covers
the failure, the notice references it instead of opening a duplicate.
Attribution is evidence-based. An agent reads commit history, the repaired diff,
and the repository's pull requests from the last 14 days. It cites commit SHAs
and GitHub resolves who authored them; the model never supplies a username
directly. Bots and people who cannot merge are filtered out, and the agent can
decline to assign anyone. Set **Default reviewer** in
[Triage settings](https://app.momentic.ai/settings/triage) (a GitHub username or
`org/team`) to give unattributed pull requests a reviewer.
Routed pull requests reuse one branch per issue, keyed on the repaired tests. A
repeat of the same failure updates the existing pull request instead of opening
another.
Requirements and fallbacks:
* Set [`gitMainBranch`](/docs/configuration/momentic-config#gitmainbranch) in
`momentic.config.yaml`. When the main branch cannot be resolved, routing
disables itself for the run and says so in the CLI output.
* Delivery uses the [GitHub integration](/docs/integrations/github), like every
pull-request mode.
* When routing cannot complete (for example, attribution fails, GitHub rejects a
call, or the repair is empty once rebuilt against the main branch), the repair
is delivered on the current branch instead and the reason is logged. A repair
is never withheld because routing failed.
### After a failed heal
The [**On failed heal**](https://app.momentic.ai/settings/triage) Triage setting
controls what happens to tests the agent cannot repair: **warn** (default)
reports the failure and the agent's reasoning, **fail** exits non-zero, and
**quarantine** exits non-zero and quarantines the unfixed tests. The
`--on-heal-fail` flag overrides it for one run.
### Large-scale failure limits
When a run group has **at least 20 failures and at least 50% of its tests
failed**, triage is skipped and the command exits non-zero with the reason: a
whole suite failing that way is one outage, not many bugs worth triaging
separately. Quarantined and recovered runs do not count toward either number,
and naming runs with `--run-id` always triages them. Triage resumes on the next
run.
If a recurring flake cannot yet be repaired, contain it with
[quarantine](#quarantine).
## Quarantine
Quarantine keeps a flaky test running without letting its failures fail the
build. The run remains visible in the dashboard as a quarantined failure, so you
keep the evidence needed to fix it.
```bash theme={null}
npx momentic quarantine add --reason
```
You can also quarantine from the run viewer or the dashboard's **Quarantine**
page. Quarantine rules can act automatically based on pass rate, failure count,
flake rate, or [transient recovery](#transient-recovery) usage. See the
[`momentic quarantine` reference](/docs/cli-reference/momentic/commands/quarantine)
for commands and rule options.
Quarantine should be temporary. Continue with
[debugging flaky tests](/docs/best-practices/debugging-flaky-tests), then remove the
quarantine when the test is stable.
## Related
* [How Momentic works](/docs/get-started/how-momentic-works)
* [What is AI-native testing?](/docs/get-started/ai-native-testing#maintain-automatically)
* [Results and reporting](/docs/running-tests/results)