The CLI is currently in beta. Please report any issues you find in our Discord (opens in a new tab)!
The Momentic CLI is a NPM package (opens in a new tab) that allows you to easily integrate Momentic tests into your existing software development lifecycle (SDLC). Using the CLI, you can manage and run Momentic tests on any machine, from developer laptops to CI/CD executors.
All CLI commands require a valid API key, which you can generate through the API keys tab (opens in a new tab) on the Momentic cloud app. Your key is tied to your user account and should be kept secret.
The API key can be passed as to the CLI using the
--api-key option, or you can set the environment variable
MOMENTIC_API_KEY in your terminal.
npx momentic@latest pull example-test-path another-test-path
npx momentic@latest pull --all
This command downloads tests from Momentic's servers in YAML format. This can be useful for sharing tests within your organization as well as setting up developer workflows.
You can choose to pull all tests or specify individual tests by path. A test path is a processed version of a test's name and folder path that is guaranteed to be unique in your organization. To generate the test path, the test name is lowercased and any spaces are converted to underscores. For example,
Hello World is converted to
You can obtain a test's path by clicking its name in the test editor, which will automatically copy the path to your clipboard. Or, from the main test directory, select the "Copy test path" option from the three-dot menu:
Any modules that a pulled test depends on will also be exported to YAML. The CLI stores module YAMLs is a directory called
modules alongside your test export. The
modules folder name is fixed and should not be altered. Doing so will affect importing and running tests.
npx momentic@latest push momentic/test-file.yaml path/to/dir/of/yaml
This command uploads tests stored in local YAML files to Momentic's servers. This operation immediately overwrites the state of any tests stored remotely, so users should refrain from editing tests through the web console while CLI actions are occurring.
You may specify either individual test files or directories of YAML files.
If a pushed test depends on a module, the CLI will attempt to upload the dependent module as well by looking for the
modules folder that was created during
npx momentic pull.
You can use the CLI to run tests on the machine the CLI is installed on, or queue tests remotely on Momentic's infrastructure. The recommended approach depends on whether or not you are testing the production version of your app.
This command starts an automated browser on the local machine, runs one or more Momentic tests, and waits for the result to complete. You can choose to use local test versions that are read from the contents of YAML files on your machine, or remote test versions stored on Momentic's servers.
npx momentic@latest run --local path/to/example-test.yaml path/to/dir/of/yamls/
A common developer-friendly workflow is to commit Momentic YAML files to your Git (opens in a new tab) repository, and then pass those Momentic tests to
npx momentic run in a CI pipeline.
Momentic YAML files can be obtained from the CLI, or from the Momentic web console using the Export feature.
You can run single YAML files or directories of YAML files. As such, an easy way to run all tests available locally is to invoke
npx momentic run . in your root Momentic folder.
If a test depends on a module, the module YAML must also be present on disk. The CLI will search for a
modules folder at every level of the test's file path, starting at the file's immediate directory. For example, for a test located at
/a/b/c/test.yaml, the CLI will look for
/a/b/modules/module-name.yaml, and so forth.
This CLI command queues one or more tests to run immediately on Momentic's infrastructure. This is similar to starting tests manually through the web console. Tests queued through the CLI execute independently of any scheduled runs you may have also setup.
You can queue tests in three ways:
npx momentic@latest run --remote my-test-path another-test-path
You can run specific tests by providing one or more test paths to the CLI. Test paths are described in a previous section.
Once queued, you can visit the Results (opens in a new tab) tab on the web console to view the progress of your test invocation.
The following options are available to you when invoking
npx momentic run:
|Overrides the base URL of the test. The CLI will automatically wait for this URL to become accessible before starting tests. Useful for testing
|Timeout associated with
|Arbitrary start command that will be invoked by the CLI before tests begin (e.g.
npm run start)
|Parallelization factor: number of tests to run at the same time. Defaults to 1 (serial exeuction).
|Queue all tests in the organization.
The minimum supported CLI version is currently
If a new update is available to the Momentic CLI,
npx may prompt you to
confirm before starting the download. To bypass this check in non-interactive
environments such as CI pipelines, you can invoke
npx --yes instead.
npx momentic --version to view the current version of your CLI.
We generally recommend you use the latest version of the Momentic CLI at all times to avoid any behavior drift between running tests on the Momentic web console and other environments. For this reason, all code samples on this page append
The Momentic CLI will also warn you when your test schema is out of date and needs to be migrated.
To see a list of all available commands, run
npx momentic@latest --help. Detailed help for each command is also available, for example:
npx momentic@latest run --help.
To customize the log level used for console output, you can supply the
--log-level option before any command. For example, to run a local test with debug logging enabled:
npx momentic@latest --log-level debug run --local my-test.yaml