> ## 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.

# momentic run

> Run Momentic web tests locally and optionally upload results.

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.

```bash theme={null}
npx momentic run --upload-results
```

## Arguments

<ParamField path="[tests...]" type="array">
  Tests to run, given as test file paths, directories, or test-name substrings.
  Defaults to every test in the current project.
</ParamField>

## Common flags

<ParamField path="-c, --config <config>" type="string">
  Path to the Momentic configuration file. Defaults to `momentic.config.yaml` in
  the current directory.
</ParamField>

<ParamField path="-f, --filter <filter>" type="string">
  When using [workspaces](/configuration/workspace), load the project whose name
  matches the filter.
</ParamField>

<ParamField path="--name <name>" type="string">
  Name to associate with this run, used in the dashboard and as the base
  filename for generated reports.
</ParamField>

<ParamField path="-p, --parallel <parallel>" type="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.
</ParamField>

<ParamField path="--retries <retries>" type="string">
  Number of times to retry a test if it fails. Overrides each test's own retry
  configuration.
</ParamField>

<ParamField path="--browser <browser>" type="string">
  Override the browser used for every test. Accepts `chromium`, `chrome`, or
  `chrome-for-testing`. Takes precedence over the per-test and config defaults.
</ParamField>

## Environment

<ParamField path="--env <env>" type="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.
</ParamField>

<ParamField path="--url-override <urlOverride>" type="string">
  Override the base URL of the test or environment. Useful for running against a
  preview deployment.
</ParamField>

<ParamField path="--custom-headers <customHeaders...>" type="array">
  Custom headers to include in the run. Specify multiple headers separated by
  spaces.
</ParamField>

<ParamField path="--input-csv <inputCsv>" type="string">
  CSV file containing input data for the tests. Each row is used as input for a
  separate test run. See [Data-driven
  tests](/guides/data-driven-tests/parametrized-runs).
</ParamField>

## Filtering

<ParamField path="--labels <labels...>" type="array">
  Only run tests with one of the specified labels.
</ParamField>

<ParamField path="--include <includePatterns...>" type="array">
  Only include tests whose file path matches any of the provided regex patterns.
  The pattern only needs to match part of the path.
</ParamField>

<ParamField path="--exclude <excludePatterns...>" type="array">
  Exclude tests whose file path matches any of the provided regex patterns.
</ParamField>

## Quarantine

<ParamField path="--skip-quarantined" type="boolean">
  Skip quarantined tests entirely. By default, quarantined tests still run but
  their statuses do not affect pipeline status or the process exit code.
</ParamField>

<ParamField path="--only-quarantined" type="boolean">
  Run only quarantined tests, applying their statuses to pipeline status and the
  exit code.
</ParamField>

<ParamField path="--ignore-quarantine" type="boolean">
  Run every test and apply all statuses to pipeline status and exit code.
</ParamField>

## Classification

<ParamField path="--classify-override-exit-code" type="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](/reliability/failure-analysis) is enabled.
</ParamField>

<ParamField path="--no-classify" type="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.
</ParamField>

## Caching

<ParamField path="--disable-cache" type="boolean">
  Disable step caches entirely. Steps run without cached data and no caches are
  saved.
</ParamField>

