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

## Where tests live and how they run Terraform's test framework, generally available since Terraform 1.6, is written in HCL rather than in a general-purpose language. Test files use the `.tftest.hcl` extension (a JSON variant also exists) and are discovered in two places: the module's own directory, and a `tests` subdirectory beneath it. `terraform test` runs them; the directory must be initialized first, because the framework drives the real Terraform workflow and needs providers installed. A test file is a *sequence*, not a set. Its `run` blocks execute top to bottom against one shared state for that file, so run 2 sees whatever run 1 created. Files are independent of one another. ## Anatomy of a run block ```hcl variables { bucket_prefix = "acme-test" } run "plan_is_valid" { command = plan variables { environment = "dev" } assert { condition = aws_s3_bucket.this.bucket == "acme-test-dev" error_message = "bucket name was not composed from prefix and environment" } } ``` The pieces: - **`command`** — `plan` or `apply`. It defaults to `apply`. A plan run evaluates the configuration and lets you assert on planned values without creating anything; an apply run provisions for real and lets you assert on values that are only known after creation. - **`variables`** — set at file level as defaults and overridden per run. This is how one module gets exercised across several input combinations. - **`assert`** — a `condition` that must evaluate true and an `error_message` printed when it does not. Conditions may reference the module's outputs and the resources of the configuration under test. - **`expect_failures`** — the inverse assertion: you list the checkable objects you expect to fail, and the run passes only if they do. This is how you test that bad input is actually rejected. - **`module`** — points a run at a different module than the one under test, typically a small helper under `tests/setup` that provisions prerequisites or generates a random suffix. Across runs, `run.<name>.<output_name>` reads an earlier run's output, which is how you apply a module and then assert against it, or feed a created resource's id into a later case. ## The part that surprises people By default `terraform test` uses your **real providers**. An apply run creates real cloud resources with real cost and real blast radius. That is deliberate — the framework's headline value is that it can verify a module end to end — but it means test credentials, an isolated account, and unique naming matter enormously. Two developers running the same suite concurrently against the same account will collide on any globally unique name, which is why setup modules that generate a random suffix are a common pattern. Cleanup is automatic but not guaranteed: when a file finishes, Terraform destroys the objects created by its runs, in reverse order. If destroy fails — a dependency it cannot delete, a credential expiry, an interrupted run — Terraform reports which objects it could not clean up, and someone has to go and remove them. Budget for orphan cleanup in any real adoption. ## Useful flags `terraform test -filter=<file>` restricts execution to specific test files; `-verbose` prints the plan or state for each run so you can see what an assertion was looking at. A non-zero exit status on failure is what makes it usable as a pipeline step. ## What it replaces and what it does not Before this existed, module testing meant a Go harness — Terratest and similar — that shelled out to Terraform, applied a fixture, made assertions from Go, and deferred a destroy. That approach is still the one that can reach *past* Terraform: HTTP-request the endpoint you just created, SSH to the box, poll until an ASG is healthy. The native framework asserts on plan values, state and outputs; it does not make arbitrary network calls to prove the infrastructure actually works. So the honest positioning is: `.tftest.hcl` covers module logic — naming, conditional resources, counts, output wiring, input rejection — in the same language as the module and with no extra runtime, and it can do so cheaply once you introduce mocked providers. Behavioural verification against a live system remains the job of a Go-style integration test. ## Answering it well Name the file extension and discovery locations, describe the run block as an ordered plan-or-apply step with assertions, and volunteer the operational catch — that the default is `apply`, that it creates real infrastructure, and that cleanup happens per file and can fail. The last point is what separates someone who has run a suite from someone who has read the documentation.