The terraform test Framework

Terraform 1.6 shipped a built-in test framework, and it changed what testing infrastructure code looks like. You write tests in HCL in .tftest.hcl files, each containing run blocks that execute a plan or an apply against your configuration and assert blocks that check the results. No external language, no Go, no separate harness — the tests live next to the module and run with terraform test.

The question this answers is the one every module author has: does this module actually create what it claims, do its variable validations fire when they should, does it behave correctly across the input combinations people will throw at it. Before 1.6 you reached for Terratest in Go or hoped a careful plan review would catch regressions. Now the assertions are first-class, version-controlled HCL that runs in CI on every change to the module.

The Framework

A test file is a sequence of run blocks. Each run sets variables, runs either a plan or an apply, and asserts on outputs and resource attributes. Runs in one file execute in order and share state, so a later run can build on what an earlier one created. The assertion is a condition that must be true and an error_message printed when it is not — the same shape as a variable validation.

run "sets_bucket_name_from_prefix" {
  command = plan

  variables {
    name_prefix = "acme-prod"
  }

  assert {
    condition     = aws_s3_bucket.this.bucket == "acme-prod-logs"
    error_message = "bucket name must be the prefix plus -logs"
  }
}

command = plan makes this run compute a plan and assert against the planned values without creating anything. The test passes if the module would name the bucket acme-prod-logs given that prefix, and fails with a clear message if the naming logic regresses.

Plan vs Apply Tests

Every run chooses command = plan or command = apply, and the difference is the whole cost model. A plan test computes the diff and asserts on planned values — it is fast, free, and creates no real resources, so it verifies the config's intended shape and logic. An apply test actually creates the infrastructure, asserts that it works end to end, then destroys it — which costs time, money, and demands reliable cleanup. Plan tests are the broad base of the pyramid; apply tests are the narrow, expensive top reserved for critical paths.

Mocking Providers

Plan tests still need a provider to compute the plan, and that is where mock providers come in. A mock_provider block stands in for the real AWS provider, returning synthetic values for computed attributes so the plan resolves without real credentials or API calls. This lets you test a module's logic — its conditionals, its for_each shaping, its name construction — entirely offline, with no AWS account and no cost, which is exactly what you want running on every pull request.

mock_provider "aws" {}

run "creates_one_subnet_per_az" {
  command = plan

  variables {
    availability_zones = ["us-east-1a", "us-east-1b"]
  }

  assert {
    condition     = length(aws_subnet.this) == 2
    error_message = "one subnet must be created per availability zone"
  }
}

With the mock provider in place, this run asserts that the module creates exactly one subnet per AZ for any list you pass — pure logic, verified in milliseconds, no infrastructure created. That is the sweet spot for the framework: testing the parts of a module that have logic worth getting wrong.

In CI

Run terraform test on every change to a module, before it is published or merged. Lean on plan-based tests with mock providers for the bulk of coverage, since they are fast enough to run on every commit and cost nothing. Reserve apply-based tests for a handful of critical end-to-end paths where "it plans correctly" is not enough assurance — and make sure those tests clean up reliably even when an assertion fails partway through, or you will leak resources and pay for them.