--upload-results to send them to the dashboard after the run
completes. Requires tests to exist locally as YAML files.
--ai-select to run only the tests
your change affects, and --start to boot the dev server first. See
Run before you push.
Arguments
array
Tests to run, given as test file paths, directories, or test-name substrings.
Defaults to every test in the current project.
Common flags
string
Path to the Momentic configuration file. When omitted, Momentic searches the
current directory and its parents for
momentic.config.yaml or a workspace
configuration. Use this flag to select a project when discovery finds more
than one.string
When using workspaces, load the project whose name
matches the filter.
string
Name to associate with this run, used in the dashboard and as the base
filename for generated reports.
string
Number of tests to run in parallel. Each test starts its own browser instance.
Uses the project’s
parallel setting, then 1. Pass auto to size
concurrency from the host’s CPU count. New projects created by momentic init
use auto.string
Number of times to retry a test if it fails. Overrides each test’s own retry
configuration.
string
Override the browser used for every test. Accepts
chromium, chrome, or
chrome-for-testing. Takes precedence over the per-test and config defaults.Environment
string
Run every test in this invocation on hosted browsers in one Browser Fleet
region:
westus3 or eastus2. The flag turns on hosted browsers for the run
even when browser.remoteBrowser is unset. The run fails instead of falling
back when that region cannot serve it, and runs through a private Connector
cannot use it. See Regions.string
Environment to run tests in. Overrides any environment configured on the test
itself. The base URL set on the test still takes precedence; use
--url-override to override it.string
Override the base URL of the test or environment. Use it to run against a
preview deployment.
array
Custom headers to include in the run. Specify multiple headers separated by
spaces.
string
CSV file containing input data for the tests. Each row provides input for a
separate test run. See Data-driven
tests.
Filtering
array
Only run tests with one of the specified labels.
array
Only include tests whose file path matches any of the provided regex patterns.
The pattern only needs to match part of the path.
array
Exclude tests whose file path matches any of the provided regex patterns.
AI test selection
boolean
Use AI test selection to choose which in-scope tests to run from
the current Git diff. If selection is unavailable, Momentic runs every
in-scope test.
string
Base branch, tag, or commit to diff against
HEAD. Momentic detects the pull
request base in supported CI providers.number
Soft cap on the number of tests selected. AI test selection can exceed it when
needed to cover distinct changed behavior.
string
Additional selection guidance appended to the built-in AI test selection
instructions when
--ai-select or --ai-select-dry-run is enabled. Repeat to
append values in command-line order. Omitting the flag leaves the standard
selection prompt unchanged.boolean
Run every in-scope test, while recording which tests AI test selection would
have selected. Use this to evaluate selection on your own CI history.
Quarantine
boolean
default:"false"
Skip quarantined tests entirely. By default, quarantined tests still run but
their statuses do not affect pipeline status or the process exit code.
boolean
Run only quarantined tests and apply their statuses to pipeline status and the
exit code.
boolean
Run every test and apply all statuses to pipeline status and exit code.
Classification
boolean
Lets the classification verdict override this run’s exit code. Failures that
classification routes to heal or warn exit
0. Takes precedence over
ai.classification.overrideExitCode in momentic.config.yaml and the cloud
setting. Has no effect unless
classification is enabled.boolean
Skip AI classification for this run, even if classification is enabled in
momentic.config.yaml or workspace settings. Use this for one-off local runs
where you only need the raw failure and want the CLI to exit as soon as test
execution finishes.Caching
boolean
Disable step caches entirely. Steps run without cached data and the run saves
no caches.
boolean
Always save updated step caches after successful runs, even on the main and
other protected Git branches. See cache saving
eligibility.
boolean
Run without using existing step caches. Saving still follows the normal
branch rules; add
--save-cache to save on protected branches. Use it to
refresh caches after a config change.number
Bust the oldest
n% of step caches before the run. Use it to regenerate
caches gradually after a config change. At least one cache is always busted,
even if n% rounds to zero. Only applies on non-protected branches.array
Replay one or more
.snapshot.zip files created with momentic snapshot. Modules, environment
data, and step caches come from the zip, and the cache backend is never read
from or written to. A Momentic API key and project config are still required.
This option cannot be combined with test paths, --include, --exclude,
--labels, --ai-select, --input-csv, or --only-quarantined.Video
boolean | on-fail
Record videos of test runs. Accepts
true, false, or on-fail. Defaults to
on-fail (videos are recorded but kept only for failing tests). The required
ffmpeg binary is installed by momentic install-browsers.Sharding
string
1-indexed shard to run. Combine with
--shard-count to split tests across
machines.string
Total number of shards.
Output
string
Directory to store run artifacts (screenshots, logs, results). The directory
is cleared at the start of a run. Defaults to the project’s
outputDir or
./test-results.The run writes a live progress.json to the top of this directory and updates
it as steps complete, so you can poll step progress while a run is still going.
See Live run progress.boolean
Upload test results to the Momentic dashboard after the run. Equivalent to
running
momentic results upload <outputDir> once the run finishes.string
Attach this invocation’s results to a caller-chosen run group. The value must
be a UUID. When omitted, Momentic creates a new run group for the invocation.
string
Output reporter. Pass multiple times to combine reporters
(e.g.
--reporter=list --reporter=junit).Live reporters render progress to the terminal as the run unfolds:list: per-test rows. Default. On a TTY the running rows redraw in place with their current step; on non-TTY each test commits a single row when it finishes.steps: append-only lines logging each step as it starts and finishes, with per-step durations, sections (setup/main/teardown), and nesting via indentation (modules, AI actions, loops). Use it for CI logs, which do not render thelistreporter’s in-place redraws.
--reporter-dir:jsonjunitallureallure-jsonplaywright-jsonbuildkite-json
reporting in
momentic.config.yaml:newrelic: see Push run results to New Relic
string
Directory where reporter output is saved. Defaults to
./reports. Filenames
derive from --name (or the project name).boolean
Update locally stored golden files for Visual diff steps. See Visual
testing.
Setup
number
Device pixel ratio of the local screen. Set to
2 on macOS Retina or other
HiDPI displays. Defaults to the detected screen DPR.string
Command to run before tests begin. Use it to boot a local dev server.
string
HTTP proxy used when polling
--wait-on. Provide the full URL including
protocol, optional credentials, host, and port.string
Timeout (in seconds) for
--wait-on. Defaults to 60. The run fails if the
resource is not reachable in time.CI
string
Maximum total run time, in minutes. When the limit hits, running tests stop,
results flush to disk, and the process exits with code
1.Emit run diagnostics using standard OpenTelemetry exporter environment
variables. Configure exporter endpoints via
OTEL_* env vars. Env:
MOMENTIC_SHARE_DIAGNOSTICS.boolean
Skip all confirmation prompts. Enabled by default when
CI is set.Examples
Run every test and upload to the dashboard:Run before you push
Commit your changes, then run the end-to-end tests they affect against a local dev server before you open a pull request.--start boots the server,
--wait-on holds the run until it answers, and --ai-select picks tests from
the committed diff between origin/main and HEAD, so uncommitted edits do not
count:
./test-results unless you pass --upload-results. To run one
flow instead of a selection, pass its path:
momentic snapshot. Replace the
example IDs with the test IDs printed by snapshot:
momentic list --changed and
run the returned paths. The example checks for an empty list before calling
run.