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

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:

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.

apps/shop/momentic.config.yaml

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:

apps/shop/tests/checkout.test.yaml

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:

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.

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:

.github/workflows/branch-tests.yml

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.

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:

.github/workflows/regression.yml

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

Overview

Migrate to Momentic

Frameworks

Use cases

Triage

AI actions

Authentication

Page interactions

Test data & variants

Visual testing

Reporting

Upgrading

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

Where the tests live

The test

Run the branch’s tests locally

Run the branch’s tests in CI

Run the whole suite on main

Notes

​Where the tests live

​The test

​Run the branch’s tests locally

​Run the branch’s tests in CI

​Run the whole suite on main

​Notes

​Related

Where the tests live

The test

Run the branch’s tests locally

Run the branch’s tests in CI

Run the whole suite on main

Notes

Related