Terraform Test vs Terratest in 2026: When Native Testing Wins

1# tests/s3_bucket.tftest.hcl
2
3# Variables available to all run blocks
4variables {
5  bucket_name = "test-bucket"
6  environment = "test"
7}
8
9# Run block 1: Unit test (plan only, no infrastructure)
10run "validate_bucket_configuration" {
11  command = plan
12
13  assert {
14    condition     = aws_s3_bucket.main.versioning[0].enabled == true
15    error_message = "Versioning must be enabled"
16  }
17
18  assert {
19    condition     = contains(keys(aws_s3_bucket.main.tags), "Environment")
20    error_message = "Environment tag is required"
21  }
22}
23
24# Run block 2: Integration test (deploys real infrastructure)
25run "deploy_and_validate" {
26  command = apply
27
28  assert {
29    condition     = output.bucket_arn != ""
30    error_message = "Bucket ARN should not be empty"
31  }
32}

1terraform test
2# Or with verbose output
3terraform test -verbose

1# tests/mocked.tftest.hcl
2
3# Mock the entire AWS provider
4mock_provider "aws" {
5  mock_resource "aws_s3_bucket" {
6    defaults = {
7      id     = "test-bucket-id"
8      arn    = "arn:aws:s3:::test-bucket"
9      bucket = "test-bucket"
10    }
11  }
12
13  mock_resource "aws_instance" {
14    defaults = {
15      id                = "i-mock12345"
16      private_ip        = "10.0.1.100"
17      availability_zone = "ap-southeast-2a"
18    }
19  }
20
21  mock_data "aws_ami" {
22    defaults = {
23      id           = "ami-mock12345"
24      architecture = "x86_64"
25    }
26  }
27}
28
29run "test_with_mocks" {
30  command = plan
31
32  assert {
33    condition     = aws_instance.web.id == "i-mock12345"
34    error_message = "Mock should provide predictable values"
35  }
36}

1# Override a specific resource
2override_resource {
3  target = aws_instance.database
4  values = {
5    id         = "i-db-override"
6    private_ip = "10.0.2.50"
7  }
8}
9
10# Override a data source
11override_data {
12  target = data.aws_vpc.main
13  values = {
14    id         = "vpc-override123"
15    cidr_block = "10.0.0.0/16"
16  }
17}
18
19# Override an entire module's outputs
20override_module {
21  target = module.networking
22  outputs = {
23    vpc_id     = "vpc-module123"
24    subnet_ids = ["subnet-1", "subnet-2"]
25  }
26}

1run "test_invalid_instance_type" {
2  command = plan
3
4  variables {
5    instance_type = "invalid-garbage"
6  }
7
8  # This test PASSES if the variable validation fails
9  expect_failures = [
10    var.instance_type
11  ]
12}
13
14run "test_missing_required_tag" {
15  command = plan
16
17  variables {
18    tags = {}  # Missing required "Environment" tag
19  }
20
21  expect_failures = [
22    var.tags
23  ]
24}

1# Run tests remotely
2terraform test -cloud-run=app.terraform.io/buun-group/aws-modules/s3

1// test/s3_bucket_test.go
2package test
3
4import (
5    "testing"
6    "github.com/gruntwork-io/terratest/modules/terraform"
7    "github.com/gruntwork-io/terratest/modules/aws"
8    "github.com/stretchr/testify/assert"
9)
10
11func TestS3Bucket(t *testing.T) {
12    t.Parallel()
13
14    terraformOptions := terraform.WithDefaultRetryableErrors(t, &terraform.Options{
15        TerraformDir: "../modules/s3-bucket",
16        Vars: map[string]interface{}{
17            "bucket_name": "test-bucket-" + random.UniqueId(),
18            "environment": "test",
19        },
20    })
21
22    // ALWAYS clean up, even if test fails
23    defer terraform.Destroy(t, terraformOptions)
24
25    // Deploy real infrastructure
26    terraform.InitAndApply(t, terraformOptions)
27
28    // Get outputs
29    bucketName := terraform.Output(t, terraformOptions, "bucket_name")
30    bucketArn := terraform.Output(t, terraformOptions, "bucket_arn")
31
32    // Validate using AWS SDK
33    bucket := aws.GetS3BucketVersioning(t, "ap-southeast-2", bucketName)
34    assert.Equal(t, "Enabled", bucket.Status)
35
36    // More assertions
37    assert.Contains(t, bucketArn, "arn:aws:s3")
38}

1func TestWebServer(t *testing.T) {
2    t.Parallel()
3
4    terraformOptions := &terraform.Options{
5        TerraformDir: "../modules/web-server",
6    }
7
8    defer terraform.Destroy(t, terraformOptions)
9    terraform.InitAndApply(t, terraformOptions)
10
11    // Get the URL from Terraform output
12    url := terraform.Output(t, terraformOptions, "url")
13
14    // Validate with retries (infrastructure takes time to stabilize)
15    http_helper.HttpGetWithRetry(
16        t,
17        url,
18        nil,                    // TLS config
19        200,                    // Expected status
20        "Hello, World!",        // Expected body
21        30,                     // Max retries
22        10 * time.Second,       // Time between retries
23    )
24}

