terraform test: Usage & Common CI Errors

Terraform’s native testing framework for your modules.

terraform test runs the test files (.tftest.hcl) in your configuration, executing real or mocked plans/applies and asserting on outputs and resource attributes. It is built into Terraform 1.6+.

What it does

terraform test discovers files matching tests/*.tftest.hcl (and *.tftest.hcl in the root), runs each run block as a plan or apply against the module, and checks its assert conditions. By default apply-mode runs create and then destroy real resources, so point tests at a sandbox account.

Common usage

# Run all tests in the module
terraform test

# Run a single test file with extra logging
terraform test -filter=tests/network.tftest.hcl -verbose

# Example tests/main.tftest.hcl
# run "subnet_count" {
#   command = plan
#   assert {
#     condition     = length(aws_subnet.this) == 3
#     error_message = "expected 3 subnets"
#   }
# }

Common error in CI: test command not found / leaked resources

Older runners fail with "Terraform has no command named \"test\"" because terraform test needs 1.6+. Apply-mode tests can also leave resources behind if a run errors mid-test. Fix: pin Terraform >= 1.6 in CI; for assertions that do not need real infra, use command = plan to stay offline and fast; for apply-mode, run against a disposable sandbox so a failed teardown does not litter production, and rely on Terraform’s automatic cleanup ordering.

Key options

Related guides