Testing Terraform Modules with Terratest: A Complete Guide

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/assert

Your 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.tf

Fixtures 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-1

Keep 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.

Read more

Start now free