Terratest uses the Go testing framework. To use Terratest, you need to install:
The easiest way to get started with Terratest is to copy one of the examples and its corresponding tests from this repo. This quick start section uses a Terraform example, but check out the Examples section for other types of infrastructure code you can test (e.g., Packer, Kubernetes, etc).
Create an examples and test folder.
Copy the folder including all the files from the basic terraform example into the examples folder.
Copy the basic terraform example test into the test folder.
To configure dependencies, run:
cd test
go mod init "<MODULE_NAME>"
go mod tidy
Where <MODULE_NAME> is the name of your module, typically in the format
github.com/<YOUR_USERNAME>/<YOUR_REPO_NAME>.
To run the tests:
cd test
go test -v -timeout 30m
(See Timeouts and logging for why the -timeout parameter is used.)
The basic usage pattern for writing automated tests with Terratest is to:
_test.go and run tests with the go test command. E.g., go test my_test.go.To make this sort of testing easier, Terratest provides a variety of helper functions and patterns for common infrastructure testing tasks, such as testing Terraform code, testing Packer templates, testing Docker images, executing commands on servers over SSH, making HTTP requests, working with AWS APIs, and so on.
Let’s start with the simplest possible Terraform code, which just outputs the text, “Hello, World” (if you’re new to Terraform, check out our Comprehensive Guide to Terraform):
Loading...How can you test this code to be confident it works correctly? Well, let’s think about how you would test it manually:
terraform init and terraform apply to execute the code.apply finishes, check that the output variable says, “Hello, World”.terraform destroy to clean everything up.Using Terratest, you can write an automated test that performs the exact same steps! Here’s what the code looks like:
Loading...This code does all the steps we mentioned above, including running terraform init, terraform apply, reading the
output variable using terraform output, checking its value is what we expect, and running terraform destroy
(using defer to run it at the end of the test, whether the test
succeeds or fails). If you put this code in a file called terraform_hello_world_example_test.go, you can run it by
executing go test, and you’ll see output that looks like this (truncated for readability):
$ go test -v
=== RUN TestTerraformHelloWorldExample
Running command terraform with args [init]
Initializing provider plugins...
[...]
Terraform has been successfully initialized!
[...]
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
Outputs:
hello_world = "Hello, World!"
[...]
Running command terraform with args [destroy -force -input=false]
[...]
Destroy complete! Resources: 2 destroyed.
--- PASS: TestTerraformHelloWorldExample (149.36s)
Success!
Let’s now try out a more realistic Terraform example. Here is some Terraform code that deploys a simple web server in AWS:
Loading...The code above deploys an EC2 Instance that is running an Ubuntu Amazon Machine Image (AMI). To keep this example simple, we specify a User Data script that, while the server is booting, fires up a dirt-simple web server that returns “Hello, World” on port 8080.
How can you test this code to be confident it works correctly? Well, let’s again think about how you would test it manually:
terraform init and terraform apply to deploy the web server into your AWS account.apply finishes, get the IP of the web server by reading the public_ip output variable.terraform destroy to clean everything up.Here’s how we can automate the steps above using Terratest:
Loading...This test code runs terraform init and terraform apply, reads the server IP using terraform output, makes HTTP
requests to the web server (including plenty of retries to account for the server taking time to boot), checks the HTTP
response is what we expect, and then runs terraform destroy at the end. If you put this code in a file called
terraform_aws_hello_world_example_test.go, you can run just this test by passing the -run argument to go test as
follows:
$ go test -v -run TestTerraformAwsHelloWorldExample -timeout 30m
=== RUN TestTerraformAwsHelloWorldExample
Running command terraform with args [init]
Initializing provider plugins...
[...]
Terraform has been successfully initialized!
[...]
Running command terraform with args [apply -auto-approve]
aws_instance.example: Creating...
associate_public_ip_address: "" => "<computed>"
availability_zone: "" => "<computed>"
ephemeral_block_device.#: "" => "<computed>"
instance_type: "" => "t2.micro"
key_name: "" => "<computed>"
[...]
Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
Outputs:
public_ip = 52.67.41.31
[...]
Making an HTTP GET call to URL http://52.67.41.31:8080
dial tcp 52.67.41.31:8080: getsockopt: connection refused.
Sleeping for 5s and will try again.
Making an HTTP GET call to URL http://52.67.41.31:8080
dial tcp 52.67.41.31:8080: getsockopt: connection refused.
Sleeping for 5s and will try again.
Making an HTTP GET call to URL http://52.67.41.31:8080
Success!
[...]
Running command terraform with args [destroy -force -input=false]
[...]
Destroy complete! Resources: 2 destroyed.
--- PASS: TestTerraformAwsHelloWorldExample (149.36s)
Success! Now, every time you make a change to this Terraform code, the test code can run and make sure your web server works as expected.
Note that in the go test command above, we set -timeout 30m. This is because Go sets a default test time out of 10
minutes, and if your test take longer than that to run, Go will panic, and kill the test code part way through. This is
not only annoying, but also prevents the clean up code from running (the terraform destroy), leaving you with lots of
resources hanging in your AWS account. To prevent this, we always recommend setting a high test timeout; the test above
doesn’t actually take anywhere near 30 minutes (typical runtime is ~3 minutes), but we give lots of extra buffer to be
extra sure that the test always has a chance to finish cleanly.
You can use Terratest for testing a variety of infrastructure code, not just Terraform. For example, you can use it to test your Docker images:
Loading...The Dockerfile above creates a simple Docker image that uses Ubuntu 18.04 as a base and writes the text “Hello, World!”
to a text file. At this point, you should already know the drill. First, let’s think through how you’d test this
Dockerfile manually:
docker build to build the Docker image.docker run.Here’s how you can use Terratest to automate this process:
Loading...Instead of using Terraform helpers, this test code uses Terratest’s Docker helpers to run docker build, docker run,
and check the contents of the text file. As before, you can run this test using go test!
Terratest also provides helpers for testing your Kubernetes code. For example, here’s a Kubernetes manifest you might want to test:
Loading...This manifest deploys the Docker training webapp, a simple app that
responds with the text “Hello, World!”, as a Kubernetes Deployment and exposes it to the outside world on port 5000
using a LoadBalancer.
To test this code manually, you would:
kubectl apply to deploy the Docker training webapp.kubectl delete to clean everything up.Here’s how you automate this process with Terratest:
Loading...The test code above uses Kuberenetes helpers built into Terratest to run kubectl apply, wait for the service to come
up, get the service endpoint, make HTTP requests to the service (with plenty of retries), check the response is what
we expect, and runs kubectl delete at the end. You run this test with go test as well!
The above is just a small taste of what you can do with Terratest. To learn more:
Happy testing!
Your entire infrastructure. Defined as code. In about a day.
Explore Gruntwork.io
Quick start