Terraform Component Testing: Stop Shipping Broken Infrastructure

It was a Tuesday afternoon. A colleague of mine pushed a Terraform change to a shared module — a seemingly innocent update to an S3 bucket's lifecycle policy. Nobody reviewed it too carefully. The terraform plan output was long, the team was busy, and the CI pipeline only ran terraform validate. What happened next? The module had a subtle logical flaw. It quietly disabled versioning on a production bucket that held compliance audit logs. Not deleted entirely — just silently misconfigured. It took three weeks to notice. The auditors noticed first.

This is not a rare story. Across teams I have worked with — from startup microservices to enterprise data platforms — Terraform modules are trusted far more than they are tested. We write hundreds of lines of HCL, peer-review the YAML that triggers the pipeline, and then just… ship it. We test our application code. We test our APIs. But the infrastructure that everything runs on? We hope it works.

That hope is expensive.

Why Testing Terraform Matters?

Think about what Terraform actually does. It provisions real cloud resources — VPCs, IAM roles, RDS instances, load balancers. A bug in your application code throws an exception. A bug in your Terraform module can delete a database, expose a storage bucket to the public internet, or silently misconfigure a security group that your compliance team will find six months later during an audit.

"Infrastructure as Code is not just code. It is a contract with your cloud provider, your security team, and your customers. And like any contract, it should be verified before it is signed."

The traditional approach has been to eyeball the terraform plan output and cross your fingers. That is fine for a one-person project. It is not fine when ten engineers are contributing to a shared module library, when that library is consumed by fifteen product teams, and when those teams are shipping to production daily. At that scale, you need a structured testing strategy — just like you have for your microservices.

This is where Terraform component testing enters the picture.

The IaC Testing Pyramid

Before we get into component testing specifically, it helps to understand where it sits in the broader landscape of infrastructure testing. Much like the classic software testing pyramid, IaC testing has layers — each with different scopes, speeds, and costs.

At the base you have your fastest and cheapest checks — static analysis. These run in seconds, require no cloud credentials, and catch syntax errors, misconfigured variables, and policy violations before anything is deployed. Above that sits component testing, which is the focus of Part 1. Then integration testing, and finally end-to-end smoke tests that validate real deployed environments.

Most teams I see only do the base and the top — static analysis and occasional end-to-end validation. The middle two layers, especially component testing, are almost completely absent. That is the gap we are going to close today.

What is Component Testing in Terraform?

In software development, a component test validates an individual unit of code — a service, a module, a class — in isolation with real dependencies but without deploying the entire application. Terraform component testing is exactly the same idea applied to infrastructure.

For example, imagine you have written a Terraform module that creates a private S3 bucket with versioning enabled, server-side encryption, and a specific lifecycle rule. A component test for this module would actually deploy that bucket to a real cloud environment, verify all those properties are correctly configured, and then tear it all down. No mocking. No dry runs. Real infrastructure, real verification, real cleanup.

This is fundamentally different from terraform validate (which only checks HCL syntax) or terraform plan (which shows intent but not actual cloud-side behaviour). Component testing closes the gap between "I planned to create a private bucket" and "I have confirmed this bucket is actually private."

The Players: Tools You Should Know

The Terraform testing ecosystem has matured significantly over the last two years. You no longer need to stitch together bash scripts and curl calls to verify your infrastructure. Here is a breakdown of the major tools and where each one fits.

My recommendation for most teams: start with Checkov for static security checks — no deployment needed, zero cost, immediate value. Then add terraform test for module-level component tests. Only invest in Terratest when your infrastructure complexity genuinely warrants it — multiple modules interacting, stateful systems, full network topologies.

Real Example #1: Native terraform test

Terraform 1.6 introduced a native testing framework. No external dependencies, no new language to learn — you write .tftest.hcl files alongside your modules and run them with terraform test. Let us walk through a complete real example.

Say your team maintains a reusable module for creating an S3 bucket with standard security hardening — versioning enabled, server-side encryption, all public access blocked. Here is the module:

# modules/s3-secure-bucket/main.tf

resource "aws_s3_bucket" "this" {
  bucket = var.bucket_name
  tags   = { Environment = var.environment, ManagedBy = "terraform" }
}

