<p align="center">
  <img width="250" style="margin-top:20px;" src="https://storage.googleapis.com/mabl-email-static-assets/mabl_logo_horizontal_light.png">
</p>
<p align="center">
mabl helps you create and run reliable end-to-end tests earlier and more often in the development cycle - without disrupting your workflow.
</p>

# 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](https://help.mabl.com/docs/mabl-cli).

## Installation

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

Stable version:

```bash
npm i -g @mablhq/mabl-cli
```

To upgrade to the latest stable version:

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

## Usage

### Authenticate

#### User Authentication

```bash
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](https://app.mabl.com) `Settings > APIs` page. Alternatively, you
can authenticate with an API key by running:

```bash
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

```bash
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.

```bash
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.

```bash
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](https://help.mabl.com/docs/integrating-mabl-with-your-cicd-workflow#section-deployment-events-api).

```bash
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.

```bash
mabl deployments watch <deployment-id>
```

#### List mabl deployments

To see a list of mabl deployments for a workspace:

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

#### Describe a mabl deployment

To see details for a specific mabl deployment:

```bash
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:

```bash
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:

```bash
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.

```bash
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.

```bash
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

```bash
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.**

#### List mabl tests

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

```bash
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.

```bash
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](https://help.mabl.com/docs/selenium-ide-export) 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.

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

To see all export options run:

```bash
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:

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

```bash
# 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:password@proxy.mycompany.com: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.

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

```bash
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
```
