--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
Tests to run, given as test file paths, directories, or test-name substrings.
Defaults to every test in the current project.
Common flags
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.Run the tests a target selects, with its browser
settings. Repeat the flag to run several targets. Each target’s tests count
separately when sharding. Without
--target, the run ignores targets.Print the tests each target would run and where each test’s environment, URL,
and browser settings come from, without logging in or starting a browser.
Can’t be combined with
--from-snapshot, --ai-select,
--ai-select-dry-run, --only-quarantined, or --skip-quarantined.When using workspaces, load the
project whose name matches the filter.
Name to associate with this run, used in the dashboard and as the base
filename for generated reports.
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.Override the browser used for every test. Accepts
chromium, chrome, or
chrome-for-testing. Takes precedence over the per-test and config defaults.Wait between steps for the selected tests in this run. Accepts The first executed step in each step list has no delay. A single-step list has
no delay. See Execution timing.
0 to 10000
milliseconds. Overrides project, environment, and per-test slowMoMs settings
without changing YAML files or organization defaults. Pass 0 to disable
inherited slow motion. Without this flag, project settings are overridden by
environment settings, then per-test settings.Run only regression-labelled tests with a 500 ms pause between steps:Environment
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.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.CSV file containing input data for the tests. Each row provides input for a
separate test run. See Data-driven
tests.
Filtering
Only include tests whose file path matches any of the provided regex patterns.
The pattern only needs to match part of the path.
AI test selection
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.
Base branch, tag, or commit to diff against
HEAD. Momentic detects the pull
request base in supported CI providers.Soft cap on the number of tests selected. AI test selection can exceed it when
needed to cover distinct changed behavior.
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.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
Skip quarantined tests entirely. By default, quarantined tests still run but
their statuses do not affect pipeline status or the process exit code.
Classification
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.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
Always save updated step caches after successful runs, even on the main and
other protected Git branches. See cache saving
eligibility.
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.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.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
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
Output
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.Upload test results to the Momentic dashboard after the run. Equivalent to
running
momentic results upload <outputDir> once the run finishes.Attach this invocation’s results to a caller-chosen run group. The value must
be a UUID; anything else fails argument parsing before the run starts. When
omitted, Momentic creates a new run group for the invocation.When an orchestrator runs each test in its own process, pass the same UUID to
every
momentic run invocation to put their runs in one run group:- Add
--upload-results(or a latermomentic results upload) to send those runs to the Momentic dashboard. Without an upload, the UUID only labels the local results and theprogress.jsonroll-up. - Keep name, project, and Git metadata consistent across invocations. The UUID also becomes the run’s CI pipeline ID.
- Give each concurrent invocation its own
--output-dir. Invocations sharing a directory overwrite each other’sprogress.json.
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
Directory where reporter output is saved. Defaults to
./reports. Filenames
derive from --name (or the project name).Update locally stored golden files for Visual diff steps. See Visual
testing.
Setup
Device pixel ratio of the local screen. Set to
2 on macOS Retina or other
HiDPI displays. Defaults to the detected screen DPR.Resource to wait for before tests begin. Accepts anything supported by
wait-on.HTTP proxy used when polling
--wait-on. Provide the full URL including
protocol, optional credentials, host, and port.Timeout (in seconds) for
--wait-on. Defaults to 60. The run fails if the
resource is not reachable in time.CI
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.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.