codeWithYoha logo
Code with Yoha
HomeArticlesAboutContact
Log In
Terraform

Robust IaC: Unit Testing Terraform with Terratest for Reliable Deployments

CodeWithYoha
CodeWithYoha17 min read
Robust IaC: Unit Testing Terraform with Terratest for Reliable Deployments

Introduction

In the world of cloud infrastructure, Infrastructure as Code (IaC) has become the gold standard for provisioning and managing resources. Terraform, from HashiCorp, stands out as a leading tool in this domain, allowing teams to define, provision, and manage infrastructure declaratively. While IaC offers immense benefits in terms of consistency, repeatability, and version control, it also introduces a critical challenge: how do you ensure that your infrastructure code works as expected before it's deployed to production?

Untested IaC can lead to costly errors, security vulnerabilities, configuration drift, and unexpected downtime. Just as application code requires rigorous testing, so too does your infrastructure code. This is where automated testing, particularly unit testing, becomes indispensable.

This comprehensive guide will walk you through the process of unit testing your Terraform configurations using Terratest, a powerful Go-based framework. We'll explore why testing IaC is crucial, how Terratest fits into the testing landscape, and provide practical, real-world examples to help you build robust, reliable, and error-free infrastructure deployments.

Why Test Infrastructure as Code?

Testing IaC isn't just a good practice; it's a necessity for any mature DevOps pipeline. Here's why:

  • Prevent Configuration Drift and Errors: Manual changes or incorrect IaC can lead to deviations from the desired state. Automated tests catch these inconsistencies early.
  • Ensure Compliance and Security: Tests can verify that resources adhere to organizational policies, security best practices, and regulatory requirements (e.g., S3 buckets are not public, specific tags are present).
  • Catch Errors Early (Shift-Left): Finding and fixing issues during development or CI/CD is significantly cheaper and faster than discovering them in production.
  • Improve Collaboration and Maintainability: Well-tested modules are easier for team members to understand, refactor, and reuse with confidence.
  • Reduce Manual Intervention and Human Error: Automating tests reduces the need for manual checks, which are prone to human error and time-consuming.
  • Support Refactoring and Upgrades: When you need to refactor a Terraform module or upgrade provider versions, tests provide a safety net, ensuring existing functionality remains intact.
  • Documentation Through Examples: Tests often serve as excellent, executable documentation for how a module is intended to be used and what outputs it produces.

Understanding Terraform and IaC Testing Levels

Terraform allows you to define your infrastructure using a declarative language, HCL (HashiCorp Configuration Language). It manages the lifecycle of resources across various cloud providers (AWS, Azure, GCP), on-premises data centers, and SaaS offerings.

IaC testing isn't a monolithic concept; it comprises different levels, each serving a distinct purpose:

  1. Static Analysis (Linting/Validation):

    • Purpose: Checks code for syntax errors, formatting issues, security vulnerabilities, and adherence to coding standards without deploying any infrastructure.
    • Tools: terraform fmt, terraform validate, tflint, checkov, terrascan.
    • Where it fits: The earliest stage in your CI/CD pipeline.

  2. Unit Testing:

    • Purpose: Verifies individual Terraform modules or resources in isolation. It focuses on ensuring that a single module, given specific inputs, provisions the correct resources with the expected attributes.
    • Tools: Terratest (our focus), Kitchen-Terraform (using Test Kitchen).
    • Where it fits: After static analysis, before integration testing. Often deploys ephemeral infrastructure.

  3. Integration Testing:

    • Purpose: Tests how multiple Terraform modules or resources interact with each other. It ensures that components work together as a cohesive system.
    • Tools: Terratest, custom scripts.
    • Where it fits: After unit testing, often deploying a more complete environment.

  4. End-to-End/Acceptance Testing:

    • Purpose: Validates the entire deployed infrastructure from an end-user perspective, often involving application deployment and functional tests.
    • Tools: Terratest (for deployment), Cypress, Selenium, custom scripts.
    • Where it fits: The final stage, verifying the complete solution.

