@mablhq/mabl-cli

mabl helps you create and run reliable end-to-end tests earlier and more often in the development cycle - without disrupting your workflow.

mabl CLI

Description

mabl CLI gives you everything you need to create, edit and run end-to-end tests locally and in the mabl cloud. Install the mabl-cli from npm to create and run tests with a few simple commands. Query your workspaces, applications, environments, and tests all through the command line.

Supported Features

• Create and Edit mabl tests from the command line, including saving changes to a mabl branch
• Run headless tests locally or in your CI environment grouped by label or a plan
• Deployments can trigger test plan runs in the mabl cloud on a deployment event in your CI/CD pipeline
• Export and download all screenshots for a test run as a zip file
• Import Selenium-based tests to mabl
• Export mabl tests to Selenium IDE
• List and Describe mabl entities (e.g. tests, branches, plans, environments, applications, workspaces, etc.)

Help Documentation

Complete help documentation available at help.mabl.com/docs/mabl-cli.

Installation

Note: Node 18+ is required to run the mabl CLI

Stable version:

npm i -g @mablhq/mabl-cli

To upgrade to the latest stable version:

npm i -g @mablhq/mabl-cli@latest

Usage

Authenticate

User Authentication

mabl auth login

Authenticate in the launched browser window

Machine User Authentication

Machine users can add the --api-key <key> flag, and supply the API key from the mabl app Settings > APIs page. Alternatively, you can authenticate with an API key by running:

mabl auth activate-key <MABL_API_KEY>

This key will be used in subsequent commands.

Deployments

All mabl deployment commands can be found under the mabl deployments commands.

Create a new mabl deployment

mabl deployments create --environment-id <environment-id> --application-id <application-id>

Use --await-completion to block until all tests complete.

Note: the CLI will return non-zero exit codes on test failure.

mabl deployments create --environment-id <environment-id> --application-id <application-id> --await-completion

Add --fast-failure to trigger CLI return after the first plan in your test suite fails. This allows you to fail build quickly, rather than waiting for all tests to complete. This is advantageous in CD pipelines, to start rolling pack a deployment immediately.

Note: when using the fast failure option, any incomplete tests will continue to run, event after the CLI returns.

Extra headers can be added to test browser requests using the --http-headers flag, followed by the SPACE delimited headers.

mabl deployments create --environment-id <environment-id> --application-id <application-id> --http-headers "x-foo:bar" "x-no-captcha:true"

JSON output can be returned using the --output json flag. Note, when using this flag, no console output will be generated until the operation has completed, similar to if --silent had been passed. If execution results are available and the deployment is successfully created, results will be returned in the payload consistent with the Execution Results API.

mabl deployments create --environment-id <environment-id> --application-id <application-id> --output json

A deployment event id can be used to rejoin or start watching an ongoing deployment run using the watch command. If the deployment is already completed, the results will be printed and the program will exit. If the running deployment fails, a non-zero exit code will be emitted.

mabl deployments watch <deployment-id>

List mabl deployments

To see a list of mabl deployments for a workspace:

mabl deployments list --workspace-id <workspace-id>

Describe a mabl deployment

To see details for a specific mabl deployment:

mabl deployments describe <deployment-id>

Working with mabl tests

Creating a mabl test

The mabl tests create command allows for creating a new mabl training session directly from the CLI. Upon running this command you will be presented with a fresh Chrome window, a preconfigured mabl Trainer extension, and the familiar 'OK train me' button.

To create a mabl test:

mabl tests create <url> '<test-name>' '<test-description>'

Use the:

• --mabl-branch flag to specify a mabl branch to create the test for.
• --auto-branch flag to automatically create the specified branch if it doesn't exist already
• --width and --height flags to specify the viewport sizes of the browser
• --desc flag to supply a test description
• -w or --workspace-id flag to specify the workspace to use, Defaults to the configured workspace or user default

Editing a mabl test

The mabl tests edit command allows for editing a mabl test directly from the CLI. Upon running this command you will be presented with a fresh Chrome window, a preconfigured mabl Trainer extension, and the familiar 'OK edit test' button.

To edit a mabl test:

mabl tests edit --id <test-id>

or use a test run id to edit a test with the same config (environment, credentials, etc.) as a cloud run.

mabl tests edit --run-id <test-run-id>

Use the:

