API-based CI/CD integration

Most mabl customers use mabl's existing integrations or the mabl CLI to integrate end-to-end testing into their DevOps pipeline. However, If none of those options fit your needs, you can use the mabl APIs to run end-to-end tests on code deployment.

Recommended reading

Before integrating mabl into your CI/CD pipeline, please review the different ways to run mabl tests and check out the article on Continuous testing in CI/CD

This article provides you with an example of how to integrate mabl as a step in your CI/CD pipeline using two simple API calls. The first API call will kick off all Plans associated with a particular Environment, Application and/or Labels in response to a new software deployment event. The second API call can be used to check the status of the Plans that were launched as a result of the first API call.

The provided examples assume that you are using a CI build tool like Jenkins, Gitlab, or CircleCI and a Linux-based container which allows you to write custom build steps in bash with standard tools such as curl and jq. If you are using a different type of build tool you may need to adapt these examples.

Hypothetical CI/CD workflow

Let's assume that your team has an automated CI/CD workflow into which you want to integrate end-to-end testing with mabl. As an example, consider the following simple pipeline which represents part of a CI/CD workflow:

Deployment Events API

The first step in adding mabl to your CI/CD flow is to notify mabl when you deploy your application using the Deployment Events API. When you invoke the Deployment Events API mabl will search for all plans associated with the specified Environment, Application and/or Labels that contain a Deployment trigger, and then it will execute those Plans immediately.

Add a "deployment" trigger to any plans that you want to run after a deployment

Before you can get started with the Deployment Event API you'll need a few pieces of information:

  • Your workspace's API key, and
  • One of the following IDs:
    • mabl Environment ID
    • mabl Application ID
    • mabl Environment ID and/or Application ID and/or Plan Labels

Labels are a great way to organize your mabl Plans and you can pass them as parameters to the API for more granular control over which Plans get executed. However, we recommend starting with just an Environment ID for simplicity.

The easiest way to learn how to use the Deployment Event API is by navigating to Settings => APIs in mabl and selecting Deployment Events API under the API documentation section. You can then select a mabl Environment and see the resulting curl command for invoking the Deployment Events API:

Interactive API Reference

You can also play with the APIs using the interactive API reference.

In addition to the minimal environment_id property, you can also pass other reference information associated with the deployment event. Here is a more complete example of a JSON message that can be passed to the API:

    repository_branch_name: 'master',
    repository_commit_username: 'mablcoder',
    repository_url: '[email protected]:mycompany/myrepo.git',
    repository_pull_request_url: 'https://github.com/mycompany/myrepo/pull/1013',
    repository_pull_request_number: 1013,
    repository_pull_request_title: 'good pr'

The revision, event_time, and properties attributes are all optional. Here is a quick description of what each of these mean:

  • revision: The SCM revision associated with the deployment, e.g. a git hash
  • event_time: The time when the deployment event occurred, as a UNIX epoch timestamp in milliseconds. It may be desirable to pass this if there is a delay between when the deployment occurs and the Deployment Events API is invoked
  • properties: Arbitrary map of key-value pairs. You can put any additional information here. There are a few standard properties that mabl recognizes and associates special meaning with. Many of our native integrations provide these properties by default. They are...
    • repository_branch_name: The code branch this deployment was build from.
    • repository_commit_username: The username of the user who committed the code being deployed
    • repository_url: The url of the code repository that triggered this deployment
    • repository_pull_request_url: The url of the pull request that triggered this deployment.
    • repository_pull_request_number: The number of the pull request that triggered this deployment.
    • repository_pull_request_title: The title of the pull request that triggered this deployment.

When you invoke the Deployment Events API you will get a JSON message back containing an event ID and some other information. For example, it might look like this:

  "id": "OCn2EccmXk9eFvRInTfwkQ-v",
  "environment_id": "dbd62e2e-bbbc-4c15-ab7c-72aa0ce379fe",
  "received_time": 1522777753410

The most important part of the response is the id field. The event ID will need to be used later when we want to retrieve the results of the executions that were kicked off my our deployment event.

Execution Result API

After a Deployment Event has been created, the status of Plans that were launched as a result of that event can be interrogated using the Execution Result API. In order to use the Execution Result API you must first have a Deployment Event ID (see Deployment Events API above).

Just like the Deployment Events API, the easiest way to learn about the Execution Result API is to use the curl builder in mabl. Navigate to Settings => APIs, and select Execution Result API under the API documentation section.

