Headless testing

The mabl CLI allows you to run tests locally in headless mode using the mabl tests run command. Headless mode offers a more performant and less disruptive way to run mabl tests. Tests run in the background and return results faster — without counting towards your mabl cloud runs. Using headless mode, QA Engineers can quickly validate test changes locally while Software Developers can perform end-to-end regression testing against their local branches without interrupting their workflow.

Running a test in headless mode

You can run headless tests using the mabl tests run command with the --headless flag specified. To run a single test you can specify either a test id or a test run id. See the Obtaining mabl Resource IDs for the CLI section on how to easily get these ids. The run command also supports the use of labels or a plan id to run multiple mabl tests sequentially.

Test id

When using the test id the mabl test specified without any additional configuration unless specified using the optional flags (run mabl tests run -h to see full list).

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

Be sure to set any necessary config flags for the test run:

  • -e, or --environment-id flag to specify the mabl environment to run the
    test under. Use mabl environments list to see options. Specifying the environment allows mabl to use the appropriate environment variables and learned element find information, such as auto-heals, when running the test.
  • -u or --url flag to specify a particular URL to run the test against. Use this flag to run tests against your local build or preview environment.
  • --mabl-branch flag to specify a mabl branch to run the test under. The test will use the most recent version from that branch if available. See Branches and version control for more info on using mabl branches.
  • --creds or --credentials flag to specify a testing credential set to use during the local run (mabl credentials list to see available ones)
  • --interaction-speed to set the speed that mabl interacts with webpages. This overrides test run settings if specified

Test run id

When using the test run id the test will run under the config used for that mabl test run when it ran in the cloud. The CLI will use the test run id to pull down the workspace, environment, credentials, auto heals, find information, and more to run the test locally with.

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

From Plan id

The --from-plan-id flag can be used to query a list of tests from a specific plan and run them sequentially. The plans environment id, url, and credentials id will also be used unless specified. You can use the mabl plans list command to get plan ids.

mabl tests run --from-plan-id <PLAN_ID> --headless



The --from-plan-id flag uses the plan information as a grouping mechanism only. It is not a plan run and advanced plan configurations (e.g. stages, shared variables) will not be adhered to.

The tests will run sequentially in alphabetical order according to the title of the test.

Test labels

The --labels flag can be used to select a set of tests and run them sequentially. The CLI will run all the tests in this set one after the other up to a maximum of 100 tests. Additionally, the --exclude-labels flag can be used to exclude a subset of the tests from the set. Be sure to enter the labels as a space delimited list for both flags.

mabl tests run --labels label1, label2, label3

mabl tests run --labels label1, label2, label3 --exclude-labels label4

If you work with multiple mabl workspaces, be sure to specify the workspace id:

  • -w or --workspace-id flag to specify the workspace to use, Defaults to the
    configured workspace or user default. Use mabl workspaces list to see options`.