Terraform test framework (1.6+) - Commands & Configuration

Introduction

Testing your Terraform code helps catch mistakes before applying changes. Terraform 1.6+ includes a built-in test framework to run automated tests on your infrastructure code.

When you want to verify that your Terraform modules create the expected resources.

When you need to catch errors early before deploying infrastructure.

When you want to automate checks for resource attributes after apply.

When you want to ensure your infrastructure code works as expected after changes.

When you want to integrate infrastructure tests into your CI/CD pipeline.

Config File - main.tf

main.tf

terraform {
  required_version = ">= 1.6"
}

resource "null_resource" "example" {
  provisioner "local-exec" {
    command = "echo Hello Terraform Test"
  }
}

// Test file
// terraform test framework uses *_test.go files, but here is a minimal example
// This file is for demonstration only and should be placed in tests/ folder

This Terraform configuration defines a simple null_resource that runs a local command. It serves as the resource to test.

The terraform block ensures the version is 1.6 or higher to support the test framework.

Tests are written in Go files with *_test.go suffix, typically placed in a tests/ directory alongside your Terraform code.

Commands

Initializes the Terraform working directory and downloads required providers. This step is needed before running any Terraform commands.

Terminal

terraform init

Expected Output

Initializing the backend...



Initializing provider plugins...

- Finding latest version of hashicorp/null...

- Installing hashicorp/null v3.1.0...

- Installed hashicorp/null v3.1.0 (signed by HashiCorp)



Terraform has been successfully initialized!

Applies the Terraform configuration to create the defined resources. The -auto-approve flag skips manual approval to speed up testing.

Terminal

terraform apply -auto-approve

Expected Output

null_resource.example: Creating...

null_resource.example: Provisioning with 'local-exec'...

Hello Terraform Test

null_resource.example: Creation complete after 0s



Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

→

-auto-approve - Automatically approve the apply without prompting

Runs the Terraform test framework to execute automated tests defined for your Terraform code. This checks if your resources behave as expected.

Terminal

terraform test

Expected Output

=== RUN   TestExample

--- PASS: TestExample (0.01s)

PASS

ok  terraform/tests 0.015s

Destroys all resources created by Terraform to clean up after tests. The -auto-approve flag skips manual confirmation.

Terminal

terraform destroy -auto-approve

Expected Output

null_resource.example: Destroying...

null_resource.example: Destruction complete after 0s



Destroy complete! Resources: 1 destroyed.

→

-auto-approve - Automatically approve the destroy without prompting

Key Concept

If you remember nothing else from this pattern, remember: Terraform 1.6+ lets you write and run automated tests to verify your infrastructure code before applying changes.

Common Mistakes

Running terraform test without initializing the directory first

The test framework requires providers and modules to be initialized, or tests will fail to run.

Always run terraform init before terraform test to prepare the working directory.

Not writing test files with the correct *_test.go naming and location

Terraform test framework only detects Go test files with *_test.go suffix in the correct folder.

Place test files in a tests/ folder and name them with *_test.go suffix to be recognized.

Forgetting to clean up resources after tests

Leaving test resources running can cause unexpected costs and clutter your environment.

Run terraform destroy -auto-approve after tests to remove created resources.

Summary

Initialize your Terraform directory with terraform init before running tests.

Apply your Terraform code with terraform apply to create resources for testing.

Run terraform test to execute automated tests on your infrastructure code.

Clean up test resources with terraform destroy to avoid leftover infrastructure.