Testing Terraform Modules with Terratest: A Complete Guide
Terratest is a Go library that lets you write real integration tests for Terraform modules by deploying actual infrastructure and asserting against it. This guide covers setting up Terratest, writing unit and integration tests for AWS/GCP/Azure resources, managing test parallelism and cleanup, and wiring everything into a CI pipeline.
Key Takeaways
Test real infrastructure, not mocks. Terratest deploys actual cloud resources and validates them—catching drift between code and cloud behavior that static analysis misses.
Structure tests in two tiers. Unit tests validate Terraform plan output and module logic without deploying; integration tests deploy and assert on live resources.
Use t.Parallel() carefully. Parallel tests cut suite time dramatically but require unique resource naming (use random suffixes) to avoid collisions.
Always defer cleanup. Call terraform.Destroy() with defer so resources are cleaned up even if assertions panic.
Invest in retry logic. Cloud APIs are eventually consistent—use retry.DoWithRetry for assertions that may not pass immediately after deploy.
Why Terraform Needs Real Tests
Terraform's validate and plan commands catch syntax errors and obvious mistakes, but they cannot tell you whether your module actually produces working infrastructure. A VPC module might plan successfully and still create subnets with overlapping CIDRs, an IAM role with insufficient permissions, or an RDS instance in the wrong subnet group.
Terratest solves this by running Go tests that actually deploy infrastructure, make assertions against the live resources, and then tear everything down. It's slower and costs real money, but it's the only way to verify that your modules work correctly in production-like conditions.
Setting Up Terratest
Terratest requires Go 1.21+. Initialize a Go module in your Terraform repository:
mkdir -p test
cd test
go mod init github.com/your-org/your-repo/test
go get github.com/gruntwork-io/terratest/modules/terraform
go get github.com/gruntwork-io/terratest/modules/aws
go get github.com/gruntwork-io/terratest/modules/retry
go get github.com/gruntwork-io/terratest/modules/random
go get github.com/stretchr/testify/assertYour repository layout should look like:
modules/
vpc/
main.tf
variables.tf
outputs.tf
rds/
main.tf
variables.tf
outputs.tf
test/
go.mod
go.sum
vpc_test.go
rds_test.go
fixtures/
vpc/
main.tf # thin wrapper that calls the module
rds/
main.tfFixtures are minimal Terraform configurations that call your module with test-appropriate values. They exist purely for testing and should not be reused in production.
Writing Your First Integration Test
Here's a complete integration test for a VPC module:
// test/vpc_test.go
package test
import (
"testing"
"fmt"
"github.com/gruntwork-io/terratest/modules/aws"
"github.com/gruntwork-io/terratest/modules/random"
"github.com/gruntwork-io/terratest/modules/terraform"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
func TestVpcModule(t *testing.T) {
t.Parallel()
awsRegion := "us-east-1"
// Unique suffix prevents naming collisions across parallel test runs
uniqueID := random.UniqueId()
vpcName := fmt.Sprintf("test-vpc-%s", uniqueID)
terraformOptions := &terraform.Options{
TerraformDir: "../test/fixtures/vpc",
Vars: map[string]interface{}{
"vpc_name": vpcName,
"cidr_block": "10.0.0.0/16",
"aws_region": awsRegion,
"environment": "test",
},
// Retry on known transient errors
RetryableTerraformErrors: map[string]string{
"RequestError: send request failed": "Transient AWS API error",
},
MaxRetries: 3,
TimeBetweenRetries: 5 * time.Second,
}
// Destroy at end of test, even if assertions panic
defer terraform.Destroy(t, terraformOptions)
// Deploy the module
terraform.InitAndApply(t, terraformOptions)
// Read outputs
vpcID := terraform.Output(t, terraformOptions, "vpc_id")
publicSubnetIDs := terraform.OutputList(t, terraformOptions, "public_subnet_ids")
privateSubnetIDs := terraform.OutputList(t, terraformOptions, "private_subnet_ids")
// Assert VPC exists and has correct configuration
require.NotEmpty(t, vpcID)
vpc := aws.GetVpcById(t, vpcID, awsRegion)
assert.Equal(t, "10.0.0.0/16", aws.GetCidrBlockOfVpc(t, vpc))
// Assert correct number of subnets
assert.Equal(t, 3, len(publicSubnetIDs), "Expected 3 public subnets (one per AZ)")
assert.Equal(t, 3, len(privateSubnetIDs), "Expected 3 private subnets (one per AZ)")
// Assert subnets are in different AZs
publicAZs := getSubnetAZs(t, publicSubnetIDs, awsRegion)
assert.Equal(t, 3, len(uniqueValues(publicAZs)), "Public subnets should span 3 AZs")
// Assert internet gateway is attached
igw := aws.GetInternetGatewayForVpc(t, vpcID, awsRegion)
assert.NotEmpty(t, igw.InternetGatewayId)
}The fixture at test/fixtures/vpc/main.tf is minimal:
variable "vpc_name" {}
variable "cidr_block" {}
variable "aws_region" {}
variable "environment" {}
provider "aws" {
region = var.aws_region
}
module "vpc" {
source = "../../../modules/vpc"
name = var.vpc_name
cidr_block = var.cidr_block
environment = var.environment
}
output "vpc_id" { value = module.vpc.vpc_id }
output "public_subnet_ids" { value = module.vpc.public_subnet_ids }
output "private_subnet_ids" { value = module.vpc.private_subnet_ids }Unit Tests with Plan Assertions
Integration tests are thorough but slow (often 5–15 minutes). For fast feedback during development, use terraform.Plan() and parse the plan output:
func TestVpcModuleUnitPlan(t *testing.T) {
t.Parallel()
terraformOptions := &terraform.Options{
TerraformDir: "../test/fixtures/vpc",
Vars: map[string]interface{}{
"vpc_name": "unit-test-vpc",
"cidr_block": "10.0.0.0/16",
"aws_region": "us-east-1",
"environment": "test",
},
PlanFilePath: "/tmp/vpc-test.plan",
}
// Plan only — no apply
planOutput := terraform.InitAndPlan(t, terraformOptions)
// Assert resource counts
resourceCount := terraform.GetResourceCount(t, planOutput)
assert.Equal(t, 0, resourceCount.Destroy, "Plan should not destroy any resources")
assert.Greater(t, resourceCount.Add, 0, "Plan should add resources")
// Parse structured plan
plan := terraform.InitAndPlanAndShowWithStruct(t, terraformOptions)
// Assert specific resources are planned
vpc := plan.ResourceChangesMap["module.vpc.aws_vpc.main"]
require.NotNil(t, vpc)
assert.Equal(t, "10.0.0.0/16", vpc.Change.After.(map[string]interface{})["cidr_block"])
// Assert tags
tags := vpc.Change.After.(map[string]interface{})["tags"].(map[string]interface{})
assert.Equal(t, "test", tags["Environment"])
}Unit tests run in seconds and give you rapid feedback on plan-level mistakes. Run them on every PR; reserve integration tests for merge to main or nightly schedules.
Testing Multi-Cloud Modules
GCP Example
func TestGcpNetworkModule(t *testing.T) {
t.Parallel()
projectID := os.Getenv("GOOGLE_PROJECT")
region := "us-central1"
networkName := fmt.Sprintf("test-net-%s", random.UniqueId())
terraformOptions := &terraform.Options{
TerraformDir: "../test/fixtures/gcp-network",
Vars: map[string]interface{}{
"project_id": projectID,
"region": region,
"network_name": networkName,
},
}
defer terraform.Destroy(t, terraformOptions)
terraform.InitAndApply(t, terraformOptions)
networkID := terraform.Output(t, terraformOptions, "network_id")
// Use gcloud SDK calls via exec
cmd := shell.Command{
Command: "gcloud",
Args: []string{
"compute", "networks", "describe", networkName,
"--project", projectID,
"--format", "json",
},
}
output := shell.RunCommandAndGetOutput(t, cmd)
var network map[string]interface{}
json.Unmarshal([]byte(output), &network)
assert.Equal(t, "CUSTOM", network["autoCreateSubnetworks"])
assert.NotEmpty(t, networkID)
}Azure Example
func TestAzureResourceGroupModule(t *testing.T) {
t.Parallel()
subscriptionID := os.Getenv("ARM_SUBSCRIPTION_ID")
location := "eastus"
rgName := fmt.Sprintf("test-rg-%s", random.UniqueId())
terraformOptions := &terraform.Options{
TerraformDir: "../test/fixtures/azure-rg",
Vars: map[string]interface{}{
"resource_group_name": rgName,
"location": location,
},
}
defer terraform.Destroy(t, terraformOptions)
terraform.InitAndApply(t, terraformOptions)
// Terratest has Azure helpers too
rg := azure.GetAResourceGroup(t, rgName, subscriptionID)
assert.Equal(t, location, strings.ToLower(*rg.Location))
assert.Equal(t, rgName, *rg.Name)
}Managing Parallelism
Running tests in parallel cuts wall-clock time significantly. The key rules:
1. Always use unique resource names. Use random.UniqueId() or random.UniqueIdWithPrefix() to generate unique names per test run.
2. Cap parallelism at the cloud account's service limits. Too many parallel tests hit API rate limits. Use TestMain to control concurrency:
// test/main_test.go
package test
import (
"os"
"testing"
"golang.org/x/sync/semaphore"
)
var sem = semaphore.NewWeighted(5) // max 5 parallel deployments
func acquireSlot(t *testing.T) {
if err := sem.Acquire(context.Background(), 1); err != nil {
t.Fatal(err)
}
t.Cleanup(func() { sem.Release(1) })
}Call acquireSlot(t) at the start of each test function that actually deploys resources.
3. Use -timeout to prevent runaway tests:
go test -v -timeout 60m ./...Cleanup and State Management
defer terraform.Destroy() handles normal cases, but tests can fail before the defer is registered (e.g., during Init). Add a safety net by tagging all resources with a timestamp and running a separate cleanup job:
# In your module, always require these tags
variable "tags" {
type = map(string)
default = {}
}
locals {
default_tags = {
ManagedBy = "terraform"
CreatedBy = "terratest"
CreatedAt = timestamp()
}
tags = merge(local.default_tags, var.tags)
}Then run a nightly cleanup Lambda or script that destroys resources with CreatedBy=terratest older than 4 hours.
CI Pipeline Integration
Here's a complete GitHub Actions workflow:
# .github/workflows/terraform-tests.yml
name: Terraform Module Tests
on:
pull_request:
paths:
- 'modules/**'
- 'test/**'
push:
branches: [main]
jobs:
unit-tests:
name: Unit Tests (Plan Only)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: hashicorp/setup-terraform@v3
with:
terraform_version: "1.7.0"
- uses: actions/setup-go@v5
with:
go-version: "1.21"
- name: Run unit tests
working-directory: test
run: go test -v -run "Unit" -timeout 10m ./...
env:
AWS_DEFAULT_REGION: us-east-1
integration-tests:
name: Integration Tests
runs-on: ubuntu-latest
needs: unit-tests
if: github.ref == 'refs/heads/main'
environment: test-aws
steps:
- uses: actions/checkout@v4
- uses: hashicorp/setup-terraform@v3
with:
terraform_version: "1.7.0"
- uses: actions/setup-go@v5
with:
go-version: "1.21"
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: ${{ secrets.AWS_TEST_ROLE_ARN }}
aws-region: us-east-1
- name: Run integration tests
working-directory: test
run: go test -v -run "Integration" -timeout 60m -parallel 3 ./...
env:
AWS_DEFAULT_REGION: us-east-1Keep integration tests on main merges only, not every PR—they're slow and cost money. Use unit tests (plan assertions) on every PR for fast feedback.
Test Organization Best Practices
Name tests clearly. Use TestVpcModule_Unit_* and TestVpcModule_Integration_* prefixes to run tiers separately with -run.
Write idempotent tests. Your test should produce the same result if run twice. Never rely on external state from a previous run.
Test error cases. Use terraform.PlanExitCode to assert that invalid inputs cause Terraform to fail:
func TestVpcModule_InvalidCIDR(t *testing.T) {
terraformOptions := &terraform.Options{
TerraformDir: "../test/fixtures/vpc",
Vars: map[string]interface{}{
"cidr_block": "not-a-cidr",
},
}
// Should fail to plan
exitCode := terraform.InitAndPlanWithExitCode(t, terraformOptions)
assert.Equal(t, 1, exitCode)
}Test module composition. Create fixtures that compose multiple modules together—VPC + RDS, VPC + EKS—to catch interface mismatches early.
Common Pitfalls
Not waiting for eventual consistency. Many AWS resources take time to fully propagate. Use retry.DoWithRetry for assertions:
retry.DoWithRetry(t, "Wait for instance to be running", 10, 15*time.Second, func() (string, error) {
instance := aws.GetEc2InstanceById(t, instanceID, region)
if *instance.State.Name != "running" {
return "", fmt.Errorf("instance state: %s", *instance.State.Name)
}
return "running", nil
})Using real account credentials in CI. Use IAM roles with assume-role, not long-lived access keys. Scope the test role to only the resources your modules create.
Forgetting to test outputs. Modules with wrong outputs break every downstream consumer. Test every output your module declares.
Conclusion
Terratest gives you confidence that your Terraform modules work correctly in real cloud environments. The investment is real—Go knowledge, cloud costs, test runtime—but the alternative is discovering module bugs when they're deployed to production. Start with plan-level unit tests for fast feedback, add integration tests for your most critical modules, and build from there. A module with a passing Terratest suite is a module you can confidently publish and reuse.