TerraformTestFramework
title: Terraform Test Framework radar_quadrant: Techniques radar_ring: Assess radar_position: inner created: 2026-05-22 last_updated: 2026-05-22 related: ["CloudFormationIaCGenerator", "ContinuousIntegration", "JsonnetKubernetesConfig"]
The Terraform Test Framework is a native module testing capability introduced in Terraform 1.6. It allows module authors to write unit and integration tests in HCL using .tftest.hcl files, colocated with the module code they test.
Tests are structured around run blocks that execute either plan or apply against the module under test. Each run block can supply provider overrides, variable values, and one or more assert blocks that validate conditions against the resulting plan or applied state.
run "repository_name_prefix" {
command = apply
assert {
condition = startswith(aws_codecommit_repository.test.repository_name, "repo-")
error_message = "Repository name must start with 'repo-'"
}
}Negative-path testing uses expect_failures to assert that a particular resource or variable validation should fail — useful for verifying that input constraints reject bad values.
Before the native framework, Terratest (a Go library from Gruntwork) was the standard approach for Terraform integration testing. Terratest is powerful but requires writing Go, maintaining a separate test codebase, and managing Go dependencies. The native framework removes those barriers: tests stay in HCL, no new language is required, and terraform test is a first-party command.
The standard pipeline pattern:
terraform init → terraform validate → terraform test → static analysis (Checkov)
terraform test can be run in plan-only mode for fast validation without provisioning real infrastructure, or in apply mode for full integration testing. Plan-mode tests are suitable for PR checks; apply-mode tests run in a dedicated test environment.
Terraform Test Framework sits at Techniques → Assess inner. Native HCL-syntax testing lowers the adoption barrier for IaC quality practices — the friction of learning Terratest or maintaining a Go test suite has been the primary reason Terraform modules go untested. The trial gate is a complete test suite covering at least one module with both positive assertions and expect_failures negative-path tests run in CI.
