Terratest — Automated Testing for Infrastructure Code

Introduction

Terratest is a Go testing library by Gruntwork that lets you write automated tests for real infrastructure. Instead of linting templates or mocking APIs, Terratest deploys actual resources — Terraform modules, Kubernetes Helm charts, Packer images — validates that they work, and tears them down. It brings the confidence of integration testing to infrastructure as code.

What Terratest Does

• Deploys real infrastructure using Terraform, Packer, Kubernetes, or Docker during tests
• Validates deployed resources by making HTTP requests, SSH connections, or API calls
• Tears down all resources automatically at the end of each test run
• Provides retry and wait utilities for eventually-consistent cloud resources
• Integrates with standard Go testing so you can use go test and existing CI pipelines

Architecture Overview

Terratest is a Go library that wraps infrastructure CLI tools. A typical test calls terraform.InitAndApply() to provision resources, uses helper functions to verify outputs (e.g., http_helper.HttpGetWithRetry), and defers terraform.Destroy() for cleanup. Tests run as standard Go tests, meaning you get parallel execution, subtests, and standard CI integration for free. Terratest manages retries internally to handle the eventual consistency inherent in cloud APIs.

Self-Hosting & Configuration

• Add Terratest as a Go module dependency: go get github.com/gruntwork-io/terratest
• Structure tests in a test/ directory alongside your Terraform modules
• Set cloud provider credentials via environment variables (AWS_ACCESS_KEY_ID, etc.)
• Use -timeout 30m or longer since infrastructure tests take minutes, not seconds
• Run tests in isolated cloud accounts or namespaces to avoid resource conflicts

Key Features

• Tests real infrastructure, not just templates or plans
• Built-in helpers for HTTP, SSH, AWS, GCP, Azure, Kubernetes, Docker, and Helm
• Automatic retry logic for flaky cloud API responses
• Parallel test execution with Go subtests for faster feedback
• Stage-based testing to skip slow deploy/destroy steps during development

Comparison with Similar Tools

• Terraform plan + manual review — catches syntax errors but not runtime behavior
• Checkov / tflint — static analysis only, cannot verify deployed resources
• Kitchen-Terraform — Ruby-based alternative but smaller community
• Pulumi testing — built into Pulumi but not applicable to Terraform code

FAQ

Q: Does Terratest create real cloud resources? A: Yes, tests deploy real infrastructure to validate behavior, then destroy it afterward.

Q: How much do Terratest runs cost? A: Costs depend on the resources deployed. Most tests create small resources for a few minutes, costing pennies per run.

Q: Can Terratest test Kubernetes manifests? A: Yes, Terratest has helpers for kubectl, Helm, and Kubernetes API calls to deploy and validate workloads.

Q: Does Terratest work with OpenTofu? A: Yes, since OpenTofu is CLI-compatible with Terraform, Terratest works with it by setting the binary path.

Sources

• https://github.com/gruntwork-io/terratest
• https://terratest.gruntwork.io