Skip to main content

Documentation Index

Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

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.
​
--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, firefox, or webkit. 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.

​
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; the bare flag is treated as true. 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
​
--record-video
boolean
deprecated
Deprecated alias for --video true. Use --video instead.

​
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 [shareDiagnostics]
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 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