Stage 4 · Provision

Terraform at Scale

Terratest Contracts

Go-based Terratest suites, fixture environments, retries, and teardown reliability — testing infrastructure with confidence.

8 min readInfrastructure as CodeProvision

Terratest Overview

Terratest is a Go library by Gruntwork for testing infrastructure. It provisions real infrastructure, validates it, and tears it down. Terratest is the industry standard for Terraform module testing because it tests the actual deployment, not just the configuration.

Gobasic-terratest-structure.go

26 linesLn 1, Col 1Go

The test file imports terraform and assert packages. terraformOptions configures where to find the module and what variables to pass. defer terraform.Destroy ensures cleanup. Assertions validate the outputs.

Test Structure

Test directory structure


tests/
  integration/
    vpc_test.go
    eks_test.go
    rds_test.go
  fixtures/
    basic/
      main.tf
      variables.tf
    complex/
      main.tf
      variables.tf
  go.mod
  go.sum

The tests directory contains Go test files and fixture directories. Each fixture is a minimal Terraform configuration that calls the module under test. The go.mod file manages dependencies.

Gocomplex-test-with-multiple-validations.go

27 linesLn 1, Col 1Go

The test validates multiple aspects of the deployed VPC. terraform.Output reads a single output. terraform.OutputList reads an output that is a list. terraform.OutputAll reads all outputs as a map.

Fixture Environments

tests/fixtures/basic/main.tf


module "vpc" {
  source = "../../../modules/vpc"

  cidr_block         = var.cidr_block
  enable_nat_gateway = var.enable_nat_gateway
}

variable "cidr_block" {
  default = "10.0.0.0/16"
}

variable "enable_nat_gateway" {
  default = true
}

output "vpc_id" {
  value = module.vpc.vpc_id
}

output "private_subnet_ids" {
  value = module.vpc.private_subnet_ids
}

The fixture calls the real module with test-appropriate values. It exposes the outputs that the test will validate. Each fixture can have different configurations for different test scenarios.

Retries and Flaky Tests

Infrastructure tests are inherently flaky — API rate limits, eventual consistency, and transient errors cause failures. Terratest provides retry mechanisms to handle these issues gracefully.

Goretry-logic.go

31 linesLn 1, Col 1Go

WithDefaultRetryableErrors retries on known transient errors. RetryAttempts and RetrySleepInterval control the retry behavior. retry.DoWithRetryableErrors retries custom checks with specific error patterns.

Teardown Reliability

Teardown is the most critical part of Terratest. A failed teardown leaves infrastructure running and billing. Always use defer to ensure destroy runs even when the test fails.

Goreliable-teardown-patterns.go

36 linesLn 1, Col 1Go

defer terraform.Destroy ensures destroy runs even when the test panics. The cleanup function retries destroy up to 3 times with 30-second delays. terraform.DestroyE returns an error instead of failing the test immediately.

Testing Contracts

Gocontract-tests-for-module-outputs.go

26 linesLn 1, Col 1Go

Contract tests verify that module outputs meet specific requirements. They check format, length, and validity. These tests catch breaking changes in module interfaces before they affect consumers.

Run tests in parallel with t.Parallel()

t.Parallel() allows Go to run test functions concurrently. This significantly speeds up test suites with multiple test functions. Each test must have its own terraformOptions and fixture to avoid conflicts.

Tests cost real money

Terratest provisions real cloud resources. A test suite for an EKS module may create VPCs, subnets, and a cluster. Always run tests in a dedicated test account and ensure defer destroy is present.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Stage 4 · Provision

Terraform at Scale

Terratest Contracts

Go-based Terratest suites, fixture environments, retries, and teardown reliability — testing infrastructure with confidence.

8 min readInfrastructure as CodeProvision

Terratest Overview

Gobasic-terratest-structure.go

26 linesLn 1, Col 1Go

Test Structure

Test directory structure


tests/
  integration/
    vpc_test.go
    eks_test.go
    rds_test.go
  fixtures/
    basic/
      main.tf
      variables.tf
    complex/
      main.tf
      variables.tf
  go.mod
  go.sum

The tests directory contains Go test files and fixture directories. Each fixture is a minimal Terraform configuration that calls the module under test. The go.mod file manages dependencies.

Gocomplex-test-with-multiple-validations.go

27 linesLn 1, Col 1Go

The test validates multiple aspects of the deployed VPC. terraform.Output reads a single output. terraform.OutputList reads an output that is a list. terraform.OutputAll reads all outputs as a map.

Fixture Environments

tests/fixtures/basic/main.tf


module "vpc" {
  source = "../../../modules/vpc"

  cidr_block         = var.cidr_block
  enable_nat_gateway = var.enable_nat_gateway
}

variable "cidr_block" {
  default = "10.0.0.0/16"
}

variable "enable_nat_gateway" {
  default = true
}

output "vpc_id" {
  value = module.vpc.vpc_id
}

output "private_subnet_ids" {
  value = module.vpc.private_subnet_ids
}

The fixture calls the real module with test-appropriate values. It exposes the outputs that the test will validate. Each fixture can have different configurations for different test scenarios.

Retries and Flaky Tests

Infrastructure tests are inherently flaky — API rate limits, eventual consistency, and transient errors cause failures. Terratest provides retry mechanisms to handle these issues gracefully.

Goretry-logic.go

31 linesLn 1, Col 1Go

Teardown Reliability

Teardown is the most critical part of Terratest. A failed teardown leaves infrastructure running and billing. Always use defer to ensure destroy runs even when the test fails.

Goreliable-teardown-patterns.go

36 linesLn 1, Col 1Go

Testing Contracts

Gocontract-tests-for-module-outputs.go

26 linesLn 1, Col 1Go

Contract tests verify that module outputs meet specific requirements. They check format, length, and validity. These tests catch breaking changes in module interfaces before they affect consumers.

Run tests in parallel with t.Parallel()

Tests cost real money

Terratest provisions real cloud resources. A test suite for an EKS module may create VPCs, subnets, and a cluster. Always run tests in a dedicated test account and ensure defer destroy is present.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.