This document provides guidelines and recommendations for testingTerraform for Google Cloud modules and configurations.

Testing Terraform modules and configurations sometimes follows differentpatterns and conventions from testing application code. While testingapplication code primarily involves testing the business logic of applicationsthemselves, fully testing infrastructure code requires deploying real cloudresources to minimize the risk of production failures. There are a fewconsiderations when running Terraform tests:

• Running a Terraform test creates, modifies, and destroys realinfrastructure, so your tests can potentially be time-consuming and expensive.
• You cannot purely unit test an end-to-end architecture. The bestapproach is to break up your architecture into modules and test thoseindividually. The benefits of this approach include faster iterativedevelopment due to faster test runtime, reduced costs for each test, andreduced chances of test failures from factors beyond your control.
• Avoid reusing state if possible. There may be situations where youare testing with configurations that share data with other configurations,but ideally each test should be independent and should not reuse stateacross tests.

Use less expensive test methods first

There are multiple methods that you can use to test Terraform. In ascendingorder of cost, run time, and depth, they include the following:

• Static analysis: Testing the syntax and structure of your configurationwithout deploying any resources, using tools such as compilers, linters,and dry runs. To do so, useterraform validate
• Module integration testing: To ensure that modules work correctly, testindividual modules in isolation. Integration testing for modulesinvolves deploying the module into a test environment and verifying thatexpected resources are created. There are several testing frameworks thatmake it easier to write tests, as follows:
  • Google's blueprint testing framework
  • Terratest
  • Kitchen-Terraform
  • InSpec
  • tftest
• End-to-end testing: By extending the integration testing approach toan entire environment, you can confirm that multiple modules work together.In this approach, deploy all modules that make up the architecture in afresh test environment. Ideally, the test environment is as similar aspossible to your production environment. This is costly but provides thegreatest confidence that changes don't break your production environment.

Start small

Make sure that your tests iteratively build on each other. Consider runningsmaller tests first and then working up to more complex tests, using afail fast approach.

Randomize project IDs and resource names

To avoid naming conflicts, make sure that your configurations have a globallyunique project ID and non-overlapping resource names within each project. To dothis, use namespaces for your resources. Terraform has a built-inrandom provider for this.

Use a separate environment for testing

During testing, many resources are created and deleted. Ensure that theenvironment is isolated from development or production projects to avoidaccidental deletions during resource cleanup. The best approach is to have eachtest create a fresh project or folder. To avoid misconfiguration, considercreating service accounts specifically for each test execution.

Clean up all resources

Testing infrastructure code means that you are deploying actual resources.To avoid incurring charges, consider implementing a clean-up step.

To destroy all remote objects managed by a particular configuration, use theterraform destroy command. Some testing frameworks have a built-in cleanupstep for you. For example, if you are using Terratest, adddefer terraform.Destroy(t, terraformOptions) to your test. If you're using Kitchen-Terraform, delete your workspace usingterraform kitchen deleteWORKSPACE_NAME.

After you run theterraform destroy command, also run additional clean-upprocedures to remove any resources that Terraform failed to destroy. Do this bydeleting any projects used for test execution or by using a tool like theproject_cleanup module.

• Run tests in parallel. Some testing frameworks support runningmultiple Terraform tests simultaneously.
  • For example, with Terratest you can do this by addingt.Parallel() after the test function definition.
• Test in stages. Separate your tests into independent configurationsthat can be tested separately. This approach removes the need to go throughall stages when running a test, and accelerates the iterative developmentcycle.
  • For example, in Kitchen-Terraform, split tests intoseparate suites. When iterating, execute each suite independently.
  • Similarly, using Terratest, wrap each stage of your test withstage(t,STAGE_NAME,CORRESPONDING_TESTFUNCTION).Set environment variables that indicate which tests to run. For example,SKIPSTAGE_NAME="true".
  • Theblueprint testing frameworksupports staged execution.

What's next

• Learn aboutgeneral style and structure best practices for Terraform on Google Cloud.
• Learn aboutbest practices when using Terraform root modules.