Triggering tests via API

Mabl deployment event

Mabl has a Deployment Events API endpoint that you can use to trigger tests via API, more commonly known as a mabl deployment event. There are a few different ways you can do this:

A mabl deployment event triggers a run of all plans in a workspace that match the specified conditions, such as environment, application, and plan label. This action can kick off multiple plans at once or can be used to trigger a plan to run in just one of its configured environments. Mabl deployment events are a powerful feature, making it possible to trigger test runs from the CLI and integrate mabl tests into an existing CI/CD workflow.

🚧

Deployment events count toward the monthly quota

Depending on the arguments you provide, deployment events are capable of triggering a lot of plan runs that will count toward your allotted monthly quota of cloud runs. If you want to confirm how many plans will run as a result of a deployment event, you can follow the steps outlined in Previewing the deployment event section.

This guide outlines the basics of deployment events and how you can trigger one from the mabl app.

Configuring plans for deployment events

Deployment events trigger tests at the plan level. In order for a plan to be triggered by a deployment event, it must meet the following criteria:

  • The plan is active (toggled on)
  • It is accepts a deployment trigger (Edit plan > Triggers > Run on deployment)
  • At least one of the tests in the plan is turned on. (If a plan is active, but all of the tests in the plan are turned off, the plan won't run!)

📘

Disabling plans

If you want to exclude a plan from running in the deployment event, you can disable it from the Plan page by toggling it off. The plan will not be able to be run until it is re-enabled.

The New Deployment page

The easiest way to do trigger tests by API is by navigating to the New Deployment page in the app:

  1. Navigate to the Home page in the left-hand navigation.
  2. Click on the "New" button in the top left corner of the page.
  3. Select "deployment." The New Deployment page will appear.
13991399

The New Deployment page

  1. Select an environment and/or application from the dropdowns.
  2. Choose plan label(s) to target specific plans (optional). The New Deployment page includes additional optional settings for URL overrides, browsers, credentials and headers.
  3. Click the "Trigger Deploy" button. An output page for the deployment event page will appear with the current status of the plan runs that were triggered.
22962296

The Deployment Event Output page

👍

Plan labels

You can get the most out of deployment events by leveraging plan labels to define specific test suites, such as regression, targeted regression, smoke, or a certain functionality or feature area.

The API page

Another resource for triggering tests via API can be found in Settings > APIs. The API page includes the following parts:

  1. API keys: a section for managing API keys.
  2. Mabl CLI: a set of copy-paste commands that you can use to install the mabl CLI, trigger a deployment event, and see all available options for triggering deployment events.
  3. API documentation: a resource for the Deployment Events API and the Execution Result API.

📘

Execution Result API

The Execution Result API retrieves the status of plan runs that were triggered as the result of a deployment event. For more information on this endpoint and how it can be integrated into an existing CI/CD pipeline, check out this guide.

The Deployment Events API

The "Deployment Events API" from the API documentation dropdown features a CURL command builder. If you have reviewed the steps to create a deployment event from the New Deployment page, you'll recognize the format.

12941294

To build a deployment events CURL command, you can take the following steps:

  1. Select an environment and/or application from the dropdowns.
  2. Choose plan label(s) to target specific plans (if desired).
  3. Add any additional settings as needed, such as URL overrides, browsers, credentials, headers.

A CURL command will appear at the bottom of the page. Notice that the CURL command uses IDs to specify which environment and application will run. Environment IDs end in -e and application IDs end in -a.

929929

To trigger the deployment event, you'll need to copy and paste the CURL command into your terminal and press enter. Running the CURL command will return a JSON response, which also uses IDs. Here's an example:

{
  "id":"hGVPrLgx10buqYmHMwG8tg-v",
  "application_id":"PD1PsJm9C22f2A2IffSQ-a",
  "workspace_id":"RS2yqNMP9nK9qobpJiZ74Q-w",
  "received_time":1658414999714,
  "triggered_plan_run_summaries":
    [{
      "plan_id":"cLhFR8Fz0Kpsh70zP6EQ3Q-p",
      "plan_run_id":"kCMvtnUOzgiaJmwzE8CUaQ-pr"
    }]
}

The response contains some useful pieces of information:

  • "id": the deployment event ID (ending in -v). Can be used to make API calls to the Execution Result API.
  • "triggered_plan_run_summaries: the plans that were triggered as a result of this deployment event, identified by plan ID (-p), and their plan run IDs (-pr`).

You can check on the results of the deployment event in the mabl app by navigating to Results > By deployment. Click on the received time to view the output of a specific deployment event.

22962296

The Deployment Event Output page.

Previewing the deployment event

You can perform a preview (dry run) of a Deployment Events API call to see what plans would have executed, without actually running them. Use this to quickly fine-tune your configuration and test your integration. To get started, navigate to the API page (Settings > API), select "Deployment Events API" from the API documentation dropdown, and then take the following steps:

  1. Select your target environment and/or application from the fields. Once added, you'll see the additional fields that can be used to build your CURL command.
  2. Add any additional settings as needed, such as plan label(s), URL overrides, and credentials.)
  3. Copy the CURL command that appears at the bottom.
  4. Open a terminal window on your machine.
  5. Paste the CURL command into the terminal.
  6. Replace the URL with https://api.mabl.com/events/deployment?preview=true
  7. Press enter to see the preview.

The "triggered_plan_run_summaries" section in the JSON response shows the plans that would run if you triggered this deployment event. Consider the following response:

{
  "id":"RAV64K2nQJ0GslNVfmtPuQ-v",
  "environment_id":"Ojc0fnJOoTBgSEZSHUCrhQ-e",
  "workspace_id":"RS2yqNMP9nK9qobpJiZ74Q-w",
  "received_time":1658414608812,
  "triggered_plan_run_summaries":[
    {"plan_id":"cLhFR8Fz0Kpsh70zP6EQ3Q-p"},
    {"plan_id":"GASWQXKMiGBXOReVCms2HQ-p"},
    {"plan_id":"AiqbHQaNT0O47lWAYDYWSA-p"},
    {"plan_id":"oqE3sw3QxQhniftVBm7NXw-p"},
    {"plan_id":"RBaecKUQHHAKkfXjTt1g3g-p"},
    {"plan_id":"XH7ww6JQM8zy8bZGLB7Z1g-p"},
    {"plan_id":"w3YwxgVepvEBjWnRkzl10g-p"}
  ]
}

The "triggered_plan_run_summaries" lists seven plan IDs, which means that seven plans would run as a result of this deployment event.

Deployment events API webinar

Watch this webinar featuring mabl's Matthew Stein and James Baldassari for a detailed look at the deployment events API and how to incorporate it into your mabl plans.


Did this page help you?