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

Take an unresolved flaky test out of the run so it cannot block CI, with the option to keep running it for data.
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

If the target is correct but a temporary condition still blocks the flow, the next layer is 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:
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. Frequent recovery is a flakiness signal. Use 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. See After a successful heal.
Run tests into a results directory, then triage failures from that directory:
Classification behavior is configured in ai.classification. Category actions and project-specific classification guidance live in Classification settings. 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. 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.

​
After a successful heal

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.
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 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 (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 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, like every pull-request mode.
  • When routing cannot complete — attribution fails, GitHub rejects a call, 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 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 takes a flaky test out of the run so its failures cannot fail the build; quarantined tests are skipped by default. Pass --skip-quarantined false to keep running them without affecting pipeline status — 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 recovery usage. See the momentic quarantine reference for commands and rule options. Quarantine should be temporary. Continue with debugging flaky tests, then remove the quarantine when the test is stable.