A mabl deployment event triggers a run of all plans in a workspace that match the specified conditions, such as application, environment, and plan label. This action can start multiple plans at once or trigger a specific plan to run in just one of its configured environments. 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 are created using the Deployment Event API, which has two endpoints:
- Trigger tests on deployment: this endpoint creates a deployment event
- Get a deployment result summary: this endpoint retrieves the status and results of a deployment event
There are a few different ways you can trigger a deployment event, including:
- From the mabl app
- In the mabl CLI, using the mabl deployments create command
- As part of a CI/CD integration
This guide outlines how to create a deployment event in the mabl app to illustrate how a deployment event works.
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.
- The plan 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 does not run.
Plan with the correct settings to be triggered by a deployment event
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.
Trigger a deployment event
To create a deployment event in the mabl app, go to the new deployment page:
- On the mabl home page, click on the New button in the top-left corner.
- Select deployment to open the new deployment page.
The new deployment page
- Select the environment, the application, or both environment and application from the dropdowns
- Optionally, you may choose one or more plan labels to target specific plans.
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 new deployment page includes additional optional settings for URL overrides, browsers, credentials and headers.
- Click the "Trigger Deploy" button to create the deployment event.
An output page for the deployment event shows the current status of the plan runs that were triggered.
The deployment event output page
Depending on the arguments that you provide, deployment events are capable of triggering a lot of plan runs that will count toward your quota of allotted credits.
If you want to confirm how many plans will run as a result of a deployment event, you can follow the steps outlined in the Previewing the deployment event section.
Curl command builder
You can find another resource for creating deployment events on the API page: Settings > APIs. Below the sections for managing API keys and working with the mabl CLI, there is a section called API documentation. This section includes a curl command builder for building requests to Deployment Event API endpoints:
- Create deployment event
- Get results from a deployment event
Curl command builder on the API page
Create deployment event
When you select the environment, application, and plan labels for the deployment event, a curl command appears at the bottom of the page. Notice that the curl command uses unique IDs to specify the environment and application. These IDs are known as mabl resource IDs.
To create the deployment event, copy and paste the curl command into your terminal and press enter.
Running the curl command returns a JSON response that includes the ID of the deployment event, which ends in -v. You can use the deployment event ID to make a separate call to the Deployment Events API to retrieve results from the deployment event.
Get results from a deployment event
Paste the deployment ID to generate a curl command for retrieving the status of plans that were triggered as a result of the deployment event.
Previewing the deployment event
If you want to see what plans would execute in a deployment event without the risk of accidentally triggering dozens of plans, follow these steps for previewing a deployment event:
- Go the to API page: Settings > API
- In the API documentation section, select "Create deployment event"
- Select your target environment and/or application.
- Add optional settings as needed, including plan labels, URL overrides, and credentials.
- Copy the generated curl command.
- Open a terminal window on your machine.
- Paste the curl command into the terminal.
- Replace the URL with
https://api.mabl.com/events/deployment?preview=true - 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"}
]
}
This sample response lists seven plan IDs, which means that seven plans would run as a result of this deployment event.
Learn more
Understanding deployment events is a crucial step toward achieving coverage at scale. To take your knowledge a step further, consider checking out the following guides on implementing deployment events into your testing workflow: