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 may be 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}

targets:
  desktop-fr:
    labels: [smoke]
    include:
      - "tests/desktop/**/*.test.yaml"
    exclude:
      - "tests/desktop/legacy/**"
    use:
      viewport: "1440,900"
      locale: fr-FR
      userAgent: null

# 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: v5
    assertion: v5
    visual-assertion: v5
    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.

Targets

targets.*: named test subsets with their own viewport, user agent, and locale.

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. Momentic picks up matching files automatically when you start the local editor or run tests.

momentic.config.yaml

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

string[]

Globs for files to exclude. Momentic always excludes node_modules, .git, and .venv.

momentic.config.yaml

exclude:
  - "out/**/*"

number

Default number of retries per test on failure. A per-test retries value overrides this. Default: 1.

momentic.config.yaml

retries: 2

number | "auto"

Number of tests to run in parallel. Default for momentic run: 1.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 for Visual diff golden files.Targets that set use keep their baselines under <goldenFileDir>/targets/<name>/.

momentic.config.yaml

goldenFileDir: golden/visual-diff

string

Directory for local run artifacts and result archives. Defaults to ./test-results. The --output-dir run flag overrides this setting.

momentic.config.yaml

outputDir: test-results

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 local editor. Display-only. Does not affect test execution or file resolution.

momentic.config.yaml

displayRoot: src/tests

CLI test-result hooks

Use hooks.postTest to run a command after each web CLI test finishes its retries and classification. The command receives JSON on stdin.

momentic.config.yaml

hooks:
  postTest:
    command: node --experimental-strip-types scripts/on-test.mts
    timeoutMs: 15000

The command runs from the project directory and inherits the CLI environment. timeoutMs defaults to 15 seconds. Hook failures produce warnings without changing test results or the run exit code. Each invocation receives this JSON envelope on stdin, with result populated using the JSON reporter’s run fields:

{
  "version": 1,
  "event": "test.finished",
  "runGroupId": "group-id",
  "runUrl": "https://app.momentic.ai/runs/run-id",
  "envName": "staging",
  "result": {}
}

runUrl and envName are optional. result excludes parameters and adds failureSection (setup, main, teardown, or none), plus optional classification.confidence and classification.rootCause.

​Configuration sources

​Example

​Reference

Global options

Environments

Targets

Environment variables

Browser

AI

Mobile

Advanced

Workspaces

Test file globs

​Global options

​CLI test-result hooks

Configuration sources

Example

Reference

Global options

CLI test-result hooks