This guide will primarily focus on unit testing with Terratest, as it's a critical foundation for building reliable IaC modules.

Introducing Terratest: Your IaC Testing Companion

Terratest is an open-source Go library developed by Gruntwork that makes it easier to write automated tests for your infrastructure code. It's designed to:

  • Deploy Infrastructure: Programmatically run terraform init, terraform plan, terraform apply.
  • Validate Infrastructure: Interact with cloud provider APIs (e.g., AWS SDK, Azure SDK, GCP client libraries) to fetch details about deployed resources and assert their properties.
  • Destroy Infrastructure: Programmatically run terraform destroy to clean up resources after tests.
  • Provide Helper Functions: Offers a rich set of helper functions for common tasks across various cloud providers and scenarios.

Terratest's power comes from its ability to orchestrate real-world deployments and then interact with the actual cloud environment to verify the state of resources. This makes it ideal for unit and integration testing where you need to confirm that your Terraform code indeed provisions what you intend.

Prerequisites

Before diving into writing tests, ensure you have the following installed and configured:

  • Go (Golang): Version 1.16 or higher. Terratest is a Go library, and your tests will be written in Go. You can download it from golang.org/dl.
  • Terraform: Version 0.13 or higher. Ensure terraform is in your system's PATH.
  • Cloud Provider CLI/Authentication: Configure your cloud provider credentials (e.g., AWS CLI, Azure CLI, gcloud CLI) with appropriate permissions to create and destroy resources. For AWS, this usually means configuring ~/.aws/credentials or setting environment variables like AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
  • Basic Go and Terraform Knowledge: Familiarity with Go syntax and Terraform concepts (modules, resources, outputs, variables) will be beneficial.

Setting Up Your First Terratest Project

Let's set up a basic project structure. We'll create a simple Terraform module for an S3 bucket and then write a Terratest unit test for it.

Your project directory might look like this:

my-terraform-project/
├── modules/
│   └── s3-bucket/
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf
└── test/
    └── unit/
        └── s3_bucket_test.go

First, let's define our simple s3-bucket module in modules/s3-bucket/:

modules/s3-bucket/main.tf:

resource "aws_s3_bucket" "this" {
  bucket = var.bucket_name
  acl    = var.acl

  tags = merge(
    {
      "Environment" = var.environment
    },
    var.tags
  )

  versioning {
    enabled = var.versioning_enabled
  }

  server_side_encryption_configuration {
    rule {
      apply_server_side_encryption_by_default {
        sse_algorithm = "AES256"
      }
    }
  }
}

modules/s3-bucket/variables.tf:

variable "bucket_name" {
  description = "The name of the S3 bucket."
  type        = string
}

variable "acl" {
  description = "The ACL to apply to the bucket. Must be private or public-read."
  type        = string
  default     = "private"
  validation {
    condition     = contains(["private", "public-read"], var.acl)
    error_message = "ACL must be 'private' or 'public-read'."
  }
}

variable "environment" {
  description = "The environment tag for the bucket."
  type        = string
  default     = "dev"
}

variable "tags" {
  description = "Additional tags to apply to the bucket."
  type        = map(string)
  default     = {}
}

variable "versioning_enabled" {
  description = "Whether to enable versioning for the bucket."
  type        = bool
  default     = true
}

modules/s3-bucket/outputs.tf:

output "bucket_id" {
  description = "The S3 bucket ID."
  value       = aws_s3_bucket.this.id
}

output "bucket_arn" {
  description = "The S3 bucket ARN."
  value       = aws_s3_bucket.this.arn
}

Now, let's initialize our Go test module. Navigate to the test/unit/ directory and run:

go mod init my-terraform-project/test/unit
go get github.com/gruntwork-io/terratest/modules/terraform
go get github.com/gruntwork-io/terratest/modules/aws
go get github.com/stretchr/testify/assert

This creates go.mod and go.sum files and fetches the necessary Terratest and Testify (for assertions) dependencies.

Writing Your First Terratest Unit Test (Simple Resource)

Our goal is to deploy the S3 bucket module, assert its properties (like name, ACL, tags, versioning), and then destroy it. Create s3_bucket_test.go inside test/unit/:

