If you treat infrastructure as code, you have to test it like code. Most of us have lived the alternative. You change one input on a shared module, run a quick plan against staging, and merge. A few hours later you learn that the harmless change replaced a database because of a dependency you did not see in the plan. Manual review and eyeballing plan output do not catch that class of regression. Infrastructure needs an automated testing strategy, and Terraform now gives you enough tooling to build a real one.

Why infrastructure code needs testing

Application teams lean on automated tests to catch regressions before a merge. Infrastructure teams often lean on intuition and a manual deploy check instead, which gives you slow feedback and fragile environments.

Testing infrastructure validates your logic, blocks misconfigurations, and speeds up review. Good tests also double as documentation: if someone edits a routing module next year, the tests tell them immediately when they break network isolation. The point is confidence that the code does what you expect, even as provider versions bump and cloud APIs shift under you.

The Terraform testing pyramid

Infrastructure testing works best as a pyramid, same as application testing. The base is fast and cheap and runs constantly. As you move up, tests get more thorough but cost more time and money.

A real strategy uses all three: catch syntax on your machine, validate logic in the pull request, and verify a true deployment before you tag a module version.

Static analysis: catch errors before the cloud does

The base of the pyramid parses your config and looks for problems without ever calling your provider.

Start with terraform validate. It checks syntax, confirms required arguments are present, and makes sure variable references resolve. It has limits, though: it does not know whether an instance type actually exists or whether your tags follow policy.

For the deeper checks, add tflint, a pluggable linter that inspects provider-specific rules. It catches things like an invalid EC2 instance type or deprecated syntax that basic validation misses. Configure it with a .tflint.hcl at the repo root:

1
plugin "terraform" {
2
  enabled = true
3
  preset  = "recommended"
4
}
5

6
plugin "aws" {
7
  enabled = true
8
  version = "0.30.0"
9
  source  = "github.com/terraform-linters/tflint-ruleset-aws"
10
}

Keep the fast checks one command away locally so you run them without thinking:

terraform fmt -recursive
terraform init -backend=false   # no remote state needed just to validate
terraform validate
tflint --init && tflint -f compact

Unit tests with native terraform test

For years, testing Terraform meant reaching for a third-party tool. That changed in Terraform 1.6, which added a native test framework, followed by provider mocking in 1.7. Native tests use HCL, so you do not learn a new language just to test a module.

Tests live in files ending in .tftest.hcl, and terraform test discovers them automatically. A common layout keeps them in a tests/ directory next to the module:

Here is a unit test for a module that builds an S3 bucket name from variables. Because it is a unit test, we do not want to create anything, so command = plan runs the plan in memory and we assert against the planned values.

1
variables {
2
  bucket_prefix = "my-application"
3
  environment   = "prod"
4
}
5

6
run "validates_bucket_name_format" {
7
  command = plan
8

9
  assert {
10
    condition     = aws_s3_bucket.main.bucket == "my-application-prod-bucket"
11
    error_message = "The S3 bucket name did not match the expected naming convention."
12
  }
13
}

terraform test builds the plan and evaluates each assert. If a condition is false, the run fails and prints your message. You can also assert on outputs with a full apply when you want to check computed values that only exist after creation:

1
run "exposes_bucket_arn_output" {
2
  command = apply
3

4
  assert {
5
    condition     = can(regex("^arn:aws:s3:::", output.bucket_arn))
6
    error_message = "bucket_arn output is not a valid S3 ARN."
7
  }
8
}

Mock providers so tests need no cloud credentials

A plan still authenticates to the provider to refresh state and read schemas. To run fully offline, or in CI without credentials, use mock_provider. It returns the real provider schema but generates fake data for computed attributes instead of calling the cloud.

1
mock_provider "aws" {
2
  override_during = plan # generate mock values during the plan phase
3
}
4

5
variables {
6
  bucket_prefix = "test"
7
  environment   = "dev"
8
}
9

10
run "test_with_mocks" {
11
  command = plan
12

13
  assert {
14
    condition     = aws_s3_bucket.main.bucket == "test-dev-bucket"
15
    error_message = "Bucket name mismatch under mocks."
16
  }
17
}

With mocks, Terraform fills computed attributes with placeholders: 0 for numbers, false for booleans, and a random 8-character string for strings. When your logic depends on a specific computed value, pin it with override_resource so the assertion is deterministic:

