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).
Copy all the files from the basic terraform example into the
Copy the basic terraform example test into the
To configure dependencies, run:
cd test go mod init "<MODULE_NAME>" go mod tidy
<MODULE_NAME> is the name of your module, typically in the format
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.goand run tests with the
go testcommand. 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.
How can you test this code to be confident it works correctly? Well, let’s think about how you would test it manually:
terraform applyto execute the code.
applyfinishes, check that the output variable says, “Hello, World”.
terraform destroyto clean everything up.
Using Terratest, you can write an automated test that performs the exact same steps! Here’s what the code looks like:
This code does all the steps we mentioned above, including running
terraform apply, reading the
output variable using
terraform output, checking its value is what we expect, and running
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
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)
Let’s now try out a more realistic Terraform example. Here is some Terraform code that deploys a simple web server in AWS:
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 applyto deploy the web server into your AWS account.
applyfinishes, get the IP of the web server by reading the
terraform destroyto clean everything up.
Here’s how we can automate the steps above using Terratest:
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
$ 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 = 22.214.171.124 [...] Making an HTTP GET call to URL http://126.96.36.199:8080 dial tcp 188.8.131.52:8080: getsockopt: connection refused. Sleeping for 5s and will try again. Making an HTTP GET call to URL http://184.108.40.206:8080 dial tcp 220.127.116.11:8080: getsockopt: connection refused. Sleeping for 5s and will try again. Making an HTTP GET call to URL http://18.104.22.168: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:
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
docker buildto build the Docker image.
Here’s how you can use Terratest to automate this process:
Instead of using Terraform helpers, this test code uses Terratest’s Docker helpers to run
and check the contents of the text file. As before, you can run this test using
Terratest also provides helpers for testing your Kubernetes code. For example, here’s a Kubernetes manifest you might want to test:
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
To test this code manually, you would:
kubectl applyto deploy the Docker training webapp.
kubectl deleteto clean everything up.
Here’s how you automate this process with Terratest:
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:
Your entire infrastructure. Defined as code. In about a day.Explore Gruntwork.io