resource "aws_s3_bucket_versioning" "this" {
  bucket = aws_s3_bucket.this.id
  versioning_configuration { status = "Enabled" }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "this" {
  bucket = aws_s3_bucket.this.id
  rule {
    apply_server_side_encryption_by_default { sse_algorithm = "AES256" }
  }
}

resource "aws_s3_bucket_public_access_block" "this" {
  bucket                  = aws_s3_bucket.this.id
  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

Now here is the component test file, living at modules/s3-secure-bucket/tests/main.tftest.hcl:

# tests/main.tftest.hcl

provider "aws" { region = "ap-southeast-1" }

variables {
  bucket_name = "test-secure-bucket-${uuid()}"  # unique per run
  environment = "test"
}

run "bucket_has_versioning_enabled" {
  command = apply

  assert {
    condition     = aws_s3_bucket_versioning.this.versioning_configuration[0].status == "Enabled"
    error_message = "Versioning must be Enabled — it was not."
  }
}

run "bucket_blocks_all_public_access" {
  command = apply

  assert {
    condition     = aws_s3_bucket_public_access_block.this.block_public_acls == true
    error_message = "Public ACL block must be enabled."
  }
  assert {
    condition     = aws_s3_bucket_public_access_block.this.restrict_public_buckets == true
    error_message = "Public bucket restriction must be enabled."
  }
}

run "bucket_uses_aes256_encryption" {
  command = apply

  assert {
    condition = (
      aws_s3_bucket_server_side_encryption_configuration.this
        .rule[0].apply_server_side_encryption_by_default[0].sse_algorithm == "AES256"
    )
    error_message = "SSE algorithm must be AES256."
  }
}

Run it with two commands:

$ terraform init
$ terraform test

# Output:
tests/main.tftest.hcl... in progress
  run "bucket_has_versioning_enabled"...      pass
  run "bucket_blocks_all_public_access"...   pass
  run "bucket_uses_aes256_encryption"...     pass
tests/main.tftest.hcl... tearing down
tests/main.tftest.hcl... pass

Success! 3 passed, 0 failed.

Real Example #2: Terratest (Go)

Native terraform test is excellent for module-level assertions against Terraform state. But sometimes you need more — you want to actually call the deployed resource's API, verify a web server responds with the right HTTP status code, or confirm that an IAM policy cannot perform an action it should be blocked from. That is where Terratest shines.

For example, imagine you have deployed a module that creates an Auto Scaling Group behind a Load Balancer. With native terraform test, you can verify the ASG configuration object. With Terratest, you can actually hit the load balancer's DNS endpoint and confirm it returns a 200. That is a fundamentally higher level of confidence.

// tests/s3_bucket_test.go
package test

import (
    "testing"
    "github.com/gruntwork-io/terratest/modules/aws"
    "github.com/gruntwork-io/terratest/modules/terraform"
    "github.com/stretchr/testify/assert"
)

func TestS3SecureBucketModule(t *testing.T) {
    t.Parallel()  // Run tests in parallel to save time

    terraformOptions := &terraform.Options{
        TerraformDir: "../modules/s3-secure-bucket",
        Vars: map[string]interface{}{
            "bucket_name":  "terratest-secure-bucket-12345",
            "environment": "test",
        },
    }

    // Always clean up — even if the test panics
    defer terraform.Destroy(t, terraformOptions)
    terraform.InitAndApply(t, terraformOptions)

    bucketName := terraform.Output(t, terraformOptions, "bucket_name")
    awsRegion  := "ap-southeast-1"

    // Assert 1: Versioning via actual AWS SDK call — not trusting TF state
    versioningStatus := aws.GetS3BucketVersioning(t, awsRegion, bucketName)
    assert.Equal(t, "Enabled", versioningStatus)

    // Assert 2: Public access block via AWS SDK
    publicBlock := aws.GetS3BucketPublicAccessBlock(t, awsRegion, bucketName)
    assert.True(t, *publicBlock.BlockPublicAcls)
    assert.True(t, *publicBlock.RestrictPublicBuckets)

    // Assert 3: Encryption algorithm via AWS SDK
    encryption := aws.GetS3BucketEncryption(t, awsRegion, bucketName)
    assert.Equal(t, "AES256",
        *encryption.Rules[0].ApplyServerSideEncryptionByDefault.SSEAlgorithm)
}

The key difference here is the assertion mechanism. With Terratest, you are calling the AWS SDK directly — not trusting Terraform's state file. This matters because Terraform state can drift from reality if someone makes a manual change in the console. Terratest catches that drift. Native terraform test trusts the state object. Both approaches have their place — use the right one for the right situation.

We have covered the "why", the landscape of tools, and two complete working examples. At this point you have everything you need to start writing your first component test today.

But there is a lot more ground to cover. In Part 2, we will go deeper into CI/CD pipeline integration, talk about what is actually worth testing, the common pitfalls I have seen across organisations, and — most excitingly — explore how AI, AI Agents, and RAG-powered systems are beginning to transform how we write, maintain, and evolve Terraform tests. That last section alone is worth the click.