1
run "uses_known_arn" {
2
  command = plan
3

4
  override_resource {
5
    target = aws_s3_bucket.main
6
    values = {
7
      arn = "arn:aws:s3:::my-application-prod-bucket"
8
    }
9
  }
10

11
  assert {
12
    condition     = aws_s3_bucket.main.arn == "arn:aws:s3:::my-application-prod-bucket"
13
    error_message = "The overridden ARN was not used."
14
  }
15
}

Integration tests with Terratest in Go

Unit tests are fast, but they cannot promise the cloud will accept your config. A plan can pass and still fail on apply because of an IAM permission, a quota, or an API constraint. For real confidence you provision actual resources, check them, and tear them down. Terratest is the standard tool for that, and it runs in Go.

1
package test
2

3
import (
4
  "fmt"
5
  "strings"
6
  "testing"
7

8
  "github.com/gruntwork-io/terratest/modules/random"
9
  "github.com/gruntwork-io/terratest/modules/terraform"
10
  "github.com/stretchr/testify/assert"
11
)
12

13
func TestTerraformAwsInstance(t *testing.T) {
14
  t.Parallel() // run alongside other independent tests
15

16
  // Randomize names so parallel runs never collide.
17
  uniqueID := strings.ToLower(random.UniqueId())
18

19
  terraformOptions := &terraform.Options{
20
    TerraformDir: "../../modules/ec2_instance",
21
    Vars: map[string]interface{}{
22
      "instance_type": "t2.micro",
23
      "name":          fmt.Sprintf("terratest-%s", uniqueID),
24
      "environment":   "testing",
25
    },
26
  }
27

28
  // `defer` guarantees cleanup even if an assertion fails or panics.
29
  defer terraform.Destroy(t, terraformOptions)
30

31
  terraform.InitAndApply(t, terraformOptions)
32

33
  instanceID := terraform.Output(t, terraformOptions, "instance_id")
34
  assert.NotEmpty(t, instanceID, "The EC2 instance ID should not be empty")
35
}

The defer terraform.Destroy(...) line is the important one. In Go, defer runs at the end of the function no matter how it exits, so the resources come down even when the test fails partway through. That is what keeps a failed run from leaving you a bill.

Spinning resources up and down safely

Testing against a real cloud adds real risks. Two tests that create resources with the same name collide. A crashed runner skips the destroy and leaves you paying for idle infrastructure. A few habits keep it safe.

Wire it into GitHub Actions

Tests only help if they run every time. Put the whole pyramid in CI so it fires on every pull request. For cloud auth, do not store long-lived AWS keys as secrets. Use OpenID Connect so the workflow requests short-lived, temporary credentials at run time.

1
name: Terraform Module CI
2

3
on:
4
  pull_request:
5
    paths: ['**/*.tf', '**/*.tftest.hcl', '**/*_test.go']
6

7
# Required for OIDC: let the workflow mint an ID token.
8
permissions:
9
  id-token: write
10
  contents: read
11

12
jobs:
13
  static-and-unit:
14
    name: Format, Lint, Unit Test
15
    runs-on: ubuntu-latest
16
    steps:
17
      - uses: actions/checkout@v4
18
      - uses: hashicorp/setup-terraform@v3
19
        with:
20
          terraform_version: 1.8.0
21
      - name: Check formatting
22
        run: terraform fmt -check -recursive
23
      - uses: terraform-linters/setup-tflint@v4
24
        with:
25
          tflint_version: latest
26
      - name: Lint
27
        run: |
28
          tflint --init
29
          tflint -f compact
30
      - name: Unit tests (mocked, no cloud creds)
31
        run: |
32
          terraform init -backend=false
33
          terraform test
34

35
  integration:
36
    name: Terratest Integration
37
    needs: static-and-unit
38
    runs-on: ubuntu-latest
39
    steps:
40
      - uses: actions/checkout@v4
41
      - name: Configure AWS credentials via OIDC
42
        uses: aws-actions/configure-aws-credentials@v4
43
        with:
44
          role-to-assume: arn:aws:iam::123456789012:role/github-actions-terratest
45
          aws-region: us-east-1
46
      - uses: actions/setup-go@v5
47
        with:
48
          go-version: '1.22'
49
      - name: Run Terratest
50
        working-directory: ./tests/integration
51
        run: go test -v -timeout 45m

With this in place, no broken syntax, failing logic, or apply-blocking error reaches main. Reviewers spend their time on architecture instead of hunting for a misspelled variable.

Frequently Asked Questions

References

• Terraform: Testing Configuration
• Terraform Tests: Provider Mocking
• Terraform 1.7 adds test mocking and config-driven remove
• Terratest (Gruntwork)
• TFLint
• Configuring OpenID Connect in AWS (GitHub Docs)
• cloud-nuke