skip to content

Native Test Framework

terraform test runs .tftest.hcl files of run blocks against real or planned infrastructure in short-lived state. Interviewers ask what command = plan changes and how to test a module's failure paths.

part ofTerraformread it →
on this pageshow

questions

5

In a Terraform `.tftest.hcl` file, what does `command = plan` change about a `run` block, and what can its `assert` blocks not read?

level: middleimportance: must knowfreq 50%

answer

  1. what each run block does by default
  2. what the test state holds afterwards
  3. values the provider generates at creation
  4. an error, neither a pass nor a skip
  5. logic versus what the API accepts

basics

~20 s

In a Terraform test file, a run block with command = plan plans but never applies, so it creates nothing. Assertions read only plan-time values; a condition on a known-after-apply attribute errors rather than passes.

solid answer

~50 s

A `run` block defaults to `command = apply`: it plans, applies real infrastructure into the file's in-memory test state, then evaluates its `assert` blocks. With `command = plan` it stops after the plan, so nothing is created and the run writes nothing to that state. That makes it fast and well suited to logic: names built from variables, instance counts, custom conditions. The limit is any value known only after apply, such as a generated ID. An `assert` whose result depends on one does not pass or get skipped: the run errors with `Unknown condition value`, and a later `run` reading such an output through `run.<name>.<output>` errors with `Reference to unknown value`. The provider is still real unless mocked, and a green plan cannot show that the API will accept the create. So I keep a fast plan-only file for logic and an apply file for provider-computed facts.

code

hcl · 14 lines
hcl
# tests/plan.tftest.hcl
variables {
  name       = "orders"
  cidr_block = "10.20.0.0/16"
}

run "tags_the_vpc" {
  command = plan

  assert {
    condition     = aws_vpc.this.tags["Name"] == "orders-vpc"
    error_message = "VPC Name tag does not follow the naming rule"
  }
}

go deeper

for a junior

Recall that a run block applies by default and that command = plan stops before creating anything. Say plainly that a plan cannot know values the provider generates at creation.

for a middle

Explain what each mode does to the test state, name the two unknown-value errors, and predict which of two given assertions errors in a plan-only run and why.

for a senior

Separate errors from failed assertions: one bad plan-only condition skips the rest of a sequential file. Show you know which facts need an apply, and do not treat a green plan as proof of creation.

for a principal

Frame plan-only against apply as a spend decision on a shared module: how many facts genuinely need real creation, what that costs per run, and what a green plan-only suite must never be used to claim.

