Skip to main content
Prerequisites: These tests must exist locally as YAML files.
Run Momentic tests in the current project. By default, tests will output results to a local directory. You can then upload results to Momentic dashboard using the momentic results upload command. 
npx momentic run [options] [tests...]

​
Arguments

​
[tests...]
array
The tests to run. If not specified, selects all tests in the current project. You can specify multiple tests separated by spaces, test paths, or folder paths. You can also pass substrings to match test names.

​
Options

​
-c, --config <config>
string
Path to the Momentic configuration file. Defaults to momentic.config.yaml in the current directory.
​
-f, --filter <filter>
string
Only applicable when using Workspaces. Loads the project with the specified name.
​
--env <env>
string
The environment to run the test in. Overrides any environment specified by the test.
The base URL set on the test always takes precedence over the environment. If you want to override the base URL set on the test, use the --url-override option instead.
​
--url-override <urlOverride>
string
Override the base URL set on the test or environment. Useful when running tests against a different URL (e.g., a preview deployment) than the one specified in the test or environment.
​
--name <name>
string
Name to associate with this run for easier identification in the Momentic dashboard. Also used as the base filename for generated reports.
​
--custom-headers <customHeaders...>
array
Custom headers to include in the test run. Specify multiple headers separated by spaces.
​
--input-csv <inputCsv>
string
Path to a CSV file containing input data for the tests. Each row is used as input for a separate test run. See Data-driven tests for details.
​
-p, --parallel <parallel>
string
Number of tests to run in parallel. Each test starts its own browser instance. Useful for speeding up execution on large test sets.
​
--retries <retries>
string
Number of times to retry a test if it fails.
​
--timeout-minutes <timeoutMinutes>
string
Maximum number of minutes to run tests before stopping. When the timeout is reached, currently running tests will be stopped, results will be written to disk, and a summary will be printed. The process exits with code 1. Useful for CI pipelines that need to enforce a maximum execution time.
​
--labels <labels...>
array
Run only tests that match the specified labels.
​
--output-dir <outputDir>
string
Directory to store run artifacts such as screenshots, results, and logs. The directory is cleared at the start of execution. Defaults to ./test-results.
​
--upload-results
boolean
Upload test results to Momentic dashboard after the test run. Equivalent to running momentic results upload <outputDir> after completion, where <outputDir> is the directory specified by --output-dir (defaults to ./test-results).
​
--reporter <reporter>
string
Reporter to use for the output. One of junit, allure, playwright-json, or buildkite-json.
​
--reporter-dir <reporterDir>
string
Directory where reporter output will be saved. Defaults to ./reports.Reporter filenames are based on the run name. For example, junit writes {name}.xml and buildkite-json writes {name}.buildkite.json. The name comes from --name when provided; otherwise, the detected project’s name from momentic.config.yaml is used. For buildkite-json, scope comes from the run name and name comes from the individual test name.
​
--shard-index <shardIndex>
string
Index of the shard to run (1-indexed). Used with --shard-count to split tests across multiple machines or processes.
​
--shard-count <shardCount>
string
Total number of shards. Used with --shard-index to split tests across multiple machines or processes.
​
--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
The opposite of --include: tests whose file path matches any of the provided regex patterns are excluded.
​
--skip-quarantined
boolean
Skip quarantined tests entirely. By default, quarantined tests run but their statuses do not impact pipeline success or the exit code of the process.
​
--only-quarantined
boolean
Run only quarantined tests. Their statuses impact pipeline success and the exit code of the process.
​
--ignore-quarantine
boolean
Run all tests and apply their statuses to pipeline success and exit code.
​
--disable-cache
boolean
Disable caching entirely. Steps run without cached data and no caches are saved after the run. This can result in slower execution but ensures all steps run fresh.
​
--save-cache
boolean
Always save updated step caches after successful test runs, even on the main Git branch and protected branches. See cache saving eligibility for more information.
​
--regenerate-cache
boolean
Run the test without using any existing caches. Step caches are still saved at the end of the run. Useful for updating caches after changing a configuration option.
Using this option causes all steps to run without any cached data, resulting in significantly longer execution times. Not recommended for ongoing use.
​
--update-golden-files
boolean
Update the golden files for Visual diff. See Visual testing.
​
--video [value]
string
Record videos of test runs. Enabling this increases the size of results. Once uploaded, videos can be viewed in the run viewer. Requires ffmpeg, which can be installed via momentic install-browsers ffmpeg. Use the bare flag or pass true, false, or on-fail.
npx momentic run --video true         # records all videos
npx momentic run --video on-fail      # keeps videos only for failures
npx momentic run --video false        # disables video
​
--start <start>
string
Command to run before starting the test. Useful for starting a local server or any prerequisite process.
npx momentic run --start "npm run start"
​
--wait-on <waitOn>
string
Resource to wait for before starting the test. Can be a URL, a file, or any other resource supported by wait-on. Useful for ensuring the resource is available before tests start.
​
--wait-on-proxy <waitOnProxy>
string
HTTP proxy to use when polling the --wait-on resource. Provide the full proxy URL, including protocol, optional credentials, host, and port.
​
--wait-on-timeout <waitOnTimeout>
string
Timeout (in milliseconds) for the --wait-on option. If the resource is not available within this time, the test fails.