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?
answer
- blast radius sets the bar
- each promise a module makes
- what only a real create can show
- cleanup counts toward green
- what you refuse to require
basics
~20 sFor 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.
solid answer
~50 sI set the bar by blast radius and cost, not by a coverage number. Every custom condition we publish as part of the module's contract gets a good-input run and an `expect_failures` run, because those are cheap and plan-only. Logic such as naming and counts stays in plan-only files. Then at least one apply file creates the module's main path in a dedicated test account, since a plan cannot show what the API accepts. Cleanup is part of green: a suite that leaves resources behind blocks the release, and helper modules stay simple enough that teardown is automatic. I would not require an apply for every input combination, because slow or flaky gates get bypassed and teams fork the module. I also name an owner for the test account's bill and for waivers. The trade-off moves with the number of consumers and the cost of breaking them.
code
bash · 3 linesterraform init
terraform test -filter=tests/plan.tftest.hcl
terraform test -filter=tests/apply.tftest.hcl -junit-xml=apply-report.xmlgo deeper
Know that a module's tests are run with terraform test before publishing, and that some of them create real resources that cost money and have to be destroyed afterwards.
Be able to lay out the suite: failure cases with expect_failures, plan-only logic files, and an apply file. Say which runs create infrastructure and which do not.
Show how you keep the gate trustworthy: a dedicated account, cleanup treated as a failure condition, simple helper modules, and flaky apply tests fixed instead of routinely overridden.
State the bar as a trade-off between consumer blast radius, run cost and release cadence. Say what you refuse to require, who owns the account bill and waivers, and what a green suite cannot claim.
## There is no universal bar This is a judgement call. A `terraform test` suite spends real money and time on each apply, and a shared module's release can break every consumer at once. The right requirement sits between those two costs, and it moves with three things: - **Blast radius**: how many teams consume the module and how quickly they pick up a new version. - **Cost per run**: how long the module takes to create and destroy, and what it costs to do so. - **Rate of change**: a module tagged twice a year can afford a slower gate than one tagged twice a week. An answer that names a single rule and no trade-off is weak. An answer that sets a minimum, says what would raise or lower it and names who decides exceptions is what is being asked for. ## A workable minimum For a network module used by many teams, I would start with this, and adjust: 1. **A failure case per promised condition.** Each custom condition we document as behaviour has a good-input `run` block and one with `expect_failures`. These are plan-only and cheap, and they fail with `Missing expected failure` if someone removes the condition. 2. **Logic in plan-only files.** Naming, counts and conditional arguments use `command = plan`. They create nothing, though they still use the real provider unless it is mocked. 3. **At least one real apply path.** The module's main shape is created with `command = apply`, in a dedicated test account, asserting on facts only a real creation can supply. A green plan cannot show that the API accepts the request. 4. **Cleanup counted as part of the result.** If Terraform reports resources that need to be cleaned up manually, the release does not proceed. Terraform already marks that file as errored and exits non-zero, so the job only has to honour it instead of retrying past it. Test helpers stay simple, ideally one setup module applied first, because the framework's own guidance warns that anything more complex may need careful thought about destruction order. 5. **An archived result.** `terraform test -junit-xml=<file>` keeps a report per release. It is not compatible with `-cloud-run`, so a team testing through HCP Terraform needs another record. | Requirement | What it costs | What it protects | |---|---|---| | Failure case per condition | Almost nothing per run | The module's published rejections | | Plan-only logic files | Provider access, little time | Names, counts and conditionals | | One real apply path | Real resources and minutes | Provider and API behaviour on the main path | | Apply for every input combination | Multiplies the above | Rare paths, at a price usually not worth it | ## What I would refuse to require A bar nobody can meet gets bypassed, and that is worse than a lower one: - **An apply for every input combination.** Costs multiply, and more real creation means more chances of an unrelated failure blocking a release. - **A coverage percentage.** `terraform test` has no such measure, and counting `run` blocks rewards empty ones. - **Parallelism by default.** It speeds a file up, but only with separate state keys and explicit references, and it makes teardown harder to reason about. I adopt it when a slow file justifies it. If the gate becomes slow or flaky, teams pin old versions or fork the module. That cost does not appear in the test report, which is why it deserves weight. ## Who owns what The requirement needs owners, not just rules: - **The test account and its bill.** The documentation recommends dedicated testing accounts that can be routinely and safely purged. Someone must own that purge. - **Waivers.** Decide in advance who may tag a release over a red or flaky apply, and how that is recorded. - **Where it runs.** A team may run the suite in its own pipeline, or use HCP Terraform's private registry, which can run tests for each commit to a designated branch of a module published with the branch-based workflow. `terraform test -cloud-run=<source>` runs them remotely against a private registry module. ## What the suite still will not tell you Be explicit about the limits, or a green badge gets over-trusted. A module's own tests exercise the examples its authors wrote, not each consumer's composition; an interface change that breaks callers is a separate kind of check. Tests on a mocked provider never reach that provider's cloud. And a pass only speaks for the Terraform and provider versions it ran with, so I would also decide which versions from the module's constraints the suite must cover.
- A flaky apply test has blocked your module's release for two days. What do you do?Find out whether it is a real provider or API problem first, since that is what the apply path is for. If it is not, fix or narrow the test rather than normalising overrides. Meanwhile, use the agreed waiver route, record it, and watch the test account for leftovers. Repeated waivers mean the bar is wrong.
- How would your requirement differ for a module used by two teams rather than two hundred?For two teams, failure cases and plan-only logic may be enough, with an apply path run occasionally, because breakage is small and quickly talked through. For two hundred, the real apply path becomes mandatory before each tag, and I would invest in cleanup checks and a purge routine for the test account.
- Every input combination must be applied for real before any release of a shared module.
- A shared module needs only plan-only tests, because a green plan proves that the apply will work.
- Resources left behind by a test run are a housekeeping matter, not a reason to hold a release.
- A green terraform test suite means every consumer's use of the module is safe.
- terraform test reports a coverage percentage that a release gate can simply enforce.