JavaScript testing frameworks

With the mabl-cli node package, you can run mabl tests locally in a JavaScript testing framework, such as Jest. Use this package when you want to run mabl tests as part of a CI pipeline within an existing JavaScript-based test suite. For most other implementations of mabl test execution in a CI environment, including installation, API key auth, and how to get started, see the article on running tests inside a CI environment.

This article is a reference for running tests with the createBrowserTestsRunner API.

Installation

Install the mabl-cli as another dev dependency in your project:

npm install @mablhq/mabl-cli@2.107.63 --save-dev

Quick start: run a single test

To run browser tests, import the createBrowserTestsRunner function into your test file and define the test suite to run.

The following example runs a single test in headless mode and asserts that there were no failures. To use this example in your own project, replace TEST-ID AND ENV-ID with the respective IDs you want to use for this run:

const {createBrowserTestsRunner} = require('@mablhq/mabl-cli');

describe('Run mabl tests locally', () => {
  it('Run single test', async () => {
    const mablTestRunner = await createBrowserTestsRunner({
      testId: 'TEST-ID',
      branchName: 'master',
      environmentId: 'ENV-ID',
      headless: true,
      filterHttpRequests: false,
    });
    const result = await mablTestRunner.run();
    expect(result.numFailedTests).toEqual(0);
    expect(result.success).toEqual(true);
  }, 600_000);
});

import {
  createBrowserTestsRunner,
  TestRunConfig,
  TestResults,
} from '@mablhq/mabl-cli';

describe('Run mabl tests locally', () => {
  it('Run single test', async () => {
    const testRunConfig: TestRunConfig = {
      testId: 'TEST-ID',
      branchName: 'master',
      environmentId: 'ENV-ID',
      headless: true,
      filterHttpRequests: false,
    };
    const mablTestRunner = await createBrowserTestsRunner(testRunConfig);
    const result: TestResults = await mablTestRunner.run();
    expect(result.numFailedTests).toEqual(0);
    expect(result.success).toEqual(true);
  }, 600_000);
});

This code sample creates a MablTestRunner object by making an asynchronous call to the createBrowserTestsRunner function. The createBrowserTestsRunner function includes test run configuration options to specify which test(s) should run. To run tests and return results, the code sample calls .run() on the MablTestRunner instance.

Run multiple tests

To run multiple tests in a single call, use labelsInclude to select all tests matching one or more labels.

The following example runs every test labeled smoke. Replace smoke with your own label, and replace ENV-ID with the correct ID:

const {createBrowserTestsRunner} = require('@mablhq/mabl-cli');

describe('Run mabl smoke tests', () => {
  it('Run all smoke tests', async () => {
    const mablTestRunner = await createBrowserTestsRunner({
      labelsInclude: ['smoke'],
      branchName: 'master',
      environmentId: 'ENV-ID',
      headless: true,
      filterHttpRequests: false,
    });
    const result = await mablTestRunner.run();
    expect(result.numFailedTests).toEqual(0);
    expect(result.success).toEqual(true);
  }, 600_000);
});

import {
  createBrowserTestsRunner,
  TestRunConfig,
  TestResults,
} from '@mablhq/mabl-cli';

describe('Run mabl smoke tests', () => {
  it('Run all smoke tests', async () => {
    const testRunConfig: TestRunConfig = {
      labelsInclude: ['smoke'],
      branchName: 'master',
      environmentId: 'ENV-ID',
      headless: true,
      filterHttpRequests: false,
    };
    const mablTestRunner = await createBrowserTestsRunner(testRunConfig);
    const result: TestResults = await mablTestRunner.run();
    expect(result.numFailedTests).toEqual(0);
    expect(result.success).toEqual(true);
  }, 600_000);
});

Test run configuration

To specify which tests you want to run, one of the following options is required: testId | runId | labelsInclude | fromPlanId. Choose the one that matches your goal:

• testId — run a single specific test by ID.
• runId — re-run a specific previous test run, reusing that run’s configuration (environment, credentials, URL).
• labelsInclude — run all tests matching one or more labels.
• fromPlanId — run all tests belonging to a specific plan. Note that running tests with the fromPlanId option is not a plan run in the mabl cloud. Advanced plan configurations, such as stages, browser settings or shared variables, are not applied.

The following table outlines all of the available testRunConfig options available for the createBrowserTestsRunner function:

Returning results

After defining the mablTestRunner, call the .run() function to run all tests and return test results. All times are in milliseconds since the unix epoch:

Returns: TestResults

• numFailedTests - number
• numPassedTests - number
• numSkippedTests - number
• numTotalTests - number
• testResults - array
  • status - string (passed | failed | skipped)
  • errorMessage - string
  • testName - string
  • startTime - number
  • endTime - number
• startTime - number
• endTime - number
• totalTimeSeconds - number
  • Total test(s) time in seconds
• success - boolean