momentic.config.yaml in your project root defines a project for both
momentic and momentic-mobile. Paths and globs in it are relative to the file
or absolute, except
browser.localChromeExtensionPaths,
which resolves from the directory you launch Momentic in.
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_KEYand any variable interpolated intomomentic.config.yaml momentic.config.yaml(this file). Includes theai.classificationtoggle 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
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.Test file globs
Glob syntax for
include / exclude.Workspaces
A workspace groups multiple Momentic projects under a single repository. Use one when different teams maintain separate test suites but share a repo. Most organizations don’t need a workspace; a singlemomentic.config.yaml at the
repo root is enough.
Add a momentic.workspace.yaml at the root of your repository:
momentic.workspace.yaml
momentic.config.yaml.
Global options
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
Globs for files to exclude. Momentic always excludes
node_modules, .git,
and .venv.momentic.config.yaml
Default number of retries per test on failure. A per-test
retries value
overrides this. Default: 1.momentic.config.yaml
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
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.
ffmpeg, which is installed automatically by
momentic install-browsers; mobile recording does not.momentic.config.yaml
Directory for Visual diff golden files.Targets that set
use keep their baselines under
<goldenFileDir>/targets/<name>/.momentic.config.yaml
Directory for local run artifacts and result archives. Defaults to
./test-results. The --output-dir run flag overrides this setting.momentic.config.yaml
Configuration for network reporters. Currently supports
newrelic; see
Push run results to New Relic.momentic.config.yaml
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
Branches considered ineligible for cache saving in non-CI environments.
Prevents accidental cache overwriting on shared branches. See
cache saving eligibility.
momentic.config.yaml
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
CLI test-result hooks
Usehooks.postTest to run a command after each web CLI test finishes its
retries and classification. The command receives JSON on stdin.
momentic.config.yaml
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:
runUrl and envName are optional. result excludes parameters and adds
failureSection (setup, main, teardown, or none), plus optional
classification.confidence and classification.rootCause.