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 mobile 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-mobile 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.
​
--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. Defaults to 1. Pass AUTO to saturate the current shard.Remote runs give each test an independent emulator session, so parallelism is safe and any org quota is enforced server-side. Local Android runs require a distinct AVD per parallel test, running multiple tests against the same --local-avd-id conflicts. Local iOS runs prefer parallel=1 because concurrent Appium instances share a driver manifest.
​
-y, --yes
boolean
Skip all confirmation prompts. Enabled by default when CI is set.

​
Environment

​
--env <env>
string
Environment to run tests in. Must exist in the project configuration and takes precedence over the default environment configured on the test.
​
--region <region>
string
Region used for remote emulator sessions. Overrides any region configured at the project or environment level. Pass closest to autoselect the nearest region.
​
--channel <channel>
string
Override the default release channel for APK selection (e.g., staging, dev). When omitted, falls back to the test’s default channel, otherwise no APK is installed on emulator initialization.
​
--tag <tag>
string
Override the version tag within the selected channel. When omitted, uses the test’s default tag, otherwise the latest uploaded APK in the channel.

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

​
Video

​
--video [value]
boolean | on-fail
Record videos of mobile test runs. Accepts true, false, or on-fail; the bare flag is treated as true. Videos are recorded by default.
npx momentic-mobile run --video true         # record every test
npx momentic-mobile run --video on-fail      # keep videos only for failures
npx momentic-mobile run --video false        # disable video

​
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 even if it is quarantined. Useful for validating that quarantined tests are fixed before moving them out of quarantine.

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

​
Sharding

​
--shard-index <shardIndex>
string
1-indexed shard to run. Defaults to 1. Must be less than or equal to --shard-count.
​
--shard-count <shardCount>
string
Total number of shards. Defaults to 1 (no sharding).

​
Output

​
--output-dir <outputDir>
string
Directory to store run artifacts (screenshots, logs, results). Defaults to the project’s outputDir or ./test-results. The directory is cleared at the start of a run.
​
--upload-results
boolean
Upload test results to the Momentic dashboard after the run. Equivalent to running momentic-mobile 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. The following are supported for mobile runs:
  • junit
  • buildkite-json
​
--reporter-dir <reporterDir>
string
Directory where reporter output is saved. Defaults to ./reports. Filenames derive from --name (or the project name).
​
--log-level <logLevel>
string
Logging verbosity. One of error, warn, info, or debug.

​
Local devices

​
--local-avd-id <id>
string
Force tests to use a specific local Android Virtual Device (AVD). Overrides all configuration at the test and environment level.
​
--local-apk-path <path>
string
Override the APK installed on emulator initialization. Requires --local-avd-id.
​
--local-ios-device-type <deviceType>
string
Force tests to use a specific local iOS simulator device type. Accepts any option Xcode supports when creating a new simulator (e.g., "iPhone 17").
​
--local-app-path <path>
string
Override the iOS app installed on simulator initialization. Requires --local-ios-device-type.

​
CI

​
--timeout-minutes <timeoutMinutes>
string
Maximum total run time, in minutes. When reached, running tests stop and the current results are printed.

​
Examples

Run every test and upload to the dashboard: 
npx momentic-mobile run --upload-results
Run a sharded Android pipeline against a staging APK: 
npx momentic-mobile run --channel staging --shard-index 1 --shard-count 4 --reporter junit
Run against a local iOS simulator with a freshly built app: 
npx momentic-mobile run --local-ios-device-type "iPhone 17" --local-app-path ./build/App.app