JavaScript testing frameworks

You can use the mabl-cli node package to run end-to-end tests locally in your preferred testing framework. The mabl-cli package exposes the MablTestRunner as an importable object that can be used to initialize and run mabl tests from within JavaScript testing frameworks such as Jest.

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 will use the same auth settings as the globally installed CLI tool. You’ll want to ensure your auth is active before running the tests. If not run mabl auth login.

Using inside a test

The createMablTestRunner function can be imported from the mabl-cli package and used to create a MablTestRunner. To run the test then call .run() on the MablTestRunner. Below is an example of a JavaScript test that will run a single test in headless mode and assert that there were no failures.

import {createMablTestRunner} from '@mablhq/mabl-cli';
 
jest.setTimeout(30000);
 
describe('Run mabl tests locally', () => {
 it('Run single test', async () => {
   const mablTestRunner = await createMablTestRunner({
     testId: 'fb60BEqZa3kXZy1Gj0hAsA-j',
     branchName: 'master',
     headless: true,
   });
   const result = await mablTestRunner.run();
   expect(result.numFailedTests).toEqual(0);
   expect(result.success).toEqual(true);
 });
});

📘

You may have to increase the default Jest timeout to accommodate the longer test runs. One way to do that is by specifying it globally: jest.setTimeout(30000);

createMablTestRunner([TestRunConfig]) <​Promise>
An asynchronous function that creates a mablTestRunner with the specified test run config. One of the following options must be specified to run a test (testId | runId | labelsInclude), all others are optional.

• TestRunConfig:
  Please see the following mabl help docs for info on obtaining needed test ids for the test run config or use the mabl-cli to query for them.
• branchName
  • The name of the mabl branch to run the test under
• branchChangesOnly
  • Only run tests that are on the specified mabl branch
• credentialsId
  • The credentials id to use in the test
• environmentId
  • The environment id to use in the test
• fromPlanId
  • the plan id to get a list of tests from. The environment id and the credentials id will be used as well unless supplied. Note: It is not a plan run and advanced plan configurations (e.g. stages, shared variables) will not be adhered to
• headless
  • Whether to run the test in headless mode or not
• labelsExclude <Array<​string>>
  • An array of labels to exclude tests by when using labels to specify tests to run
• labelsInclude <Array<​string>>
  • An array of labels query tests by and run sequentially
• testId
  • The test id to execute
• runId
  • The test run id to pull test info from for local run config. Will pull the environment, credentials, url, etc from that test run.
• url
  • The URL to run the test against
• workspaceId
  * The workspace Id to run the tests in, only needed when using labels as the primary config
  Returns a MablTestRunner. Call the run() function on to run the tests.

MablTestRunner.run() <​Promise>
An asynchronous function that will run all the tests and return the test results.

All times are in milliseconds since the unix epoch.

• Returns: TestResults
  • numFailedTests
  • numPassedTests
  • numSkippedTests
  • numTotalTests
  • testResults <Array<TestResult>>
    • status (passed | failed | skipped)
    • errorMessage
    • testName
    • startTime
    • endTime
  • startTime
  • endTime
  • totalTimeSeconds
    • Total test(s) time in seconds
  • success

TypeScript support

The mabl-cli does include types for use in TypeScript. The types listed above should be available via import in TypeScript. See below for an example:

import {
 createMablTestRunner,
 TestRunConfig,
 TestResults,
} from '@mablhq/mabl-cli';
 
jest.setTimeout(30000);
 
describe('mabl Execution Validation Tests', () => {
 it('Run single test', async () => {
   const testRunConfig: TestRunConfig = {
     testId: 'fb60BEqZa3kXZy1Gj0hAsA-j',
     branchName: 'master',
     headless: true,
   };
   const mablTestRunner = await createMablTestRunner(testRunConfig);
   const result: TestResults = await mablTestRunner.run();
   expect(result.numFailedTests).toEqual(0);
   expect(result.success).toEqual(true);
 });
});