test/unit/s3_bucket_test.go:

package unit

import (
	"fmt"
	"testing"

	"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"
)

func TestS3BucketModule(t *testing.T) {
	// Generate a unique ID for the bucket name to avoid conflicts
	// and ensure test isolation.
	uniqueId := random.UniqueId()
	bucketName := fmt.Sprintf("my-test-bucket-%s", uniqueId)
	awsRegion := "us-east-1" // Specify your desired AWS region

	// Configure Terraform options
	terraformOptions := &terraform.Options{
		// The path to the Terraform module we want to test
		TerraformDir: "../../modules/s3-bucket",

		// Variables to pass to the Terraform module
		Vars: map[string]interface{}{
			"bucket_name":        bucketName,
			"acl":                "private",
			"environment":        "test",
			"tags":               map[string]string{"Project": "Terratest"},
			"versioning_enabled": true,
		},

		// Configure AWS region for the Terraform apply
		EnvVars: map[string]string{
			"AWS_DEFAULT_REGION": awsRegion,
		},
	}

	// At the end of the test, run `terraform destroy` to clean up resources.
	// This is crucial for avoiding resource leaks and unnecessary costs.
	defer terraform.Destroy(t, terraformOptions)

	// Run `terraform init` and `terraform apply`.
	// This will deploy the S3 bucket module to your AWS account.
	terraform.InitAndApply(t, terraformOptions)

	// *** Assertions ***

	// Verify the bucket exists and has the expected properties using AWS SDK helpers.
	bucketExists := aws.IsS3BucketExists(t, awsRegion, bucketName)
	assert.True(t, bucketExists, "Bucket %s should exist", bucketName)

	// Get bucket tags and verify them
	expectedTags := map[string]string{
		"Environment": "test",
		"Project":     "Terratest",
	}
	actualTags := aws.GetS3BucketTags(t, awsRegion, bucketName)
	assert.Equal(t, expectedTags, actualTags, "Bucket tags should match")

	// Verify bucket versioning status
	versioningStatus := aws.GetS3BucketVersioning(t, awsRegion, bucketName)
	assert.Equal(t, "Enabled", versioningStatus, "Bucket versioning should be enabled")

	// Verify server-side encryption
	encryption := aws.GetS3BucketServerSideEncryption(t, awsRegion, bucketName)
	assert.NotNil(t, encryption, "Bucket encryption should be configured")
	assert.Equal(t, "AES256", *encryption.Rules[0].ApplyServerSideEncryptionByDefault.SSEAlgorithm, "Bucket encryption algorithm should be AES256")

	// Retrieve Terraform outputs and assert them
	bucketID := terraform.Output(t, terraformOptions, "bucket_id")
	assert.Equal(t, bucketName, bucketID, "Bucket ID should match bucket name")

	bucketARN := terraform.Output(t, terraformOptions, "bucket_arn")
	assert.Contains(t, bucketARN, fmt.Sprintf("arn:aws:s3:::%s", bucketName), "Bucket ARN should contain bucket name")
}

func TestS3BucketModule_PublicReadACL(t *testing.T) {
	// This test specifically checks the public-read ACL scenario.
	uniqueId := random.UniqueId()
	bucketName := fmt.Sprintf("my-public-bucket-%s", uniqueId)
	awsRegion := "us-east-1"

	terraformOptions := &terraform.Options{
		TerraformDir: "../../modules/s3-bucket",
		Vars: map[string]interface{}{
			"bucket_name": bucketName,
			"acl":         "public-read", // Testing public-read ACL
			"environment": "test-public",
		},
		EnvVars: map[string]string{
			"AWS_DEFAULT_REGION": awsRegion,
		},
	}

	defer terraform.Destroy(t, terraformOptions)

	terraform.InitAndApply(t, terraformOptions)

	// Verify the bucket exists
	assert.True(t, aws.IsS3BucketExists(t, awsRegion, bucketName), "Public bucket %s should exist", bucketName)

	// Note: Directly checking ACL via AWS SDK can be tricky as it's often represented by grants.
	// A more robust test for 'public-read' might involve attempting to read an object anonymously.
	// For simplicity, we'll assume Terraform correctly applies the ACL if no errors during apply.
	// In a real scenario, you might want to create a test object and try to fetch it unauthenticated.

	// Example of checking a tag for this specific test case
	actualTags := aws.GetS3BucketTags(t, awsRegion, bucketName)
	assert.Equal(t, "test-public", actualTags["Environment"], "Public bucket environment tag should be 'test-public'")
}