• --mabl-branch flag to specify a mabl branch to edit the test for.
• -e or --environment-id flag to specify the mabl environment to edit the test under. Specifying the environment allows mabl to use the appropriate environment variables and learned find information when editing the test
• --auto-branch flag to automatically create the specified branch if it doesn't exist already
• --width and --height flags to specify the viewport sizes of the browser
• --creds or --credentials-id flag to specify a testing credential set to use during edit (mabl credentials list to see available ones)

Note: required IDs can be found by using the CLI list commands or on the test details or test output pages inside the mabl web app

Running a mabl test locally

The mabl tests run command allows for running mabl tests locally in a fresh Chrome browser window and supports headless mode.

mabl tests run --id <test-id>

mabl tests run --id <test-id> --headless

or use a test run id to run a test with the same config (environment, credentials, etc.) as a cloud run

mabl tests run --run-id <test-run-id>

Note: required IDs can be found by using the CLI list commands or on the test details or test output pages inside the mabl web app

Use the:

• -e, or --environment-id flag to specify the mabl environment to run the test under. Specifying the environment allows mabl to use the appropriate environment variables and learned find information when running the test
• -u or --url flag to specify a particular URL to run the test against
• --mabl-branch flag to specify a mabl branch to run the test under.
• --creds or --credentials flag to specify a testing credential set to use during the local run (mabl credentials list to see available ones)
• --headless when supplied the test will run in headless mode. Flag should be supplied with no argument.
• --labels run tests that match any label.
• --exclude-labels exclude tests that match any label.
• --interaction-speed [normal, slow, slower] controls how fast the cli interacts with the page. This overrides any settings set at the environment, plan, or test run level.

Note: pre v1.0.0 run behavior has been moved to run-legacy, and will be removed in a future release.

[DEPRECATED] Alpha run mode

The alpha run command behavior, run-alpha has been promoted to GA as run.

run-alpha command is DEPRECATED and will be removed in a future release. Please migrate to run which has the identical behavior

Example:

mabl tests run-alpha --run-id <test-run-id> --headless

List mabl tests

The mabl tests list command allows for listing all mabl tests in a workspace.

mabl tests list

Use the -l or --limit flag to specify the number of tests to list

Exporting mabl tests

The mabl tests export command allows users to export tests into various formats: ["json", "yaml", "csv", "side"]. Using the "json", "yaml", and "csv" options will export a tests step descriptions, annotations, and notes in the specified format.

mabl tests export --format <[json, yaml, csv, side]>

Use the --mabl-branch to specify the exporting of a mabl branch

Export to Selenium IDE

Using the side format with the mabl tests export command will export the test into a Selenium IDE compatible format and can then be imported into the Selenium IDE extension. Please see the mabl help docs for more information.

Export mabl Data

Export all screenshots for a test run by supplying the test run id from the mabl webapp View Output URL.

e.g. in the URL .../journey-runs/n3k23bavavba-jr ← n3k23bavavba-jr is the id

All screenshots will be bundled into a zip file and downloaded to your computer. Specify the --file foo.zip to download the results to an alternative location.

mabl test-runs export <test-run-id>

To see all export options run:

mabl test-runs export --help

Note: for very large test runs, this may take minutes and result in files 100MiB or larger.

Configuration

The list subcommand allows you to view your current configuration values:

# view current configuration values
mabl config list

Proxy

To use a proxy, set the http.proxy configuration value to the URL for your proxy server. The URL can contain basic authentication credentials and port information.

# add a proxy with no credentials on port 3128
mabl config set http.proxy http://proxy.mycompany.com:3128

# add a proxy using credentials on port 3128
mabl config set http.proxy http://username:[e-mail]:3128

# delete the current proxy setting
mabl config delete http.proxy

SSL Verification

The default behavior is to validate SSL certificates. To disable SSL certificate verification, you can set http.sslVerify to false.

# disable SSL verification
mabl config set http.sslVerify false

# delete the current ssl verification setting to use the default
mabl config delete http.sslVerify

Installation Troubleshooting

If you receive the following error message, you need to ensure you have Node 18+ installed.

npm WARN notsup Unsupported engine for @mablhq/mabl-cli@1.54.0: wanted: {"node":">= 18.0.0"} (current: {"node":"8.15.1","npm":"6.13.4"})
npm WARN notsup Not compatible with your version of node/npm: @mablhq/mabl-cli@2.5.0