Skip to main content
Runs Momentic tests in the current project. By default, results are written to a local directory; pass --upload-results to send them to the dashboard after the run completes. Requires tests to exist locally as YAML files. 
npx momentic run --upload-results

​
Arguments

​
[tests...]
array
Tests to run, given as test file paths, directories, or test-name substrings. Defaults to every test in the current project.

​
Common flags

​
-c, --config <config>
string
Path to the Momentic configuration file. Defaults to momentic.config.yaml in the current directory.
​
-f, --filter <filter>
string
When using workspaces, load the project whose name matches the filter.
​
--name <name>
string
Name to associate with this run, used in the dashboard and as the base filename for generated reports.
​
-p, --parallel <parallel>
string
Number of tests to run in parallel. Each test starts its own browser instance. Defaults to 1. Pass auto to size workers from the host’s CPU count.
​
--retries <retries>
string
Number of times to retry a test if it fails. Overrides each test’s own retry configuration.
​
--browser <browser>
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

​
--env <env>
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.
​
--url-override <urlOverride>
string
Override the base URL of the test or environment. Useful for running against a preview deployment.
​
--custom-headers <customHeaders...>
array
Custom headers to include in the run. Specify multiple headers separated by spaces.
​
--input-csv <inputCsv>
string
CSV file containing input data for the tests. Each row is used as input for a separate test run. See Data-driven tests.

​
Filtering

​
--labels <labels...>
array
Only run tests with one of the specified labels.
​
--include <includePatterns...>
array
Only include tests whose file path matches any of the provided regex patterns. The pattern only needs to match part of the path.
​
--exclude <excludePatterns...>
array
Exclude tests whose file path matches any of the provided regex patterns.

​
Quarantine

​
--skip-quarantined
boolean
Skip quarantined tests entirely. By default, quarantined tests still run but their statuses do not affect pipeline status or the process exit code.
​
--only-quarantined
boolean
Run only quarantined tests, applying their statuses to pipeline status and the exit code.
​
--ignore-quarantine
boolean
Run every test and apply all statuses to pipeline status and exit code.

​
Classification

​
--classify-override-exit-code
boolean
Opt in to letting the classification verdict override this run’s exit code, overriding ai.classification.overrideExitCode in momentic.config.yaml. When present, failures that classification routes to heal or warn exit 0. Takes precedence over both the config file and the cloud setting. Has no effect unless classification is enabled.

​
Caching

​
--disable-cache
boolean
Disable step caches entirely. Steps run without cached data and no caches are saved.
​
--save-cache
boolean
Always save updated step caches after successful runs, even on the main and other protected Git branches. See cache saving eligibility.
​
--regenerate-cache
boolean
Run without using any existing caches. Step caches are still saved at the end of the run. Useful for refreshing caches after a config change.
Steps run without cached data, which significantly increases run time. Not recommended for ongoing use.
​
--bust-oldest-cache-percentage <n>
number
Bust the oldest n% of step caches before the run. Useful for incrementally regenerating caches after a config change. At least one cache is always busted, even if n% rounds to zero. Only applies on non-protected branches.

​
Video

​
--video [value]
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). Requires ffmpeg.
npx momentic run --video true         # record every test
npx momentic run --video on-fail      # keep videos only for failures
npx momentic run --video false        # disable video

​
Sharding

​
--shard-index <shardIndex>
string
1-indexed shard to run. Combine with --shard-count to split tests across machines.
​
--shard-count <shardCount>
string
Total number of shards.

​
Output

​
--output-dir <outputDir>
string
Directory to store run artifacts (screenshots, logs, results). The directory is cleared at the start of a run. Defaults to ./test-results.
​
--upload-results
boolean
Upload test results to the Momentic dashboard after the run. Equivalent to running momentic results upload <outputDir> once the run finishes.
​
--reporter <reporter>
string
Output reporter. Pass multiple times to combine reporters (e.g. --reporter=list --reporter=junit).Live reporter renders 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.
File reporters write post-run output to --reporter-dir:
  • junit
  • allure
  • allure-json
  • playwright-json
  • buildkite-json
​
--reporter-dir <reporterDir>
string
Directory where reporter output is saved. Defaults to ./reports. Filenames derive from --name (or the project name).
​
--update-golden-files
boolean
Update locally stored golden files for Visual diff steps. See Visual testing.

​
Setup

​
--pixel-ratio <pixelRatio>
number
Device pixel ratio of the local screen. Set to 2 on macOS Retina or other HiDPI displays. Defaults to the detected screen DPR.
​
--start <start>
string
Command to run before tests begin. Useful for booting a local dev server.
npx momentic run --start "pnpm dev"
​
--wait-on <waitOn>
string
Resource to wait for before tests begin. Accepts anything supported by wait-on.
​
--wait-on-proxy <waitOnProxy>
string
HTTP proxy used when polling --wait-on. Provide the full URL including protocol, optional credentials, host, and port.
​
--wait-on-timeout <waitOnTimeout>
string
Timeout (in seconds) for --wait-on. Defaults to 60. The run fails if the resource is not reachable in time.

​
CI

​
--timeout-minutes <timeoutMinutes>
string
Maximum total run time, in minutes. When reached, running tests stop, results are flushed to disk, and the process exits with code 1.
​
--share-diagnostics
boolean
Emit run diagnostics using standard OpenTelemetry exporter environment variables. Configure exporter endpoints via the usual OTEL_* env vars. Env: MOMENTIC_SHARE_DIAGNOSTICS.
​
-y, --yes
boolean
Skip all confirmation prompts. Enabled by default when CI is set.

​
Examples

Run every test and upload to the dashboard: 
npx momentic run --upload-results
Run a single test suite across four shards in CI: 
npx momentic run tests/checkout --shard-index 1 --shard-count 4 --reporter junit
Run against a preview deployment with a startup hook: 
npx momentic run --url-override https://preview-123.example.com --start "pnpm dev" --wait-on http-get://localhost:3000