Skip to main content
Momentic starts with the least invasive response and escalates only when needed.
1

Locator auto-healing

Re-resolve a stale target or wait for the page to settle. The current step continues without editing the test.
2

Transient failure recovery

Failure recovery generates temporary steps to clear an obstruction, then retries the failed step. The test still does not change.
3

Permanent healing

Classification and triage explain the failure, decide whether it is healable, and permanently repair the test when possible.
4

Quarantine

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 for fast replay.
Locator auto-healing diff

A locator re-resolved during a run

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
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:
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.
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 MCP server and skills, 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 while 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
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 leave the runner.

​
Patch delivery

The On successful heal Triage setting 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 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 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 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. The repair is committed to that branch, or opened as a pull request when the run is on the main branch.
  • Another cause is responsible. A separate pull request is opened against the main branch and assigned from commit and pull-request evidence.
  • A fix already exists. The existing pull request is referenced 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) 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.

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