To run the tests, navigate to test/unit/ and execute:

go test -v -timeout 30m
  • -v: Verbose output, showing each test and its status.
  • -timeout 30m: Sets a timeout of 30 minutes. IaC tests often take longer due to resource provisioning.

Testing Terraform Outputs and Variables

In the previous example, we already demonstrated how to test Terraform outputs: terraform.Output(t, terraformOptions, "output_name") retrieves the value of a specific output from the deployed module. This is crucial for verifying that your module correctly exposes the necessary information.

Passing variables to your module is done via the Vars map in terraform.Options, as shown:

	terraformOptions := &terraform.Options{
		// ...
		Vars: map[string]interface{}{
			"bucket_name":        bucketName,
			"acl":                "private",
			// ... other variables
		},
		// ...
	}

This allows you to test your module with different input configurations, ensuring it behaves correctly under various scenarios. For instance, you might have separate tests for different acl values, encryption settings, or resource counts.

Advanced Unit Testing Scenarios

Terratest goes beyond simple resource verification. Here are a few advanced scenarios:

1. Testing Conditional Resources (Count/For_Each)

If your Terraform module uses count or for_each to create resources conditionally, you'll want to test these conditions. For example, testing an EC2 instance that's only created if a certain variable is true.

Terraform (example main.tf snippet for EC2):

resource "aws_instance" "app_server" {
  count = var.create_instance ? 1 : 0
  ami           = var.ami_id
  instance_type = var.instance_type
  tags = {
    Name = "${var.environment}-app-server"
  }
}

Terratest (example snippet):

func TestEC2InstanceConditionalCreation(t *testing.T) {
	// ... setup uniqueId, region ...

	// Test case 1: create_instance = true
	terraformOptions1 := &terraform.Options{
		TerraformDir: "../../modules/ec2-module",
		Vars: map[string]interface{}{
			"create_instance": true,
			// ... other vars ...
		},
		EnvVars: map[string]string{"AWS_DEFAULT_REGION": awsRegion},
	}
	defer terraform.Destroy(t, terraformOptions1)
	terraform.InitAndApply(t, terraformOptions1)

	// Assert instance exists
	instanceID := terraform.Output(t, terraformOptions1, "instance_id") // Assuming output for instance ID
	assert.NotEmpty(t, instanceID, "Instance ID should not be empty when created")
	assert.True(t, aws.IsEc2InstanceRunning(t, instanceID, awsRegion), "EC2 instance should be running")

	// Test case 2: create_instance = false
	terraformOptions2 := &terraform.Options{
		TerraformDir: "../../modules/ec2-module",
		Vars: map[string]interface{}{
			"create_instance": false,
			// ... other vars ...
		},
		EnvVars: map[string]string{"AWS_DEFAULT_REGION": awsRegion},
	}
	defer terraform.Destroy(t, terraformOptions2) // This destroy might not do anything if no resources are created
	terraform.InitAndApply(t, terraformOptions2)

	// Assert instance does NOT exist (e.g., output is empty or check AWS API)
	instanceID2 := terraform.Output(t, terraformOptions2, "instance_id")
	assert.Empty(t, instanceID2, "Instance ID should be empty when not created")
	// More robust: use AWS SDK to check if instance exists by tag/name, if output isn't reliable for non-existent resources.
}

2. Testing Resource Attributes and Relationships

You can go deeper into resource attributes and relationships. For instance, testing security group rules, IAM policy statements, or subnet associations.

