Testing Terraform
Terraform provides numerous testing capabilities to validate your infrastructure.
The testing capabilities fit into two categories:
- Configuration and infrastructure validation as part of regular Terraform operations.
- More traditional unit and integration testing of your configuration.
The first capability is discussed in detail within the Custom Conditions and Checks language documentation.
The second capability is provided by the Terraform test
command.
A brief history
- Terraform v0.13.0 introduced Input Variable Validation.
- Terraform v0.15.0 introduced an experimental Terraform
test
command. - Terraform v1.2.0 introduced Pre- and Post-conditions.
- Terraform v1.5.0 introduced Checks.
- Terraform v1.6.0 deprecated the experimental Terraform
test
command and released the updated and finalized Terraformtest
command.
The most important takeaway from this history is the introduction and deprecation of the experimental test
command, followed by the introduction of the finalized test
command. Read the v1.6.x Upgrade Guide for a full breakdown of the changes between the experimental and finalized command.
The Terraform test
command
The Terraform test
command:
- Locates Terraform testing files within your configuration directory.
- Provisions the infrastructure within your configuration as specified by each testing file.
- Runs the assertions from the test file against the provisioned infrastructure.
- Destroys the provisioned infrastructure at the end of the test.
The test
command, along with command-line flags and options, is discussed in detail within the Command: test page.
Writing configuration for your tests
Terraform test files have their own configuration syntax. This is discussed in detail within the language Test Files page.
The test file syntax is focused on customizing Terraform executions for the current configuration, and overriding variables and providers to test different behaviours.
Validations
Validations allow you to verify aspects of your configuration and infrastructure as it is applied and created. Terraform Cloud also supports automated Continuous Validation.
The Terraform test
command will also execute all validations within your configuration as part of tests it executes. For more information on the available validations read the Checks and Custom Condition language pages.
Tests or Validations
You can write many validations as test assertions, but there are specific use cases for both.
Validations are executed during usual Terraform plan and apply operations, and are also checked as part of any executed tests. Therefore, validations should be used to validate aspects of your configuration that should always be true and can impact the valid execution of your infrastructure. Module authors should also note that validations are executed and exposed to module users should they fail, and should be understandable to the user and actionable.
In contrast, tests are only executed when requested and can be used to simulate specific behaviours within the configuration. Therefore, tests should be used to assert the correctness of any logical operations or behaviour within your configuration. For example, any conditional resources created based on an input can be verified as part of a test by setting that particular input to true.