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

> ## Agent Instructions
> The canonical docs host is https://momentic.ai/docs. Append .md to any page URL for clean Markdown. Fetch https://momentic.ai/docs/llms.txt for the page index and https://momentic.ai/docs/llms-full.txt for every page in one file.
> For an unattended setup, run `npx --yes @momentic/wizard@latest -y --platform web` (use `--platform ios` or `--platform android` for mobile). Never run an interactive command in a non-TTY shell.
> You cannot complete the browser sign-in yourself. Read the API key from the MOMENTIC_API_KEY environment variable, or ask the user to create one at https://app.momentic.ai/settings/api-keys and paste it back.
> Momentic's capability summary for agents is at https://momentic.ai/docs/skill.md. Install the skills with `npx momentic skills --yes` (or `npx momentic-mobile skills --yes` for mobile).
> Tests are YAML files in the user's repository. Use only the step names listed at https://momentic.ai/docs/reference/commands.md and the file structure at https://momentic.ai/docs/core-concepts/file-format.md. Do not invent step names, config keys, or CLI flags.
> Web tests run on Chromium, iOS tests on simulators, and Android tests on emulators. Physical devices are not supported.

# Keep end-to-end tests in your repo and run them on a branch

> Store Momentic tests as YAML next to the code, review them in pull requests, and run the branch's tests against its preview deployment before the merge.

Momentic tests are YAML files, so they live in the repository with the code they
cover. A pull request that changes the checkout page can change
`tests/checkout.test.yaml` in the same diff, and CI runs that version of the
test against that branch's preview deployment. Reach for this setup when the
tests must match the branch, not `main`.

## Where the tests live

Put the tests in one directory at the root of the project, or next to the app in
a monorepo:

```text theme={null}
apps/
  shop/
    src/
    tests/
      modules/
        log-in.module.yaml
      checkout.test.yaml
      search.test.yaml
    momentic.config.yaml
```

`momentic.config.yaml` sets the project and the test discovery globs. Run
`npx momentic init` in that directory to create it, or copy one from another
app. In a monorepo with several apps, each app keeps its own
`momentic.config.yaml`, and a `momentic.workspace.yaml` at the repository root
lists them as [workspaces](/docs/configuration/workspace).

```yaml apps/shop/momentic.config.yaml theme={null}
include:
  - "tests/**/*.test.yaml"
  - "tests/**/*.module.yaml"
exclude:
  - "tests/drafts/**"
```

Tests in the repository go through the same review as the code: a reviewer reads
the YAML diff, and the test runs in CI on the branch before anyone merges it.

## The test

A test is a plain YAML file. Keep the shared steps, such as logging in, in a
module that the tests import:

```yaml apps/shop/tests/checkout.test.yaml theme={null}
fileType: momentic/test/v2
id: checkout
url: https://shop.example.com
labels: [checkout]
before:
  - module: ./modules/log-in.module.yaml
steps:
  - click: Add to cart
  - click: Checkout
  - type:
      text: jeff@example.com
      into: the Email field
  - click: Place order
  - assert: An order confirmation is visible
```

The `url` is the default target. CI overrides it per branch with
`--url-override`, so the same file runs against the preview deployment of any
branch.

## Run the branch's tests locally

Before you push, run the tests that your change touches from the app directory:

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

`--ai-select` reads the diff between your branch and `origin/main` and picks the
tests that cover the changed code. Pass a path
(`npx momentic run tests/checkout.test.yaml`) to run one test, and `--start` to
boot the dev server first. See
[momentic run](/docs/cli-reference/momentic/commands/run).

## Run the branch's tests in CI

The workflow checks out the branch, so the tests it runs are the ones in the
pull request, and it waits for the preview deployment before it starts. The
example uses GitHub Actions with a provider that posts a GitHub deployment, such
as Vercel:

```yaml .github/workflows/branch-tests.yml theme={null}
name: Branch tests

on:
  deployment_status:

jobs:
  test:
    if: >-
      github.event.deployment_status.state == 'success' &&
      github.event.deployment.environment == 'Preview'
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults:
      run:
        working-directory: apps/shop
    env:
      MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}
    steps:
      - uses: actions/checkout@v4
        with:
          # AI test selection diffs the branch against main, so it needs history.
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
          cache: "npm"
      - run: npm install
      - run: npx momentic install-browsers chromium

      - name: Run the tests this branch changes
        run: |
          npx momentic run \
            --ai-select \
            --ai-select-base origin/main \
            --url-override "${{ github.event.deployment_status.environment_url }}" \
            --upload-results
```

* The `if` guard runs the job for a ready preview deployment only. `Preview` is
  the environment name Vercel posts; use your provider's name, so a production
  deployment does not start the tests.
* `actions/checkout` puts the branch's YAML in the job, so a test edited in the
  pull request runs in its edited form.
* `--url-override` points every test at the preview URL of the deployment that
  triggered the job.
* `--upload-results` attaches the run to the dashboard, so a failed check links
  to the video, the screenshots, and the trace of the failing step.
* `MOMENTIC_API_KEY` is a repository secret. See
  [GitHub Actions](/docs/running-tests/ci/github-actions#authentication).

A failed run exits non-zero and the check fails. Add the check name to the
branch protection's required status checks to block the merge on it.

## Run the whole suite on main

The pull request job runs a subset. Run every test on each merge to `main`, or
on a schedule, against staging:

```yaml .github/workflows/regression.yml theme={null}
on:
  push:
    branches: [main]
  schedule:
    - cron: "0 6 * * *"
```

Use the same `momentic run` step without `--ai-select`, and add a matrix with
`--shard-index ${{ matrix.shard }} --shard-count 4` to split the suite across
jobs. See [Common CI setups](/docs/guides/common-setups) for the full workflow.

## Notes

* A test that a coding agent writes on the branch runs in the same job. The
  agent commits the YAML, CI runs it, and the structured failure comes back on
  the pull request. See [Momentic MCP server](/docs/coding-agents/mcp-server).
* `--ai-select` needs the full Git history in CI. Without `fetch-depth: 0` the
  diff against `origin/main` is empty and no test is selected.
* Quarantined tests still run but do not fail the check by default. See
  [quarantine](/docs/reliability/auto-maintenance#quarantine).

## Related

* [Gate pull requests on critical flows](/docs/guides/use-cases/gate-pull-requests-on-critical-flows)
* [Common CI setups](/docs/guides/common-setups)
* [AI test selection](/docs/ai/select)
* [GitHub Actions](/docs/running-tests/ci/github-actions)