func TestSecurityGroupRules(t *testing.T) {
	// ... setup ...

	terraformOptions := &terraform.Options{
		TerraformDir: "../../modules/vpc-sg-module",
		Vars: map[string]interface{}{
			"vpc_id": "vpc-12345678", // Assume a pre-existing VPC for unit testing SG
			"sg_name": "test-sg",
			"ingress_ports": []int{80, 443},
		},
		EnvVars: map[string]string{"AWS_DEFAULT_REGION": awsRegion},
	}
	defer terraform.Destroy(t, terraformOptions)
	terraform.InitAndApply(t, terraformOptions)

	securityGroupID := terraform.Output(t, terraformOptions, "security_group_id")
	assert.NotEmpty(t, securityGroupID, "Security Group ID should not be empty")

	// Use AWS SDK to fetch security group rules
	ingressRules := aws.Get</li>SecurityGroupIngressRules(t, awsRegion, securityGroupID)
	assert.Contains(t, ingressRules, aws.SecurityGroupRule{FromPort: 80, ToPort: 80, Protocol: "tcp", CidrBlocks: []string{"0.0.0.0/0"}})
	assert.Contains(t, ingressRules, aws.SecurityGroupRule{FromPort: 443, ToPort: 443, Protocol: "tcp", CidrBlocks: []string{"0.0.0.0/0"}})
}

3. Negative Testing (Error Conditions)

Sometimes, you want to ensure your module fails gracefully or as expected when given invalid input. Terratest can help with this by checking for specific error messages or failures during terraform apply.

func TestS3BucketModule_InvalidACL(t *testing.T) {
	uniqueId := random.UniqueId()
	bucketName := fmt.Sprintf("my-invalid-acl-bucket-%s", uniqueId)
	awsRegion := "us-east-1"

	terraformOptions := &terraform.Options{
		TerraformDir: "../../modules/s3-bucket",
		Vars: map[string]interface{}{
			"bucket_name": bucketName,
			"acl":         "invalid-acl", // This should cause a validation error
		},
		EnvVars: map[string]string{"AWS_DEFAULT_REGION": awsRegion},
	}

	// Expect a Terraform error during apply
	_, err := terraform.InitAndApplyE(t, terraformOptions)
	assert.Error(t, err, "Terraform apply should fail for invalid ACL")
	assert.Contains(t, err.Error(), "validation error", "Error message should indicate a validation failure")

	// Assert that the bucket was NOT created
	bucketExists := aws.IsS3BucketExists(t, awsRegion, bucketName)
	assert.False(t, bucketExists, "Bucket should not exist after failed apply")
}

Note the use of terraform.InitAndApplyE, which returns an error, allowing you to assert against it.

Best Practices for Terratest Unit Testing

To maximize the effectiveness and maintainability of your Terratest suite, consider these best practices:

  • Isolation is Key: Each test function (func Test...) should be completely independent. It should provision its own resources, run its assertions, and clean up after itself. This prevents test flakiness and makes debugging easier.
  • Always Clean Up: Use defer terraform.Destroy(t, terraformOptions) at the beginning of your test function. This ensures that resources are reliably destroyed, even if the test fails.
  • Keep Tests Focused: Unit tests should be small and target specific functionality of a module. Avoid monolithic tests that try to validate an entire application stack.
  • Use Unique Identifiers: Append random.UniqueId() to resource names to prevent naming collisions when running tests concurrently or repeatedly.
  • Specify Regions: Explicitly set the AWS/Azure/GCP region in terraform.Options.EnvVars to ensure tests run in a predictable location.
  • Leverage Terratest Helpers: Terratest provides extensive helper functions for interacting with cloud APIs. Use them instead of writing custom API calls.
  • Test Outputs and Inputs: Verify that your module's outputs are correct and that it behaves as expected with different input variables.
  • Version Control Your Tests: Store your test/ directory alongside your modules/ in the same repository. This ensures tests evolve with the code they validate.
  • Readability Over Cleverness: Write clear, concise tests. Future you (or your teammates) will thank you.
  • Fast Feedback: While IaC tests are inherently slower than static analysis, aim to keep unit tests as fast as possible. Avoid deploying large, complex resources unless necessary for integration tests.

