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

# AI test selection

> Select the tests most likely to catch regressions from a code change, using your code index and app graph.

AI test selection reads a git diff and runs a focused set of Momentic tests that
covers the changed behavior. Use it in pull request CI when running every test
would take too long.

<Warning>
  This feature is in alpha and may change. [Contact
  us](https://momentic.ai/sales) to join the waitlist.
</Warning>

## Run selected tests

Run it from the root of your git repository:

```bash theme={null}
npx momentic run . --ai-select
```

In supported CI providers, Momentic detects the pull request base ref. Use
`--ai-select-base` when you need to set it explicitly:

```bash theme={null}
npx momentic run . --ai-select --ai-select-base origin/main
```

Test files changed directly in the diff are included. Changes to shared modules
do not force every consuming test to run; selection chooses representative
coverage for the affected behavior.

If Momentic cannot build a safe selection, it runs the full in-scope test set
instead.

## How selection works

Momentic combines three sources of evidence:

1. The git diff identifies the code and behavior that changed.
2. A local code index traces imports and downstream consumers in your
   repository.
3. The [app graph](/docs/ai/app-graph) connects product journeys and UI states to the
   tests that exercised them in real runs.

The app graph provides runtime relationships that static imports cannot express,
such as a backend change surfacing in a browser flow. Selection quality improves
as the graph observes more of your application and test suite.

Build-graph systems such as Bazel are effective at selecting work within a
declared dependency graph. Applying that approach to end-to-end tests requires
teams to manually define and maintain the relationship between build targets,
services, and tests. Code imports also stop at network and product boundaries:
they do not show that a frontend journey depends on an API, queue, data store,
or third-party integration. The app graph adds those observed runtime
relationships without requiring every cross-system dependency to be orchestrated
by hand.

The test budget is a soft cap. Momentic can exceed it when more tests are needed
to cover distinct changed behavior.

```bash theme={null}
npx momentic run . --ai-select --ai-select-budget 10
```

## Guide selection with a prompt

Use `--prompt` to add repository-specific selection guidance that Momentic
cannot infer from the diff, code index, or app graph:

```bash theme={null}
npx momentic run . --ai-select \
  --prompt "Prioritize authentication, cart state, and checkout behavior affected by this change."
```

The prompt augments Momentic's built-in selection instructions. It does not
replace them. Repeat the flag to provide multiple instructions; Momentic appends
the values in command-line order. When you omit `--prompt`, the standard
selection prompt is unchanged.

The standalone command accepts the same flag:

```bash theme={null}
npx momentic ai select . --json \
  --prompt "Treat changes to shared API types as relevant to browser checkout tests."
```

## Use the code index in GitHub Actions

Check out full git history and install the code-index parsers before running the
command:

```yaml theme={null}
steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0
  - run: npx momentic install-codetools
  - run: npx momentic run . --ai-select
```

See the
[complete GitHub Actions example](https://github.com/momentic-ai/examples/blob/main/.github/workflows/test-ai-select.yml)
for setup, code-index caching, standalone selection output, test execution, and
result uploads.

## Preview a selection

Use shadow mode to compare a selection with the full test run before using it to
gate pull requests. Momentic still runs every in-scope test and records which
ones selection would have skipped.

```bash theme={null}
npx momentic run . --ai-select-dry-run
```

To inspect a selection without running tests, use `momentic ai select`:

```bash theme={null}
npx momentic ai select --base origin/main
npx momentic ai select --base origin/main --json > ai-selection.json
```

The JSON result contains `selectedTests` for an explicit handoff and sets
`fallbackToRunAll` when Momentic cannot produce a safe selection.

## Build a dynamic CI matrix

Run standalone selection once in a planning job, convert the selected test paths
into your CI system's matrix format, and pass each shard's paths to
`momentic run`. This lets a small selection use one runner while larger
selections create more shards.

Your planner should handle three outcomes:

1. Run the paths in `selectedTests`.
2. Run every in-scope test when `fallbackToRunAll` is `true`.
3. Skip the execution job for a valid selection with no tests.

The
[dynamic GitHub Actions example](https://github.com/momentic-ai/examples/blob/main/.github/workflows/test-ai-select.yml)
shows the complete workflow. Its
[matrix builder](https://github.com/momentic-ai/examples/blob/main/.github/scripts/build-ai-select-matrix.mjs)
is a small Node.js script you can adapt to another CI provider or shard size.

Use `momentic run --ai-select` when you do not need to customize the handoff; it
performs selection and execution in one command.

## When selection chooses zero tests

A selection that picks no tests is a normal outcome for non-behavioral changes.
The run group still uploads with the selection plan, and the GitHub pull request
comment explains why nothing ran instead of staying silent.

When onboarding onto AI selection, set your CI up so zero-test selections reach
Momentic:

* Always run `momentic results upload`. Do not gate the upload step on the runs
  directory existing or on tests having run; a zero-test run group uploads its
  metadata, which is what powers the pull request comment.
* When you merge sharded results before uploading, pass `--allow-empty` to
  [`momentic results merge`](/docs/cli-reference/momentic/commands/results) so shards
  without runs keep their selection plans in the merged archive.
* `momentic results check` treats a zero-test results directory as clean, so a
  check step needs no special casing.

The
[AI Select example workflows](https://github.com/momentic-ai/examples/blob/main/.github/workflows/test-ai-select.yml)
follow this setup, including a zero-selection reporting job for the dynamic
matrix pattern where an empty selection skips the execution jobs entirely.

## Benchmark

Momentic achieves state-of-the-art results on our custom QAWorkflowSelect
benchmark. It uses real code changes across frontend, backend, CLI, shared
libraries, configuration, and non-behavioral scenarios. Each baseline receives
the same code changes and candidate test files as Momentic, but does not use the
app graph or Momentic's investigation workflow. Cross-functional recall uses the
harder cases that span product boundaries. Metrics are macro averages across
cases.

| Metric                             | Momentic agent (GPT-5.6 Terra, medium) | GPT-5.5 Codex (medium) | Claude Opus 5 (medium) |
| ---------------------------------- | -------------------------------------- | ---------------------- | ---------------------- |
| Average precision                  | **91.8%**                              | 75.7%                  | 82.9%                  |
| Average recall                     | **97.5%**                              | 94.5%                  | 95.1%                  |
| Average cross-functional recall    | **100%**                               | 77.8%                  | 91.7%                  |
| Average F1                         | **90.2%**                              | 75.3%                  | 82.9%                  |
| Perfect cases                      | **85%**                                | 59%                    | 69%                    |
| Average latency                    | **36.1s**                              | 73.2s                  | 38.9s                  |
| Estimated model cost per selection | **\$0.35**                             | \$1.54                 | \$0.96                 |
| Model cost saved with Momentic     | -                                      | **78%**                | **64%**                |

Cost estimates apply the published standard uncached API rates for
[GPT-5.6 Terra](https://developers.openai.com/api/docs/models/gpt-5.6-terra),
[GPT-5.5](https://developers.openai.com/api/docs/models/gpt-5.5), and
[Claude Opus 5](https://platform.claude.com/docs/en/about-claude/models/choosing-a-model)
to the observed input and output token usage. The Momentic estimate prices its
Terra root and Luna investigation tokens at the higher Terra rate. Actual costs
vary with caching, long-context pricing, and provider agreements.

Model output varies between runs, so these results measure the evaluated code
changes rather than guarantee a particular selection. We can share the raw
results and reproduction harness on request.

## Notes

* The command needs enough git history to resolve the base ref. Use
  `fetch-depth: 0` with `actions/checkout`.
* The code index currently analyzes TypeScript and JavaScript imports. Runtime
  app graph evidence can still connect behavior across other boundaries.
* A budget limits selection size, not safety behavior. Selection can fall back
  to running all tests.

## Related

* [What is AI-native testing?](/docs/get-started/ai-native-testing#run-intelligently)