How to Test Terraform Code – Strategies & Tools

Terraform discovers test files inside your configuration by checking the following extensions:

• .tftest.hcl
• .tftest.json

Every test file is composed of root-level attributes and blocks as follows:

• One or more run blocks
• One or zero variables block
• Zero to many provider blocks.

Terraform carries out run blocks sequentially, mimicking a sequence of Terraform commands being run in the configuration directory. The sequence in which the variables and provider blocks are arranged doesn’t matter, as Terraform evaluates all values within these blocks at the start of the testing process. For clarity, placing your variables and provider blocks at the start of the test file is advisable.

Terraform test file example

The run block command can be either plan or apply, if you omit to add it, the default value is a plan.

Inside the run block, you can have optional variables and assertions, and you can use the variables inside the assertions as you would use a variable inside any terraform configuration by prefixing it with var. Variables can also be defined globally (outside the run block), or just inside the run block for them to be accessed only by that particular run block.

Assertions in run blocks check a condition, and if that condition is failed, it will be presented at the end of the Terraform verification.

You can define how many providers you want and specify them as part of the run block or outside of it.

The terraform test command is used to run all the test files defined in your configuration.

What does the Terraform test command do?

The terraform test command reads the Terraform test files defined in your configuration files by looking at all the files that have the .tftest.json and .tftest.hcl extensions and executes the tests defined in those files. By default, Terraform will search for these files in the current directory and also in the specified testing directory (by default, it is tests).

Terraform test command usage examples

The terraform test command can receive a couple of optional attributes:

• -test-directory=<directory> – overrides the directory that Terraform looks into for test files
• -json – displays JSON output for your testing results
• -verbose – prints out the plan or state for each run block within a test file
• -filter=testfile – will limit the test operation on specific testfiles only

Terraform test command examples

terraform test -filter=tests/my_test.tftest.hcl – this will test only the tests/my_test.tftest.hcl

terraform test -verbose – will print out the plan or state for each run block

terraform test -test-directory=my_tests – will run the tests from the current directory and my_tests directory

As with any code, you should implement some testing strategies to help validate your code and ensure that your changes do not cause any unexpected issues or break existing functionality.

Common Terraform testing strategies include:

• Integration testing
• Unit testing
• End-to-end (E2E) testing
• Linting
• Compliance testing
• Drift testing

In this article, we will take a look at each and how to use them with Terraform code.

Note: New versions of Terraform are placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that expands on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6.

Integration testing

Integration testing involves testing your entire infrastructure configuration, including any dependencies on other resources, to ensure that they work together correctly. Terraform has built-in dependency mapping and management that can be utilized to make sure the changes being made are as expected.

You can use tools like Terratest or Kitchen-Terraform for integration testing.

The following tools can also be used in the workflow, and including them in the CI pipeline will form Integration Testing:

• Terraform fmt — to format the code correctly.
• Terraform validate — to verify the syntax.
• Terraform plan — to verify the config file will work as expected.
• TFLint — to verify the contents of the configuration as well as the syntax and structure, also checks account limits (e.g. that a VM instance type is valid, and that the limit on the number of VMs in Azure has not been reached).
• Kitchen-Terraform — Kitchen-Terraform is an open-source tool that provides a framework for writing automated tests that validate the configuration and behavior of Terraform code, including testing for errors, resource creation, destruction, and validation of outputs. Kitchen-Terraform uses a combination of Ruby, Terraform, and Test Kitchen to spin up infrastructure in a sandbox environment, run tests, and destroy the infrastructure once testing is complete.
• Terratest — Terratest is an open-source testing framework for testing Terraform that can also be used to test Kubernetes, Docker, and Packer, amongst others. Terratest enables automated testing of infrastructure code in a sandbox environment to validate that it meets requirements, functions as expected, and is reliable. Tests are written in Go, and it provides a rich set of testing functions that allow the user to automate the entire testing process, including provisioning resources, running tests, and cleaning up resources. Terratest also provides built-in support for popular testing frameworks like Ginkgo and Gomega.

How to use Terratest

In the Terratest example below, a function is created to test the creation of an Azure storage account in a resource group, and a container in the storage account, then verifies that the storage account and container exist. The resources are then cleaned up after the test is complete.

Unit testing

Unit testing involves testing individual modules or resources in isolation to ensure that they work as expected. This can again be done using tools like Terratest or using Terraform’s built-in testing functionality.

Unit testing with CDKTF

AWS CDK for Terraform (CDKTF) is a flexible open-source framework that provides a high-level object-oriented abstraction on top of Terraform to enable infrastructure-as-code development using popular programming languages such as TypeScript, Python, and Java. To unit test your CDKTF code, you can use a testing framework such as unittest, Jest or Mocha.

In the example below, CDKTF is used with Python to validate the creation of an AWS S3 bucket region, lifecycle rules, and access control policies, using the unittest framework. The stack is deployed using the app.synth() method, which generates the Terraform configuration and applies it to create the S3 bucket.

The next example shows a similar test using Typescript in the Jest framework. The code uses the Jest expect function to compare the actual and expected values of the resource properties.

