Test-integrated modules in the HCP Terraform private registry

You can configure HCP Terraform to automatically run tests for modules in your private registry. When enabled, HCP Terraform will run tests for every commit to the designated branch. This lets you verify that it is safe to publish new module versions.

Enable testing

If your module uses the branch-based publishing workflow and its source code includes tests, you can enable testing at any time.

To enable testing when you publish your module:

Choose the Branch module publishing type
Assign a branch and a module version
Under testing, click the Enable testing for module checkbox
Click Publish module

To enable testing after you publishing your branch-based module:

Navigate to the module overview screen
Click Configure Tests to open the Tests Settings screen
Click Enable testing for module

Run tests remotely from the CLI

After publishing and enabling testing for your module, you can use the Terraform CLI locally to trigger remotely-executed tests in HCP Terraform. This lets you test your module changes using the credentials configured in HCP Terraform without committing your changes to version control.

To run your tests remotely, use the -cloud-run flag with the path to your module in your private registry.

terraform test -cloud-run=app.terraform.io/:ORG/:MODULE_NAME/:PROVIDER

Configure environment variables

You can define test-specific environment variables that HCP Terraform will use for testing. If your tests provision infrastructure, you must configure provider credentials for the module.

To add environment variables to your module's tests:

On the module overview screen, click Configure Tests.
In the Variables section on the Tests Settings screen, click + Add variable.
Provide a Key and Value for your environment variable, and if you want to protect the variable's value, click the Sensitive checkbox. TF_VAR_x variables of a string type that are not defined in a config must be wrapped in double-quotes.
Click Add variable to save it.