Preview environments

Preview, or ephemeral, environments have become an essential part of CI/CD workflows. Software developers typically deploy code changes to such short-lived environments so that the team can perform automated end-to-end testing and manual validation to ensure everything functions and looks as expected early on in the deployment cycle.


Illustration of a CI/CD pipeline with a preview (ephemeral) environment stage.

Let's see how you can use mabl to easily run automated browser and API regression tests against such preview environments. There are two different ways you can set up your mabl environments to run tests against short-lived preview environments depending on your CI/CD workflow.

One mabl environment with multiple deployments

The most common approach is to manually create a single preview environment in mabl and simply override its base URL when creating a deployment event for that environment in mabl using one of the available options. See running tests on deployment for more info how to instrument this..

This approach assumes that you use the same environment variables for each mabl deployment and that you don't need to setup a separate secure tunnel with mabl Link for each deployment.


Environment configuration in mabl.

Most customers with private preview environments will setup a mabl Link Agent on a virtual machine that has network access to all internal preview environments. That way you don't have to install a new Link Agent and wait up to five minutes to establish a secure tunnel for each deployment.

You can see deployment events in mabl by going to the Results page and clicking to see the results by deployment. You can click on individual deployment to see test run details, including various metatadata that is passed from your CI tool such as the code branch and hash of the last code commit triggered the test runs.


Deployment event results in mabl.

Separate mabl environments for each preview deployment

In case you need to establish a separate secure tunnel for each preview environment, or simply need to override environment variables for every deployment, it is best to create separate preview environments with an associated Link Agent for the secure tunneling and then delete those environments from mabl when no longer needed. You can use the mabl CLI to instrument and automate all of this as part of your CI tool deployment steps.

You first need to configure your CI deployment tool to install a Link Agent and the mabl CLI for as part of provisioning a preview environment. You will need to generate an API key of type Link Agent to establish the secure connection. You will then need to generate a separate API key of type mabl CLI for authenticating the CLI. See managing API keys to learn more about API keys.

Next, you can use the mabl CLI to create a corresponding preview environment in mabl with the respective URL, Link Agent name, and variables configured.

mabl auth activate-key <cli-api-key>
mabl environments create --name <environment_name> --application-id <app_id> --app-url <web_url> --workspace-id <mabl_workspace_id> --link <agent_name> --variables <var1:value1, var2:value2> --preview true

You can get the IDs for your mabl applications and workspaces by running the following CLI commands:

mabl applications list
mabl workspaces list

For the Link Agent command option ( --link <agent_name>), you should use the same name that you used during the agent installation at the previous step. This will automatically associate the agent with the newly created environment.

Here's an example of CLI command that will create a preview environment named E0 - preview-0a939aa for a given application.


Creating a preview environment via the CLI.


Environment preview flag

Creating an environment via the CLI with a --preview true flag will indiciate in the system that this is a short-lived environment, but at present this will not be reflected in the user interface. However, we may use this environment flag in the future to better visualize your mabl environments so we encourage you to use it as applicable.

You will be able to see the newly created environment in the mabl app if you go to the Configurations page.


List of applications and environments in the mabl app.

You can also see that the E0 - preview-0a939aa environment has been properly configured with the Link Agent and the passed environment variables by clicking on the pencil next to the name.


mabl environment details.

If you would like to associated the newly created preview environment with other application URLs, you can run the following CLI command for as many applications as you need.

mabl environments urls add <environment_id> --application-id <app_id> --app-url <web_url> --api-url <api_url>

With the preview envirnonment created, you can configure your CI tool to run mabl tests for the deployment. See running tests on deployment for how to do so.

The last step in the process here is to instrument cleaning things up in mabl as you teardown the preview environment in your CI tool. Here it is important that you delete both the environment and the Link Agent from mabl to keep your wokspace clean and free up tunneling infrastucture resources for your new preview environments.


Preview environment teardown

Please, ensure that you clean up the preview environment and Link Agent from mabl when you do so in your CI tool as described below.

To delete those resources you can run the following CLI commands:

mabl environments delete <environment_id>
mabl link-agents delete <link_agent_name>

When you run the command to create an environment, you will get back the environment id that you can store in a CI variable that you pass at this delete step. Deleting the environment will also delete the associated URLs and variables. For the link agent name, make sure to use the same agent name that was associated with that environment during the original creation process.