Skip to main content

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.

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:
  1. CLI flags (e.g. --local-avd-id, --local-apk-path)
  2. Environment variables, including MOMENTIC_API_KEY and any variable interpolated into momentic.config.yaml
  3. Organization AI settings. Failure classification and auto-heal are configured in the Momentic dashboard and applied when the CLI is authenticated. They cannot be set in this file.
  4. momentic.config.yaml (this file)
  5. 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:
  defaultBrowserType: Chromium
  smartWaitingTimeoutMs: 5000
  pageLoadTimeoutMs: 8000

# AI agent versions and per-agent behavior
ai:
  useMemory: true
  failureRecovery: true
  agentConfig:
    locator: v3
    assertion: v3
    visual-assertion: v3
    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

​
name
string
Project name, displayed in reports and the dashboard.
momentic.config.yaml
name: my-project-name
​
include
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"
​
exclude
string[]
Globs for files to exclude. node_modules, .git, and .venv are always excluded.
momentic.config.yaml
exclude:
  - "out/**/*"
​
retries
number
Default number of retries per test on failure. Overrides per-test retries.
momentic.config.yaml
retries: 2
​
parallel
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
​
recordVideo
boolean | "on-fail"
Record video for test runs. Default: false for browser, true for mobile.
  • true: record every run.
  • false: never record.
  • on-fail: record every run but keep video only for failures.
Browser recording requires ffmpeg (momentic install-browsers ffmpeg); mobile recording does not.
momentic.config.yaml
recordVideo: on-fail
​
goldenFileDir
string
Directory Momentic writes golden files to for Visual diff.
momentic.config.yaml
goldenFileDir: golden/visual-diff
​
reporterDir
string
Default directory for reporter output.
momentic.config.yaml
reporterDir: reports
​
gitMainBranch
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
​
gitProtectedBranches
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
​
displayRoot
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