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:

1. On the module overview screen, click Configure Tests.
2. In the Variables section on the Tests Settings screen, click + Add variable.
3. 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.
4. Click Add variable to save it.

Generated module tests

HCP Terraform can generate test files for any private module in your registry. You can only generate tests one time per module.

To generate tests for your module:

1. On the module overview screen, click Generate tests.
2. Click Confirm. It will take a few minutes to generate your module tests.
3. HCP Terraform displays generated configuration. To download all of the test files, click Download generated tests.
4. Create a tests directory in your configuration.
5. Unzip the downloaded files into the new tests directory.

Generated test files remain available on the module overview page for later retrieval. Click View test files to view and download any previously generated tests.

Organization owners can control this feature on the organization's General Settings page.