End-to-End (E2E) testing

End-to-end testing involves testing your infrastructure configuration in a production-like environment to ensure that it works as expected in a real-world scenario. This can be done using tools like Terratest or manual testing in a staging environment.

Continuing with the Azure storage account example, let’s look at how we can use Terratest to implement end-to-end testing.

1. Create a Terraform configuration file that defines an Azure Storage account and container:

main.tf

2. Create a Terratest test file to deploy the Terraform configuration and validate the created Azure Storage account exists, along with testing that the container has the correct name and access type.

storage_test.go

3. Run the test by navigating to the directory where the go file is saved and run the following command.

Contract testing

Contract testing checks if a configuration using a Terraform module gives properly formatted inputs. They verify the compatibility between the expected and actual inputs of a Terraform module, ensuring the module is used as intended by its author.

These tests utilize input validations, along with preconditions and postconditions, to check input combinations and errors, facilitating clear communication from the module creator to the users about the intended use of the module:

In the above example, we ensure that an instance type can be only t2.micro, t2.small or t3.micro.

Mocks

Test mocking is a beta feature that lets you mock providers, resources and datasource for your tests, which lets you use terraform test without creating infrastructure or requiring credentials. They can be only used with terraform test and generate fake data for all the computed attributes.

Mock Providers

Mock Providers are used to create a dummy version of a provider, enabling the testing of Terraform configurations without actual cloud interactions. They can be used instead of a traditional provider block in your test, and they share the global namespace. Terraform won’t distinguish between a real and a mocked provider.

They will be defined with a “mock_provider” entry in your test files like so:

Note: Test mocking is available in Terraform v1.7.0 and later. This feature is in beta.

Overrides

Overrides can modify existing configurations for testing purposes, allowing for the alteration of resource attributes, data source attributes or even provider settings.

Each override block identifies the target—be it a resource, data source, or module—through a target attribute. For modules, an outputs attribute is used within override_module blocks to specify overrides. In contrast, override_resource and override_data blocks use a values attribute to define the overrides for resources and data sources, respectively.

Repeated blocks and nested attributes

Repeated blocks and nested attributes can also be tested with mocks to ensure that configurations with complex structures behave as expected, even when actual resources are not being manipulated.

For example, for every block inside of a resource that supports a dynamic block, you can build mock attributed that will mimic this behavior

Linting

Linting is very important in every programming language and even though HCL is a declarative language, linting can also ensure that your code is written correctly.

In the Terraform context, linting refers to the process of analyzing code to detect syntax errors, enforce style guidelines, and identify potential issues before doing an actual terraform plan. This step is crucial for maintaining code quality and consistency, and it enhances collaboration. Tools designed for Terraform, such as tflint, offer customizable rulesets that cater to different project needs and standards, facilitating the automation of code review processes and integration into CI pipelines.

• Terraform fmt: This is a built-in Terraform command that should be the first port of call. The command formats your Terraform code based on a set of standard formatting rules.

Use terraform fmt -check and terraform validate to format and validate the correctness of your Terraform configuration.

• TFLint: This is a popular open-source tool that checks for syntax errors, best practices, and code style consistency. Once installed, simply run it using the command:

• Checkov: This is an open-source static analysis tool for Terraform that checks for security and compliance issues in your Terraform code. Install it using the Python package manager pip and run it using the command below:

Checkov will identify security issues and provides recommendations for how to fix the issue, along with the location of the relevant code, such as publically accessible storage accounts.

• Terrascan: This open-source tool performs static code analysis to identify security vulnerabilities and compliance violations in Terraform code. Example output is shown below for a publically accessible storage account:

Check out the list of other popular tools used in Terraform-managed deployments.

terraform-compliance enables you to write a set of conditions in YAML files that must be met and test your code against them.

It can easily be installed using pip and run using the command shown below:

For example, the YAML file below specifies that Azure Storage Account should not be publicly accessible:

Terraform will natively test for drift between your code and the real infrastructure when terraform plan is run. Terraform will compare the current state of your infrastructure to the state saved in the state file.

If there are any differences, Terraform will display an execution plan that shows how to update your infrastructure to match your configuration.

You can also make use of driftctl which is a free open-source tool that can report on infrastructure drift. Example output from the tool is shown below:

Periodic monitoring of the IaC-managed infrastructure to proactively check for drifts is a challenge. Drift detection provided by Spacelift helps with identifying and highlighting infrastructure drifts on time. This makes it easy to know what has changed and provides us with the direction to investigate. Configuring a drift monitor is as simple as configuring a cron job. Read more in the documentation.

By combining the testing strategies mentioned in this article and taking a holistic approach, you can ensure that your Terraform code is well-tested and reliable and that changes are deployed quickly and safely.

We encourage you also to explore how Spacelift makes it easy to work with Terraform. If you need any help managing your Terraform infrastructure, building more complex workflows based on Terraform, and managing AWS credentials per run, instead of using a static pair on your local machine, Spacelift is a fantastic tool for this.