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.

Test Configuration (.tftest.hcl)

Test Block

The optional test block configures test-wide settings:

test {
  parallel = true  # Enable parallel execution for all run blocks (default: false)
}

Test Block Attributes:

• parallel - Boolean, when set to true, enables parallel execution for all run blocks by default (default: false). Individual run blocks can override this setting.

Run Block

Each run block executes a command against your configuration. Run blocks execute sequentially by default.

Basic Integration Test (Apply Mode - Default):

run "test_instance_creation" {
  command = apply

  assert {
    condition     = aws_instance.example.id != ""
    error_message = "Instance should be created with a valid ID"
  }

  assert {
    condition     = output.instance_public_ip != ""
    error_message = "Instance should have a public IP"
  }
}

Unit Test (Plan Mode):

run "test_default_configuration" {
  command = plan

  assert {
    condition     = aws_instance.example.instance_type == "t2.micro"
    error_message = "Instance type should be t2.micro by default"
  }

  assert {
    condition     = aws_instance.example.tags["Environment"] == "test"
    error_message = "Environment tag should be 'test'"
  }
}

Run Block Attributes:

• command - Either apply (default) or plan
• plan_options - Configure plan behavior (see below)
• variables - Override test-level variable values
• module - Reference alternate modules for testing
• providers - Customize provider availability
• assert - Validation conditions (multiple allowed)
• expect_failures - Specify expected validation failures
• state_key - Manage state file isolation (since v1.9.0)
• parallel - Enable parallel execution when set to true (since v1.9.0)

Plan Options

The plan_options block configures plan command behavior:

run "test_refresh_only" {
  command = plan

  plan_options {
    mode    = refresh-only  # "normal" (default) or "refresh-only"
    refresh = true           # boolean, defaults to true
    replace = [
      aws_instance.example
    ]
    target = [
      aws_instance.example
    ]
  }

  assert {
    condition     = aws_instance.example.instance_type == "t2.micro"
    error_message = "Instance type should be t2.micro"
  }
}

Plan Options Attributes:

• mode - normal (default) or refresh-only
• refresh - Boolean, defaults to true
• replace - List of resource addresses to replace
• target - List of resource addresses to target

Variables Block

Define variables at the test file level (applied to all run blocks) or within individual run blocks.

Important: Variables defined in test files take the highest precedence, overriding environment variables, variables files, or command-line input.

File-Level Variables:

# Applied to all run blocks
variables {
  aws_region    = "us-west-2"
  instance_type = "t2.micro"
  environment   = "test"
}

run "test_with_file_variables" {
  command = plan

  assert {
    condition     = var.aws_region == "us-west-2"
    error_message = "Region should be us-west-2"
  }
}

Run Block Variables (Override File-Level):

variables {
  instance_type = "t2.small"
  environment   = "test"
}

run "test_with_override_variables" {
  command = plan

  # Override file-level variables
  variables {
    instance_type = "t3.large"
  }

  assert {
    condition     = var.instance_type == "t3.large"
    error_message = "Instance type should be overridden to t3.large"
  }
}

Variables Referencing Prior Run Blocks:

run "setup_vpc" {
  command = apply
}

run "test_with_vpc_output" {
  command = plan

  variables {
    vpc_id = run.setup_vpc.vpc_id
  }

  assert {
    condition     = var.vpc_id == run.setup_vpc.vpc_id
    error_message = "VPC ID should match setup_vpc output"
  }
}

Assert Block

Assert blocks validate conditions within run blocks. All assertions must pass for the test to succeed.

Syntax:

assert {
  condition     = <expression>
  error_message = "failure description"
}

Resource Attribute Assertions:

run "test_resource_configuration" {
  command = plan

  assert {
    condition     = aws_s3_bucket.example.bucket == "my-test-bucket"
    error_message = "Bucket name should match expected value"
  }

  assert {
    condition     = aws_s3_bucket.example.versioning[0].enabled == true
    error_message = "Bucket versioning should be enabled"
  }

  assert {
    condition     = length(aws_s3_bucket.example.tags) > 0
    error_message = "Bucket should have at least one tag"
  }
}

Output Validation:

run "test_outputs" {
  command = plan

  assert {
    condition     = output.vpc_id != ""
    error_message = "VPC ID output should not be empty"
  }

  assert {
    condition     = length(output.subnet_ids) == 3
    error_message = "Should create exactly 3 subnets"
  }
}

Referencing Prior Run Block Outputs:

run "create_vpc" {
  command = apply
}

run "validate_vpc_output" {
  command = plan

  assert {
    condition     = run.create_vpc.vpc_id != ""
    error_message = "VPC from previous run should have an ID"
  }
}

Complex Conditions:

run "test_complex_validation" {
  command = plan

  assert {
    condition = alltrue([
      for subnet in aws_subnet.private :
      can(regex("^10\\.0\\.", subnet.cidr_block))
    ])
    error_message = "All private subnets should use 10.0.0.0/8 CIDR range"
  }

  assert {
    condition = alltrue([
      for instance in aws_instance.workers :
      contains(["t2.micro", "t2.small", "t3.micro"], instance.instance_type)
    ])
    error_message = "Worker instances should use approved instance types"
  }
}

Expect Failures Block

Test that certain