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

# Regression testing

> Rerun your existing tests on every change to catch regressions in CI.

Regression testing reruns your existing test suite on every change so you catch
when a flow that used to work breaks. Use it once you have flows worth keeping:
run the whole test suite in CI on each commit or pull request and treat a
failure as a release blocker.

Because tests are defined in natural language, a cosmetic UI change does not
fail a test that still works, so failures point at real regressions.

```bash theme={null}
npx momentic run --upload-results
```

## When to use it

* You ship often enough that re-verifying every flow by hand before each release
  is not realistic.
* A change in one area can break something far from the edit: a shared
  component, an API contract, a dependency bump.
* You already spend engineer time on manual regression passes, or you learn
  about regressions from users instead of CI.

It is less useful before the product has flows stable enough to keep. If your
core flows still change weekly, start with a few
[smoke tests](/docs/guides/use-cases/smoke-testing) and grow coverage as flows
settle.

## What to cover first

Prioritize by blast radius, not by what is easiest to automate. Partial coverage
is useful from the start.

* Revenue and retention paths first: sign-up, checkout, the primary action your
  product exists to do.
* Flows that have regressed before.
* Flows that exercise shared code many features depend on.

Add breadth over time, and let the [explore agent](/docs/coding-agents/explore)
propose tests for journeys you have not covered yet.

## How it works

* Author tests once as natural-language steps. See the [web](/docs/quickstart/web),
  [iOS](/docs/quickstart/ios), and [Android](/docs/quickstart/android) quickstarts.
* [Auto-heal](/docs/reliability/auto-maintenance#locator-auto-healing) repairs a test
  mid-run when the UI changed, so routine UI edits do not turn into failing
  builds to triage.
* Reuse shared setup (login, seeding) with [modules](/docs/core-concepts/modules) so
  one change updates every test that depends on it.

## Run it in CI

<Steps>
  <Step title="Build a baseline test suite">
    Cover your highest-priority flows and confirm they pass locally. Start from
    the [web](/docs/quickstart/web), [iOS](/docs/quickstart/ios), or
    [Android](/docs/quickstart/android) quickstart.
  </Step>

  <Step title="Run the tests on every change">
    Add Momentic to your pipeline so the test suite runs on each commit or pull
    request. See [GitHub Actions](/docs/running-tests/ci/github-actions), [GitLab
    CI](/docs/running-tests/ci/gitlab-ci), or [custom
    setups](/docs/running-tests/ci/custom-setups) for other providers.
  </Step>

  <Step title="Triage failures">
    When a run fails, read the trace and screenshots in
    [results](/docs/running-tests/results). Isolate unstable tests with
    [quarantine](/docs/reliability/auto-maintenance#quarantine) so one flaky test
    does not block the rest.
  </Step>
</Steps>

## Keeping the test suite healthy

A regression test suite earns its place only if the team trusts a failure.
Budget for upkeep, not just authoring:

* Quarantine flaky tests instead of disabling them. Quarantined tests still run
  but do not fail the build, so you keep the signal while you fix the test, then
  promote it back out of [quarantine](/docs/reliability/auto-maintenance#quarantine).
* Keep runs fast as the test suite grows by sharding across CI machines with
  `--shard-count` and `--shard-index` rather than dropping coverage.
* Give flows clear ownership so a failure is triaged by someone with context,
  while the change that caused it is still fresh.

## Notes

* A failed run exits non-zero so CI blocks the merge. Quarantined tests are the
  exception and do not affect the exit code by default.

## Related

<CardGroup cols={2}>
  <Card title="Explore agent" icon="compass" href="/docs/coding-agents/explore">
    Find journeys a diff changed and author tests for the gaps.
  </Card>

  <Card title="Auto-healing" icon="wrench" href="/docs/reliability/auto-maintenance#locator-auto-healing">
    Repair tests automatically when the UI changes.
  </Card>

  <Card title="Run in CI/CD" icon="play" href="/docs/running-tests/ci/github-actions">
    Run the tests on every commit and pull request.
  </Card>

  <Card title="Quarantine" icon="box-archive" href="/docs/reliability/auto-maintenance#quarantine">
    Isolate unstable tests without blocking the rest of the test suite.
  </Card>
</CardGroup>