1func TestSSHAccess(t *testing.T) {
2    t.Parallel()
3
4    terraformOptions := &terraform.Options{
5        TerraformDir: "../modules/bastion",
6    }
7
8    defer terraform.Destroy(t, terraformOptions)
9    terraform.InitAndApply(t, terraformOptions)
10
11    publicIP := terraform.Output(t, terraformOptions, "public_ip")
12    keyPair := terraform.Output(t, terraformOptions, "private_key")
13
14    host := ssh.Host{
15        Hostname:    publicIP,
16        SshKeyPair:  keyPair,
17        SshUserName: "ec2-user",
18    }
19
20    // Run command via SSH
21    output := ssh.CheckSshCommand(t, host, "echo 'Hello from Terratest'")
22    assert.Contains(t, output, "Hello from Terratest")
23}

1func TestFullStack(t *testing.T) {
2    t.Parallel()
3
4    // Step 1: Build AMI with Packer
5    packerOptions := &packer.Options{
6        Template: "../packer/app.pkr.hcl",
7        Vars: map[string]string{
8            "aws_region": "ap-southeast-2",
9        },
10    }
11    amiID := packer.BuildArtifact(t, packerOptions)
12    defer aws.DeleteAmiAndAllSnapshots(t, "ap-southeast-2", amiID)
13
14    // Step 2: Deploy infrastructure with Terraform using the AMI
15    terraformOptions := &terraform.Options{
16        TerraformDir: "../terraform",
17        Vars: map[string]interface{}{
18            "ami_id": amiID,
19        },
20    }
21    defer terraform.Destroy(t, terraformOptions)
22    terraform.InitAndApply(t, terraformOptions)
23
24    // Step 3: Deploy app with Kubernetes
25    k8sOptions := k8s.NewKubectlOptions("", "", "default")
26    k8s.KubectlApply(t, k8sOptions, "../k8s/deployment.yaml")
27    defer k8s.KubectlDelete(t, k8sOptions, "../k8s/deployment.yaml")
28
29    // Step 4: Validate everything works together
30    url := terraform.Output(t, terraformOptions, "load_balancer_url")
31    http_helper.HttpGetWithRetry(t, url, nil, 200, "", 30, 10*time.Second)
32}

1# tests/outputs.tftest.hcl
2variables {
3  project_name = "myproject"
4  environment  = "test"
5}
6
7run "verify_output_formats" {
8  command = plan  # No infrastructure created
9
10  # Validate naming convention
11  assert {
12    condition     = can(regex("^myproject-test-", output.resource_name))
13    error_message = "Resource name should follow naming convention"
14  }
15
16  # Validate output is a list
17  assert {
18    condition     = can(tolist(output.availability_zones))
19    error_message = "availability_zones should be a list"
20  }
21
22  # Validate minimum count
23  assert {
24    condition     = length(output.subnet_ids) >= 2
25    error_message = "Should have at least 2 subnets"
26  }
27}

1func TestOutputsAgainstRealInfra(t *testing.T) {
2    terraform.InitAndApply(t, terraformOptions)
3
4    // Get output and validate against actual AWS state
5    bucketName := terraform.Output(t, terraformOptions, "bucket_name")
6
7    // Verify the bucket actually exists and has correct config
8    aws.AssertS3BucketExists(t, "ap-southeast-2", bucketName)
9    versioning := aws.GetS3BucketVersioning(t, "ap-southeast-2", bucketName)
10    assert.Equal(t, "Enabled", versioning.Status)
11}

1terraform fmt -check
2terraform validate

1# Fast mocked tests
2mock_provider "aws" {}
3run "unit_test" { command = plan }

1# Real infrastructure tests
2run "integration_test" { command = apply }

1// Full stack validation with Terratest
2func TestFullStack(t *testing.T) { ... }

1name: Terraform Module Tests
2on:
3  pull_request:
4    paths:
5      - 'modules/**'
6      - 'tests/**'
7
8jobs:
9  unit-tests:
10    runs-on: ubuntu-latest
11    steps:
12      - uses: actions/checkout@v4
13
14      - name: Setup Terraform
15        uses: hashicorp/setup-terraform@v3
16        with:
17          terraform_version: 1.14.0
18
19      - name: Terraform Init
20        run: terraform init
21
22      - name: Run Unit Tests (Mocked)
23        run: terraform test -filter=tests/unit/
24
25  integration-tests:
26    runs-on: ubuntu-latest
27    needs: unit-tests  # Only run if unit tests pass
28    steps:
29      - uses: actions/checkout@v4
30
31      - name: Setup Terraform
32        uses: hashicorp/setup-terraform@v3
33
34      - name: Run Integration Tests
35        run: terraform test -filter=tests/integration/
36        env:
37          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
38          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

