momentic.config.yaml

momentic.config.yaml lives in your project root and defines a project. One file covers both web and mobile. Paths and globs are relative to the file’s location, or absolute.

Configuration sources

Momentic resolves configuration from these sources, highest precedence first:

CLI flags (e.g. --local-avd-id, --local-apk-path)
Environment variables, including MOMENTIC_API_KEY and any variable interpolated into momentic.config.yaml
momentic.config.yaml (this file). Includes the ai.classification toggle for failure classification.
Organization AI settings. Failure categories and auto-heal behavior are configured in the Momentic dashboard and applied when the CLI is authenticated. These remain dashboard-managed and cannot be set in this file.
CLI defaults

Example

momentic.config.yaml

# Project identity and test discovery
name: my-project
include:
  - "**/*.test.yaml"
  - "**/*.module.yaml"
exclude:
  - "out/**/*"

# Run behavior
retries: 2
parallel: 4
recordVideo: on-fail

# One entry per environment, each with its own baseUrl and variables
environments:
  - name: dev
    baseUrl: https://dev.example.com
    envVariables:
      USERNAME: devUser
      PASSWORD: ${DEV_PASSWORD}
  - name: production
    baseUrl: https://www.example.com
    envVariables:
      USERNAME: prodUser
      PASSWORD: ${PROD_PASSWORD}

# Browser defaults applied to every browser-based test
browser:
  smartWaitingTimeoutMs: 5000
  pageLoadTimeoutMs: 8000

# AI agent versions and per-agent behavior
ai:
  classification: true
  useMemory: true
  failureRecovery: true
  agentConfig:
    locator: v4
    assertion: v4
    visual-assertion: v4
    text-extraction: v3

# Mobile emulator settings (remote-hosted)
emulator:
  region: us-west1

Reference

Global options

Project name, file globs, retries, parallelism, video recording, Git branch settings.

Environments

environments[]: name, base URL, env variables, per-env proxy.

Environment variables

How Momentic resolves variables at runtime and the reserved variables available in every test.

Browser

browser.*: defaults for browser type, timezone, timeouts, locator behavior, AI context filtering.

AI

ai.*: per-agent versions, memory, and failure recovery.

Mobile

emulator.*: region and runtime options for remote-hosted mobile emulators.

Advanced

advanced.*: Faker seed, per-environment cache isolation.

Workspaces

Group multiple projects under one repo.

Test file globs

Glob syntax for include / exclude.

Global options

string

Project name, displayed in reports and the dashboard.

momentic.config.yaml

name: my-project-name

string[]

Globs for test and module files to include. Matching files are picked up automatically when starting the Momentic Local App or running tests.

momentic.config.yaml

include:
  - "**/*.test.yaml"
  - "**/*.module.yaml"

string[]

Globs for files to exclude. node_modules, .git, and .venv are always excluded.

momentic.config.yaml

exclude:
  - "out/**/*"

number

Default number of retries per test on failure. Overrides per-test retries.

momentic.config.yaml

retries: 2

number | "auto"

Default for momentic run: 1. Tests to run in parallel.For momentic run, "auto" sizes workers from the host’s CPU cores. When the project’s browser.remoteBrowser flag is enabled, workers scale to cores * 4 - 2 (remote browsers are IO-bound); otherwise workers cap at cores (local browsers are CPU-bound).For mobile projects (momentic-mobile), pass AUTO (CLI flag only, not in momentic.config.yaml) to run as many tests in parallel as the current shard contains. Combine with --shard-index / --shard-count so each shard saturates its capacity.In momentic.config.yaml, only the lowercase form auto is valid.

momentic.config.yaml

parallel: 4

boolean | "on-fail"

Record video for test runs. Default: on-fail.

true: record every run.
false: never record.
on-fail: record every run but keep video only for failures.

Browser recording requires ffmpeg, which is installed automatically by momentic install-browsers; mobile recording does not.

momentic.config.yaml

recordVideo: on-fail

string

Directory Momentic writes golden files to for Visual diff.

momentic.config.yaml

goldenFileDir: golden/visual-diff

string

Default directory for reporter output.

momentic.config.yaml

reporterDir: reports

object

Configuration for network reporters. Currently supports newrelic; see Push run results to New Relic.

momentic.config.yaml

reporting:
  newrelic:
    region: US
    accountId: "1234567"
    licenseKey: ${NEW_RELIC_LICENSE_KEY}
    attributes:
      service: checkout
      team: payments

string

Main branch of the repo. When running tests on a new branch, Momentic seeds cache entries from the nearest commit on this branch. In non-CI environments, the main branch is also excluded from cache saving. See cache saving eligibility.

momentic.config.yaml

gitMainBranch: main

string[]

Branches considered ineligible for cache saving in non-CI environments. Prevents accidental cache overwriting on shared branches. See cache saving eligibility.

momentic.config.yaml

gitProtectedBranches:
  - staging

string

Relative path from the project root to use as the Repository root in the Momentic Local App. Display-only. Does not affect test execution or file resolution.

momentic.config.yaml

displayRoot: src/tests

​Configuration sources

​Example

​Reference

Global options

Environments

Environment variables

Browser

AI

Mobile

Advanced

Workspaces

Test file globs

​Global options

Configuration sources

Example

Reference

Global options