<ParamField path="--save-cache" type="boolean">
  Always save updated step caches after successful runs, even on the main and
  other protected Git branches. See [cache saving
  eligibility](/reliability/step-cache#cache-saving-eligibility).
</ParamField>

<ParamField path="--regenerate-cache" type="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.

  <Warning>
    Steps run without cached data, which significantly increases run time. Not
    recommended for ongoing use.
  </Warning>
</ParamField>

<ParamField path="--bust-oldest-cache-percentage <n>" type="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.
</ParamField>

<ParamField path="--from-snapshot <snapshots...>" type="array">
  Replay one or more `.snapshot.zip` files created with [`momentic
      snapshot`](/cli-reference/momentic/commands/snapshot). Each snapshot replays
  in complete isolation: modules, environment, and step caches are read straight
  from the zip, and the cache backend is never read from or written to. Because
  the run is fully self-contained, this option cannot be combined with test
  paths or any test-selection option (`--include`, `--exclude`, `--labels`,
  `--ai-select`).
</ParamField>

## Video

<ParamField path="--video [value]" type="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`.

  ```bash theme={null}
  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
  ```
</ParamField>

## Sharding

<ParamField path="--shard-index <shardIndex>" type="string">
  1-indexed shard to run. Combine with `--shard-count` to split tests across
  machines.
</ParamField>

<ParamField path="--shard-count <shardCount>" type="string">
  Total number of shards.
</ParamField>

## Output

<ParamField path="--output-dir <outputDir>" type="string">
  Directory to store run artifacts (screenshots, logs, results). The directory
  is cleared at the start of a run. Defaults to `./test-results`.

  A live `progress.json` is written to the top of this directory and updated as
  steps complete, so you can poll step progress while a run is still going. See
  [Live run progress](/running-tests/results#live-run-progress).
</ParamField>

<ParamField path="--upload-results" type="boolean">
  Upload test results to the Momentic dashboard after the run. Equivalent to
  running `momentic results upload <outputDir>` once the run finishes.
</ParamField>

<ParamField path="--reporter <reporter>" type="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`:

  * `json`
  * `junit`
  * `allure`
  * `allure-json`
  * `playwright-json`
  * `buildkite-json`

  Network reporters push results to an external service configured under
  [`reporting`](/configuration/momentic-config#reporting) in
  `momentic.config.yaml`:

  * `newrelic`: see [Push run results to New Relic](/guides/reporting/new-relic)
</ParamField>

<ParamField path="--reporter-dir <reporterDir>" type="string">
  Directory where reporter output is saved. Defaults to `./reports`. Filenames
  derive from `--name` (or the project name).
</ParamField>

<ParamField path="--update-golden-files" type="boolean">
  Update locally stored golden files for **Visual diff** steps. See [Visual
  testing](/guides/visual-testing/golden-files).
</ParamField>

## Setup

<ParamField path="--pixel-ratio <pixelRatio>" type="number">
  Device pixel ratio of the local screen. Set to `2` on macOS Retina or other
  HiDPI displays. Defaults to the detected screen DPR.
</ParamField>

<ParamField path="--start <start>" type="string">
  Command to run before tests begin. Useful for booting a local dev server.

  ```bash theme={null}
  npx momentic run --start "pnpm dev"
  ```
</ParamField>

<ParamField path="--wait-on <waitOn>" type="string">
  Resource to wait for before tests begin. Accepts anything supported by
  [`wait-on`](https://www.npmjs.com/package/wait-on).
</ParamField>

<ParamField path="--wait-on-proxy <waitOnProxy>" type="string">
  HTTP proxy used when polling `--wait-on`. Provide the full URL including
  protocol, optional credentials, host, and port.
</ParamField>

<ParamField path="--wait-on-timeout <waitOnTimeout>" type="string">
  Timeout (in seconds) for `--wait-on`. Defaults to `60`. The run fails if the
  resource is not reachable in time.
</ParamField>

## CI

<ParamField path="--timeout-minutes <timeoutMinutes>" type="string">
  Maximum total run time, in minutes. When reached, running tests stop, results
  are flushed to disk, and the process exits with code `1`.
</ParamField>

<ParamField path="--share-diagnostics" type="boolean">
  Emit run diagnostics using standard OpenTelemetry exporter environment
  variables. Configure exporter endpoints via the usual `OTEL_*` env vars. Env:
  `MOMENTIC_SHARE_DIAGNOSTICS`.
</ParamField>

<ParamField path="-y, --yes" type="boolean">
  Skip all confirmation prompts. Enabled by default when `CI` is set.
</ParamField>

## Examples

Run every test and upload to the dashboard:

```bash theme={null}
npx momentic run --upload-results
```

Run a single test suite across four shards in CI:

```bash theme={null}
npx momentic run tests/checkout --shard-index 1 --shard-count 4 --reporter junit
```

Run against a preview deployment with a startup hook:

```bash theme={null}
npx momentic run --url-override https://preview-123.example.com --start "pnpm dev" --wait-on http-get://localhost:3000
```

Replay snapshots created with
[`momentic snapshot`](/cli-reference/momentic/commands/snapshot) in full
isolation:

```bash theme={null}
npx momentic run --from-snapshot checkout.snapshot.zip login.snapshot.zip
```