Terraform testing is the discipline of proving that a module or configuration behaves correctly before it reaches production, using the native terraform test framework (.tftest.hcl files, generally available since Terraform 1.6) alongside third-party tools like Terratest. It matters because a module is a contract: consumers depend on its inputs, outputs, and resource behavior staying stable, and a silent regression in a shared module can break every downstream configuration that references it at once. The key mental model is that terraform test gives you two speeds for free by swapping one attribute, command = plan runs fast, no-infrastructure unit tests against logical behavior, while command = apply runs slower, real-infrastructure integration tests, and provider mocking (1.7+) lets you get unit-test speed even when your assertions depend on computed, provider-generated values.
What This Cheat Sheet Covers
This topic spans 15 focused tables and 131 indexed concepts. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.
A jump-to index of every table row in this cheat sheet.
An interactive map of every table and concept in this topic.
Table 1: Core Testing Concepts and the terraform test Command
Before writing a single test file, it helps to know what terraform test actually is, what versions unlock which features, and how the CLI command itself behaves when you run it. This table anchors the vocabulary and command surface everything else builds on.
| Concept | Example | Description |
|---|---|---|
terraform test | • Discovers and executes .tftest.hcl/.tftest.json files in the current directory and the tests/ directory• run from the module root, same as plan/apply. | |
tests/validations.tftest.hcl | Terraform always loads files in the root config directory plus the default tests subdirectory; override the latter with -test-directory. | |
terraform test | Each test file maintains its state entirely in memory, separate from any real state file, so running tests never touches your live infrastructure's state. | |
command = apply vs command = plan | By default terraform test creates real infrastructure (integration-style); switching a run's command to plan skips deployment for unit-style logic checks. | |
terraform { required_version = ">= 1.7.0" } | • terraform test itself needs 1.6+• provider mocking needs 1.7+ • native parallel execution needs 1.12+. | |
terraform test -filter=tests/one.tftest.hcl | Limits a run to specific test files; repeatable, useful for splitting slow suites across CI matrix jobs. | |
terraform test -verbose | Prints the full plan or state for every run block as it executes, invaluable while debugging a failing assertion. |