Skip to main content

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.

Momentic has two kinds of auto-healing, and they run at different times:
  • In-run auto-healing (this page) keeps a single run green 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 entries when the run is eligible to save cache.
  • Post-run heal agent (momentic ai heal) 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: it keeps the current run green without touching your test file, and is saved for reuse only when the run is eligible to save cache.
Auto-heal diff

​
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 decides what happens to the proposed changes:
BehaviorWhat it does
Pull requestOpens a pull request with the proposed test changes.
Draft pull requestOpens a draft pull request with the proposed changes.
Direct commitCommits and pushes the changes directly to the checked-out branch. Runs on main still open a pull request.
PatchPrints a git patch to stdout that you can apply with git apply.
Leave on diskWrites 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 decides how the run ends:
BehaviorWhat it does
WarnReports that healing failed and surfaces the agent’s reasoning. Exits zero.
FailKeeps 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
  • Runs started with --disable-cache
  • Never-cached steps, 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, 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, the resolved target is written to the 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 heal agent.

​
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 for details on the format and location Momentic respects.