1name: Terratest Integration
2on:
3  push:
4    branches: [main]
5  schedule:
6    - cron: '0 6 * * *'  # Daily at 6 AM
7
8jobs:
9  terratest:
10    runs-on: ubuntu-latest
11    steps:
12      - uses: actions/checkout@v4
13
14      - name: Setup Go
15        uses: actions/setup-go@v5
16        with:
17          go-version: '1.22'
18
19      - name: Setup Terraform
20        uses: hashicorp/setup-terraform@v3
21        with:
22          terraform_wrapper: false  # Required for Terratest
23
24      - name: Run Tests
25        run: |
26          cd test
27          go test -v -timeout 60m ./...
28        env:
29          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
30          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

1# .github/workflows/terraform-testing.yml
2name: Complete IaC Testing Pipeline
3
4on:
5  push:
6    branches: [main, develop]
7  pull_request:
8    branches: [main]
9
10jobs:
11  # Stage 1: Static Analysis (Every Commit)
12  static-analysis:
13    runs-on: ubuntu-latest
14    steps:
15      - uses: actions/checkout@v4
16      - uses: hashicorp/setup-terraform@v3
17
18      - name: Format Check
19        run: terraform fmt -check -recursive
20
21      - name: Validate
22        run: |
23          terraform init -backend=false
24          terraform validate
25
26      - name: TFLint
27        uses: terraform-linters/setup-tflint@v4
28        with:
29          tflint_version: latest
30
31      - run: tflint --recursive
32
33  # Stage 2: Security Scanning
34  security-scan:
35    needs: static-analysis
36    runs-on: ubuntu-latest
37    steps:
38      - uses: actions/checkout@v4
39
40      - name: Checkov Scan
41        uses: bridgecrewio/checkov-action@v12
42        with:
43          directory: .
44          framework: terraform
45          output_format: sarif
46
47      - name: tfsec
48        uses: aquasecurity/tfsec-action@v1.0.0
49
50  # Stage 3: Unit Tests (Mocked)
51  unit-tests:
52    needs: static-analysis
53    runs-on: ubuntu-latest
54    steps:
55      - uses: actions/checkout@v4
56      - uses: hashicorp/setup-terraform@v3
57
58      - name: Run Mocked Unit Tests
59        run: terraform test -filter=tests/unit/
60
61  # Stage 4: Integration Tests (Real Infrastructure)
62  integration-tests:
63    needs: [unit-tests, security-scan]
64    if: github.ref == 'refs/heads/main'
65    runs-on: ubuntu-latest
66    environment: testing
67    steps:
68      - uses: actions/checkout@v4
69      - uses: hashicorp/setup-terraform@v3
70
71      - name: Integration Tests
72        run: terraform test -filter=tests/integration/
73        env:
74          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
75          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
76
77  # Stage 5: Terratest E2E (Pre-Release)
78  e2e-tests:
79    needs: integration-tests
80    if: startsWith(github.ref, 'refs/tags/')
81    runs-on: ubuntu-latest
82    steps:
83      - uses: actions/checkout@v4
84      - uses: actions/setup-go@v5
85        with:
86          go-version: '1.22'
87      - uses: hashicorp/setup-terraform@v3
88        with:
89          terraform_wrapper: false
90
91      - name: Terratest Suite
92        run: |
93          cd test
94          go test -v -timeout 90m ./...

1# Install OpenTofu
2brew install opentofu
3
4# Run tests with OpenTofu
5tofu test
6
7# Terratest with OpenTofu
8export TERRATEST_TERRAFORM_BINARY="tofu"
9go test -v ./...

1# tests/security.tftest.hcl
2
3run "verify_encryption_enabled" {
4  command = plan
5
6  assert {
7    condition = alltrue([
8      for bucket in aws_s3_bucket.all :
9        bucket.server_side_encryption_configuration != null
10    ])
11    error_message = "All S3 buckets must have encryption enabled"
12  }
13}
14
15run "verify_public_access_blocked" {
16  command = plan
17
18  assert {
19    condition = alltrue([
20      for bucket in aws_s3_bucket_public_access_block.all :
21        bucket.block_public_acls == true &&
22        bucket.block_public_policy == true
23    ])
24    error_message = "Public access must be blocked on all buckets"
25  }
26}
27
28run "verify_no_hardcoded_secrets" {
29  command = plan
30
31  # Negative test - should fail if secrets detected
32  expect_failures = []
33
34  assert {
35    condition = !can(regex("AKIA[A-Z0-9]{16}", jsonencode(local.all_vars)))
36    error_message = "Potential AWS access key detected in variables"
37  }
38}

1# Run Checkov against your Terraform
2checkov -d . --framework terraform
3
4# Output example
5Passed checks: 42, Failed checks: 3, Skipped checks: 0
6
7Check: CKV_AWS_18: "Ensure the S3 bucket has access logging enabled"
8  FAILED for resource: aws_s3_bucket.data
9  File: /modules/s3/main.tf:1-15
10
11Check: CKV_AWS_145: "Ensure S3 bucket encryption is enabled"
12  PASSED for resource: aws_s3_bucket.data