Integrating Terratest into Your CI/CD Pipeline

Automating your Terratest runs in a CI/CD pipeline is crucial for continuous validation of your IaC. This ensures that every code change is tested before it can be merged or deployed.

Here's a conceptual GitHub Actions workflow example:

.github/workflows/terratest.yml:

name: Terratest IaC Unit Tests

on: [push, pull_request]

env:
  AWS_REGION: us-east-1

jobs:
  terratest:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.20'

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.5.0 # Or your desired version

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Run Terratest Unit Tests
        working-directory: ./test/unit
        run: go test -v -timeout 45m -parallel 4 # Adjust timeout and parallelism as needed

      # Optional: Add steps for tflint, checkov etc. here

Key considerations for CI/CD integration:

  • Cloud Credentials: Securely provide cloud provider credentials to your CI/CD environment (e.g., GitHub Secrets, GitLab CI/CD Variables, Jenkins Credentials).
  • Permissions: The IAM role or service principal used by the CI/CD pipeline must have sufficient permissions to create, read, and destroy all resources defined in your Terraform modules.
  • Timeouts: IaC provisioning can take time. Set generous timeouts for your go test command.
  • Parallelism: Terratest supports running tests in parallel (-parallel flag with go test). This can significantly speed up your pipeline, provided your tests are truly isolated.
  • Cost Management: Be mindful of the costs associated with ephemeral infrastructure created by tests, especially in high-volume CI/CD environments. Ensure cleanup is robust.

Common Pitfalls and Troubleshooting

Even with the best intentions, you might encounter issues. Here are common pitfalls and how to address them:

  • Resource Leaks: The most common issue. Forgetting defer terraform.Destroy or having tests crash before it's called can leave orphaned resources. Always double-check your defer statements and consider manual cleanup if a test run goes awry.
  • Permissions Issues: "Access Denied" errors from cloud APIs. Verify that the credentials used by your tests (local or CI/CD) have the necessary IAM policies attached.
  • Test Flakiness: Tests that pass sometimes and fail others. This often points to:
    • Lack of Isolation: Tests interfering with each other.
    • Timing Issues: Cloud resources often have eventual consistency. Use Terratest's retry.DoWithRetry or aws.WaitUntil... helpers to wait for resources to reach a stable state.
    • Race Conditions: Multiple tests trying to create resources with the same name (solved by random.UniqueId()).
  • Long Test Times: If tests are too slow, consider:
    • Refactoring: Break down large modules into smaller, more testable units.
    • Targeted Testing: Only deploy the minimal set of resources required for a specific assertion.
    • Parallelization: Use go test -parallel N.
    • Mocking (Advanced): For very complex or expensive external services, you might explore mocking, but Terratest's strength is testing real infrastructure.
  • Dependency on Real Resources: While necessary for unit testing, deploying real resources incurs costs. Monitor your cloud spend closely during development of test suites.
  • State File Conflicts: Ensure each Terratest run uses a unique state file or operates in isolation to prevent conflicts.

Conclusion

Testing Infrastructure as Code is no longer optional; it's a fundamental component of building reliable, secure, and maintainable cloud infrastructure. Terratest provides a powerful and flexible framework to implement robust unit and integration tests for your Terraform configurations.

By embracing automated testing with Terratest, you can:

  • Catch errors early in the development cycle.
  • Ensure consistency and compliance across your environments.
  • Increase confidence in your infrastructure deployments.
  • Accelerate development by providing fast feedback on changes.

Start small, integrate your tests into your CI/CD pipeline, and gradually expand your test coverage. The effort invested in testing your IaC will pay dividends in reduced downtime, improved security, and a more resilient cloud presence. Your infrastructure deserves the same rigorous testing as your application code. Happy testing!

CodewithYoha

Written by

CodewithYoha

Full-Stack Software Engineer with 5+ years of experience in Java, Spring Boot, and cloud architecture across AWS, Azure, and GCP. Writing production-grade engineering patterns for developers who ship real software.

LinkedInGitHub

Related Articles