terraform-test

Terraform Test

Terraform's built-in testing framework enables module authors to validate that configuration updates don't introduce breaking changes. Tests execute against temporary resources, protecting existing infrastructure and state files.

Core Concepts

Test File: A .tftest.hcl or .tftest.json file containing test configuration and run blocks that validate your Terraform configuration.

Test Block: Optional configuration block that defines test-wide settings (available since Terraform 1.6.0).

Run Block: Defines a single test scenario with optional variables, provider configurations, and assertions. Each test file requires at least one run block.

Assert Block: Contains conditions that must evaluate to true for the test to pass. Failed assertions cause the test to fail.

Mock Provider: Simulates provider behavior without creating real infrastructure (available since Terraform 1.7.0).

Test Modes: Tests run in apply mode (default, creates real infrastructure) or plan mode (validates logic without creating resources).

File Structure

Terraform test files use the .tftest.hcl or .tftest.json extension and are typically organized in a tests/ directory. Use clear naming conventions to distinguish between unit tests (plan mode) and integration tests (apply mode):

my-module/
├── main.tf
├── variables.tf
├── outputs.tf
└── tests/
    ├── validation_unit_test.tftest.hcl      # Unit test (plan mode)
    ├── edge_cases_unit_test.tftest.hcl      # Unit test (plan mode)
    └── full_stack_integration_test.tftest.hcl  # Integration test (apply mode - creates real resources)

Test File Components

A test file contains:

• Zero to one test block (configuration settings)
• One to many run blocks (test executions)
• Zero to one variables block (input values)
• Zero to many provider blocks (provider configuration)
• Zero to many mock_provider blocks (mock provider data, since v1.7.0)

Important: The order of variables and provider blocks doesn't matter. Terraform processes all values within these blocks at the beginning of the test operation.