## What `command` selects A Terraform test file (`.tftest.hcl`) is a sequence of **`run` blocks**, and each one simulates Terraform commands executed in the configuration directory. The `command` argument takes two values: - **`command = apply`** is the default. Terraform plans, applies real infrastructure, records the result in the file's in-memory test state, and then evaluates the block's `assert` conditions. - **`command = plan`** stops after the plan. Terraform evaluates the `assert` conditions against the planned values, creates nothing, and writes nothing to the test state. The **test state** is separate from any state the configuration keeps in a real backend. It starts empty for every test file, so a plan-only run at the top of a file is planning the creation of everything. ## What a plan-only `assert` can read A plan knows what the configuration determines. It does not know what the provider only generates when an object is created, which Terraform shows as **known after apply**. | Value in the condition | `command = plan`, empty state | `command = apply` | |---|---|---| | Attribute set from a variable or literal | Known | Known | | Number of instances, when `count` or `for_each` inputs are known | Known | Known | | Data source result, when its arguments are known | Known, read during the plan | Known | | Provider-generated attribute such as an ID | Unknown | Known | | Output built from a provider-generated attribute | Unknown | Known | That is why plan-only runs suit **logic**: a naming rule, a conditional argument, the number of subnets a list of zones expands to, or a custom condition that can be evaluated from the inputs. ## The two errors an unknown value raises A condition whose result is unknown never quietly passes. Terraform reports one of two diagnostics: 1. **`Unknown condition value`**: an `assert` in a plan-only run could not be evaluated, because something it depends on is known only after apply. 2. **`Reference to unknown value`**: a `run` block reads `run.<name>.<output>` from an earlier plan-only run, and that output is known only after apply. ```hcl run "reads_generated_id" { command = plan assert { condition = aws_vpc.this.id != "" error_message = "VPC has no ID" } } ``` On an empty test state this block ends in `Unknown condition value`. The usual fixes are to drop the value from the condition or to run the block with `command = apply`. Both diagnostics are errors rather than failed assertions, and the difference matters. A failed `assert` marks the run as failed, but later `run` blocks still execute, because the run did execute and write its outputs. An errored run is treated as not having done so, and a `run` block that must follow it is skipped, which in a default sequential file means all the remaining ones. ## What a plan-only pass does not prove Green means the logic evaluated as you asserted. It leaves these open: - **Whether the API accepts the request.** The create never happened, so anything only the API checks at creation is untested. - **Whether conditions on computed values hold.** Terraform may be unable to evaluate a custom condition that relies on computed attributes until the resource exists. - **Whether the provider was needed.** It was. Unless the file mocks the provider, Terraform configures the real one and reads data sources through it, so a plan-only file is not an offline test. - **Whether later runs have anything to build on.** A plan-only run writes nothing to the test state, so the next `command = apply` run on that state starts without any of the planned objects. ## Splitting a shared module's tests For a shared network module, the author's `tests/` directory usually ends up holding two files: - `tests/plan.tftest.hcl`: `command = plan` on every block, for naming, subnet counts and input handling. It costs little and creates nothing, so it can be large. - `tests/apply.tftest.hcl`: real creation for what only apply can show, such as a provider-generated attribute feeding another resource. There is also a useful middle pattern. A plan-only run placed after an apply run on the same state does see real values, because it plans against the objects that apply recorded. It still creates nothing itself, but it depends on that earlier apply and its cost. A mocked provider changes this trade-off, and its `override_during = plan` setting can make an overridden value available at plan time, but that is a topic of its own and does not change what a real-provider plan knows.

  • How can a plan-only `run` block in a test file read a provider-generated attribute at all?
    Only if an earlier `command = apply` run on the same state key already created the object. The plan run loads that test state, so attributes that are not changing are known. You get a real value in the condition, but you have paid for the earlier apply, and that object is destroyed in cleanup like any other.
  • What is the practical difference between a failed `assert` and `Unknown condition value` for the rest of the file?
    A failed `assert` marks that run as failed, and later `run` blocks still execute because the run produced data. `Unknown condition value` is an error, like a failed plan, so a `run` block that must follow it is skipped. In a sequential file that is every remaining block, which is why one bad plan-only condition can hide many results.
  • Why does a plan-only test file still reach the real provider?
    Because `command = plan` skips the apply, not the plan. Unless the provider is mocked, Terraform configures the real one, reads data sources through it and refreshes anything already in the test state. So a plan-only file avoids creating infrastructure, but it is not an offline test.

  • command = plan is the default for a run block, so tests never create anything.
  • An assert on a value known only after apply simply passes or gets skipped in a plan-only run.
  • A green plan-only run proves the resources will create successfully in the cloud.
  • Plan-only runs never contact the real provider, even when the provider is not mocked.
  • A plan-only run records its planned resources in the test state for later runs to use.
open as a page

In a Terraform `.tftest.hcl` file, how do you use `expect_failures` to test a module's failure path, and what still fails the `run` block?

level: middleimportance: should knowfreq 44%

basics

~20 s

In a Terraform test file, expect_failures lists the object whose custom condition should fail, usually with command = plan and bad input. The run passes only if it does; a type error or provider error still fails the run.

open as a page

How does Terraform's native `terraform test` framework work — where do the test files live, and what does a `run` block do?

level: middleimportance: should knowfreq 45%

basics

~20 s

Tests are .tftest.hcl files in the module directory or a tests/ subdirectory. Each run block executes a plan or an apply against the module and evaluates assert conditions. Apply runs create real infrastructure, which Terraform destroys when the file finishes.

open as a page

In a Terraform `.tftest.hcl` file using a setup helper module, how do state keys decide which `run` blocks can run in parallel and what cleanup destroys first?

level: seniorimportance: should knowfreq 36%

basics

~20 s

Terraform test files keep one in-memory state per state key: by default the main configuration and each helper module source. Run blocks sharing a key never run concurrently, and cleanup destroys the most recently updated state first.

open as a page

You own a shared Terraform network module used by many teams: what do you require of its `terraform test` suite before you tag a release, and why?

level: principalimportance: should knowfreq 30%

basics

~20 s

For a shared Terraform module's test suite, require a failure case for each promised custom condition, plan-only logic tests and at least one real apply in a dedicated account that cleans up after itself, scaled to blast radius and cost.

open as a page