AI test maintenance

Momentic starts with the least invasive response and escalates only when needed.

Locator auto-healing re-resolves a stale target or waits 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.
Permanent healing uses classification and triage to explain the failure, decide whether it is healable, and permanently repair the test when possible.
Quarantine keeps 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 for fast replay.

When an unexpected one-off condition blocks the flow, the next layer is failure recovery.

Failure 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:

momentic.config.yaml

ai:
  failureRecovery: true

Give the recovery agent custom guidance with a knowledge base agent rule that targets the failure recovery agent. Use it to say which failures count as recoverable and how to handle them. When 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 for the full reference. Recovery can also clear a stale AI action cache. 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 to find and fix the cause.

Permanent healing

Permanent healing combines AI classification, AI triage, and configurable delivery for repaired and unrepaired tests.

AI classification

Classification explains the evidence behind each category and the configured heal, warn, or fail action. Review the reasoning in the run viewer and override the category when the evidence supports a different diagnosis.

Momentic classification showing Healed and Test authorship labels with reasoning about a transient UI race — Classification identifies a test-authorship race and routes it to healing

Classification behavior is configured in ai.classification. Category actions and project-specific guidance live in Classification settings.

AI triage

Run tests into a results directory, then triage failures from that directory:

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. A failure that was transient or came from outside your test can end with No test change: a successful outcome that keeps the test as it is. Triage delivers a repair only when it changes the test or a module, so a run no longer produces a pull request that only reformats a file. A failing run points at the exact step and hands off to triage:

[2/2] ✘ slow-nav.test.yaml (38s)

  1) slow-nav.test.yaml

    Assertion failure

    An AI check failed for a legitimate reason, such as a missing element, a
    change in the page structure, or an unexpected state (e.g. loading state).

    Failed at:

        5 |   - click: the Submit button
     >  6 |   - assert:
        7 |       that: The error message "Your password is invalid!" is visible

    https://app.momentic.ai/runs/cef3a8f6-8347-406d-b496-ac43c71d627f

  Tests     2 failed | 0 passed (2)
  Duration  67s

  Run momentic ai triage to attempt automatic fixes · https://momentic.ai/docs/reliability/auto-heal

A real triage session reads the failing runs, re-executes candidate fixes in a live browser, then reports each repair with its reasoning:

$ npx momentic ai triage test-results --yes --timeout-minutes 10
Momentic CLI v3.57.0

Healing 2 tests · 1 worker
  source  ./test-results

Triage
[tool call] momentic_get_run(runId: 06189c5d-...)
[tool call] momentic_get_step_result(runId: 06189c5d-..., includeAiInput: true)
[tool call] preview_step(step: --step-type TYPE --description "the Username input" ...)
[tool call] run_step(fromStep: ..., toStep: ...)

  ✓ wrong-assert.test.yaml (1m03s)
    Proposed solution: replace the unsupported greeting assertion with the
    minimum positive-login journey. The main flow now fills the Username input
    with student, fills the Password input with Password123, clicks Submit, and
    retains a single semantic AI assertion confirming a successful login.

  ✓ slow-nav.test.yaml (53s)
    Proposed solution: insert two focused TYPE steps before the existing Submit
    action: fill the Username input with student, then fill the Password input
    with incorrectPassword. The existing assertion was retained unchanged.

  Tests     2 healed (2)

The slow-nav repair was written to disk as:

slow-nav.test.yaml

 steps:
+  - fill:
+      text: student
+      into: the Username input
+  - fill:
+      text: incorrectPassword
+      into: the Password input
   - click: the Submit button
   - assert: The error message "Your password is invalid!" is visible

The test previously submitted an empty form, so the page showed the username-invalid error and the password-invalid assertion could never pass. Triage restored the intended login flow instead of weakening the assertion.

Momentic healed step analysis explaining how triage replaced a transient label check with a durable queue-state check — Triage explains the repaired step and its validation

For an interactive investigation, install the coding agent skills and the MCP server, then invoke momentic-maintain with the run ID. 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. Failures routed to fail still block the build. See 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):

.github/workflows/momentic.yml

- 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 includes authentication, permissions, checkout, and browser setup. See the GitHub Actions guide or another CI integration for runner setup. The momentic ai reference covers alternative run selectors, queue filters, parallelism, delivery overrides, and exit codes.

Heal behavior

Triage settings control how accepted repairs and failed repair attempts are delivered off the runner.

Patch delivery

The On successful heal Triage setting controls how an accepted repair is delivered off 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: open a pull request with the repairs 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 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.

A merged Momentic auto-heal pull request with root cause, fix, validation, and links to the base pull request and results — An auto-heal pull request records the root cause, fix, and validation

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 adds 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 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 to AI routing to choose delivery separately for each repaired issue:

The branch under test caused the failure. Triage commits the repair to that branch, or opens a pull request when the run is on the main branch.
Another cause is responsible. Triage opens a separate pull request against the main branch and assigns it from commit and pull-request evidence.
A fix already exists. Triage references the existing pull request instead of creating a duplicate.

AI routing requires gitMainBranch and the GitHub integration. If routing cannot complete, Momentic delivers the repair on the current branch and logs the reason.

Failed heals

The On failed heal Triage setting controls what happens to tests the agent cannot repair:

warn (default): report the failure and the agent’s reasoning.
fail: exit non-zero.
quarantine: exit non-zero and quarantine the unfixed tests.

The --on-heal-fail flag overrides it for one run.

Circuit breaker

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 indicates a single outage rather than many separate bugs. Quarantined and recovered runs do not count toward either number, and runs named with --run-id are always triaged. Triage resumes on the next run. If a recurring flake cannot yet be repaired, contain it with quarantine.

Quarantine

Quarantine keeps a flaky test running without failing the build. The run remains visible in the dashboard as a quarantined failure, so you keep the evidence needed to fix it. Quarantine a test with a reason:

npx momentic quarantine add <test> --reason <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 failure recovery usage. See the momentic quarantine reference for commands and rule options. Quarantine should be temporary. Continue investigating, then remove the quarantine when the test is stable.

Get started

Building with AI

Author

Run

Learn

Platforms

Integrations

Account

AI test maintenance

Locator auto-healing

Failure recovery

Permanent healing

AI classification

AI triage

Heal behavior

Patch delivery

AI routing

Failed heals

Circuit breaker

Quarantine

​Locator auto-healing

​Failure recovery

​Permanent healing

​AI classification

​AI triage

​Heal behavior

​Patch delivery

​AI routing

​Failed heals

​Circuit breaker

​Quarantine

​Related

Locator auto-healing

Failure recovery

Permanent healing

AI classification

AI triage

Heal behavior

Patch delivery

AI routing

Failed heals

Circuit breaker

Quarantine

Related