The Execution Result API will return a JSON object containing summary information about all Plans and tests that were executed including detailed information about each one. Here is an example response:

  "event_status": {
    "succeeded": true,
    "succeeded_first_attempt": true
  "plan_execution_metrics": {
    "total": 1,
    "passed": 1,
    "failed": 0
  "journey_execution_metrics": {
    "total": 1,
    "passed": 1,
    "failed": 0
  "executions": [
      "status": "succeeded",
      "success": true,
      "plan": {
        "id": "c953e3e3-a195-4b36-bdf8-49ec73ee3d35",
        "name": "Verify home page load and login",
        "label": "regression",
        "href": "https://api.mabl.com/schedule/runPolicy/c953e3e3-a195-4b36-bdf8-49ec73ee3d35",
        "app_href": "https://app.mabl.com/workspaces/5bf0ebb1-f158-4c02-9e71-1be9f6ce7d17/test/plans/c953e3e3-a195-4b36-bdf8-49ec73ee3d35"
      "plan_execution": {
        "id": "I9wjeolJE-iuvOmCSF28Lw-pe",
        "status": "succeeded",
        "href": "https://api.mabl.com/execution/runPolicyExecution/c953e3e3-a195-4b36-bdf8-49ec73ee3d35"
      "journeys": [
          "id": "6b194f04-1ea0-45f1-8a1a-04c9338067d9:0",
          "name": "Visit home page",
          "href": "https://api.mabl.com/execution/runPolicyExecution/I9wjeolJE-iuvOmCSF28Lw-pe/testScriptExecution/6b194f04-1ea0-45f1-8a1a-04c9338067d9:0",
          "app_href": "https://app.mabl.com/workspaces/5bf0ebb1-f158-4c02-9e71-1be9f6ce7d17/test/plan-executions/I9wjeolJE-iuvOmCSF28Lw-pe/journeys/6b194f04-1ea0-45f1-8a1a-04c9338067d9:0"
      "journey_executions": [
          "journey_id": "6b194f04-1ea0-45f1-8a1a-04c9338067d9:0",
          "journey_execution_id": "6b194f04-1ea0-45f1-8a1a-04c9338067d9:0",
          "status": "completed",
          "success": true,
          "href": "https://api.mabl.com/test/journey/6b194f04-1ea0-45f1-8a1a-04c9338067d9:0",
          "app_href": "https://app.mabl.com/workspaces/5bf0ebb1-f158-4c02-9e71-1be9f6ce7d17/train/journeys/6b194f04-1ea0-45f1-8a1a-04c9338067d9:0",
          "test_cases": [
              "id": "MABL-1234"
              "id": "MABL-999"
      "start_time": 1522777753987,
      "stop_time": 1522777997841

For most purposes it should be sufficient to process only the summary information under plan_execution_metrics and journey_execution_metrics. Any output field named app_href contains a link to the mabl UI that may be used to directly view an entity or the results of an execution.

Tests used to be called Journeys

Our API response still reflects the old term "Journey."

Inserting mabl into your pipeline

One option for inserting mabl into your CI/CD pipeline would be to:

  1. Kick off certain Plans when a deployment occurs to a particular environment using the Deployment Events API
  2. Poll the Execution Result API until all plans have either passed or failed

Using the earlier pipeline example, it might look something like this:

Tying it all together

Below is a bash script that can be used to trigger a deployment event and then poll the executions until they either complete or fail. Of course you will need to substitute your own API key and environment ID before using or adapting this example.

Be sure to replace 'api-key' and 'environment-id' below with your own API key and environment ID.



if [ "$#" -ne 2 ]; then
  echo "Usage: $0 <api-key> <environment-id>"
  exit 0


# Create a deployment event, and retrieve its ID:
deployment_event=$(curl -s "${MABL_API_BASE}/events/deployment" -u "key:${API_KEY}" -H 'Content-Type:application/json' -d "{\"environment_id\":\"${ENV_ID}\"}")
event_id=$(echo "${deployment_event}" | jq -r '.id')
echo "Deployment Event ID: ${event_id}"

# Poll the Execution Result API until all Plans have completed
while true; do
  echo "Waiting for executions to complete..."
  sleep ${POLL_SEC}
  results=$(curl -s "${MABL_API_BASE}/execution/result/event/${event_id}" -u "key:${API_KEY}")
  event_status=$(echo "${results}" | jq '.event_status')
  if [ -z "${event_status}" ] || [ "${event_status}" = "{}" ]; then

  plan_metrics=$(echo "${results}" | jq '.plan_execution_metrics')
  if [ "${plan_metrics}" != "null" ]; then
    total_plans=$(echo "${plan_metrics}" | jq -r '.total')
    passed_plans=$(echo "${plan_metrics}" | jq -r '.passed')
    failed_plans=$(echo "${plan_metrics}" | jq -r '.failed')

  succeded=$(echo "${event_status}" | jq -r '.succeeded')
  succeded_with_retries=$(echo "${event_status}" | jq -r '.succeeded_with_retries')

# Print summary:
echo "Full Results:"
echo "${results}" | jq
echo "Total plans executed: ${total_plans} succeded: ${passed_plans} failed: ${failed_plans}"
if [ "${succeded}" = "true" ]; then
  if [ "${succeded_with_retries}" = "true" ]; then
    echo "Successful run with retries"
    echo "Successful run"
  exit 0
  echo "One or more plans have failed"
  exit 1

Updated 8 months ago

API-based CI/CD integration

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.