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.

After a run, momentic ai heal investigates failed tests and repairs them in place. Based on your organization’s Healing settings, it then opens a pull request with the fix.
This is the post-run repair agent. It is separate from in-run auto-healing (locator resolution and smart waiting), which keeps a single run green without changing your test files.

​
Add the workflow

Add a workflow to run your tests on every pull request and heal whatever fails:
.github/workflows/momentic.yml
name: Momentic

on:
  pull_request:

permissions:
  contents: write
  pull-requests: write

env:
  MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}

jobs:
  test-and-heal:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "npm"

      - run: npm ci
      - run: npx momentic install-browsers chromium

      - name: Run tests
        continue-on-error: true
        run: npx momentic run --output-dir test-results

      - name: Heal failing tests
        if: always()
        run: npx momentic ai heal test-results --yes --timeout-minutes 10

      - name: Upload results
        if: always()
        run: npx momentic results upload test-results
MOMENTIC_API_KEY authenticates the run so the agent picks up your organization’s healing behavior. Create one here and add it as a repository secret. continue-on-error on the test step lets the heal step run even when tests fail, and --timeout-minutes caps total heal time. --yes skips confirmation prompts (on by default when CI is set). The contents: write and pull-requests: write permissions let the Momentic GitHub App open the fix PR, which uses your repository’s pull request template.

​
Choose what a heal produces

Set On successful heal in Settings > Healing to control the outcome:
  • pull-request: open a PR with the fix (default). Best when you want the fix reviewed and merged like any other change.
  • draft-pull-request: open the PR as a draft so a human verifies it before it is marked ready. Requires [email protected]+.
  • patch: print a git apply-ready diff instead of opening a PR. Needs no GitHub App or pull-requests: write, so it is the option for forked-PR runs or when you would rather apply the fix yourself.

​
Gate strictly, or roll out gently

On failed heal decides what happens to tests the agent cannot fix:
  • warn: log the failures and keep the job green. Use this while introducing auto-heal to an existing suite.
  • fail: exit 1 so the check blocks the PR once you trust it.

​
Variations

For large suites, run healing on a schedule or on demand instead of on every PR by swapping the trigger. This mirrors the AI heal demo in momentic-ai/examples: 
on:
  workflow_dispatch:
  schedule:
    - cron: "0 9 * * 1" # every Monday at 09:00 UTC
Narrow the heal queue when you only want to touch some tests: 
# Only quarantined tests, two sessions in parallel
npx momentic ai heal test-results --only-quarantined --parallel 2

# Skip known-flaky tests by name
npx momentic ai heal test-results --exclude "checkout flow" "^Legacy "
See the momentic ai heal reference for every flag. The same run-then-heal pattern works on GitLab CI, CircleCI, Jenkins, and custom setups.