Skip to main content

JavaScript testing frameworks

Eva Ferreira
  • Updated

With the mabl-cli node package, you can run mabl tests locally in a JavaScript testing framework, such as Jest. This article explains how to run browser tests by importing the createBrowserTestRunner function into a project in your preferred JavaScript testing framework.

Before you start

If this is your first time using the mabl CLI, please refer to the CLI overview documentation for additional information.

Installation

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

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

This install uses the same auth settings as the globally installed CLI tool. Make sure your auth session is active before running the tests. If not, run mabl auth login.

Running tests

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

The mabl-cli node package includes support for both JavaScript and TypeScript.

The following JavaScript 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> with the ID of the test you want to run:

import {createBrowserTestRunner} from '@mablhq/mabl-cli';

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

This code sample creates a MablTestRunner object by making an asynchronous call to the createBrowserTestRunner function. The createBrowserTestRunner 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.

Test run configuration

To specify which tests you want to run, one of the following options is required: testId | runId | labelsInclude.

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

Option Type Description
branchName <string> The name of the mabl branch to run the test against
branchChangesOnly <boolean> Use with the branchName option. Exclude tests that do not exist on the specified branch. The default value is false.
credentialsId <string> ID of the credentials to use in the test
environmentId <string> mabl environment to run under. Specify to ensure the test runs with the correct environment variables and the latest find information. Note: setting the environment does not override the default URL. To override the URL, use the url option.
fromPlanId <string> Run tests associated with a specific plan. Running tests with the fromPlanId option is not a plan run. Advanced plan configurations, such as stages, browser settings or shared variables, are not applied. 
headless <boolean> Run the test in the background without opening a browser window. The default value is false.
labelsExclude <Array<string>> Exclude any tests that match the space-delimited list of labels
labelsInclude <Array<string>> Run any tests that match the space-delimited list of labels. For example: ['label1', 'label2']
testId <string> ID of the test to run
runId <string> ID of the test run to pull configuration from, including environment, credentials, and URL.
url <string> The URL to run the test against
basicAuthCredentialsId <string> ID of the credentials you want to use for basic authentication in the test run
workspaceId <string> ID of the workspace to run tests in. Use this option if you belong to multiple mabl workspaces.

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<TestResult>>
    • 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>

TypeScript support

The following TypeScript 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> with the ID of the test you want to run:

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

describe('mabl Execution Validation Tests', () => {
  it('Run single test', async () => {
    const testRunConfig: TestRunConfig = {
      testId: '<TEST-ID>',
      branchName: 'master',
      headless: true,
    };
  const mablTestRunner = await createBrowserTestRunner(testRunConfig);
    const result: TestResults = await mablTestRunner.run();
    expect(result.numFailedTests).toEqual(0);
    expect(result.success).toEqual(true);
  });
});



 

Related articles