Contract Testing for Modules

A reusable module is a contract. Its input variables and output values are an interface other teams depend on, and a change that breaks that interface breaks every consumer — exactly like changing a function signature in a shared library. Contract testing pins that interface down so the break is caught in your CI, not in a downstream team's failed apply.

Three tools cover it: examples/ directories that double as runnable tests, terraform test for the input/output contract, and Terratest in Go for the heavier integration nobody else can reach. And the single most important contract to test is not an output at all — it is that the module's defaults are safe, because an insecure default spreads exposure to everyone who adopts the module.

The Module Interface as a Contract

The variables — their defaults and validations — and the outputs form a promise to consumers. Renaming an output, removing one, or flipping the behavior of a default is a breaking change exactly like altering a function signature. A team that references module.ingest.topic_id sees its plan break the moment you rename that output to pubsub_topic_id, and they find out at their next apply, not at yours.

That is the case for catching it with a test instead. A contract test asserts the output exists and the validation holds, so the break shows up in the module's own CI when you make it — where you can fix it — rather than as a surprise in a consumer's pipeline a sprint later.

examples/ That Double as Tests

An examples/minimal and an examples/complete directory serve two jobs at once: they document how to call the module, and they are fixtures that terraform test and Terratest run against. If the examples do not plan, the module is broken — so wiring them into the test suite means the documentation cannot quietly rot away from the real module.

The trap they avoid is the copy-paste of a broken snippet. A new consumer reaches for examples/minimal, copies it, and expects it to work. If that example is run under terraform test on every change, a broken example fails CI before it can mislead anyone — the docs are proven, not asserted.

terraform test for the Contract

Plan-mode run blocks assert the module's outputs and computed wiring. The Hatch ingest module exposes the bucket name and the Pub/Sub topic id; a test asserts those outputs exist and that the service account is bound to the right role. Because these are plan-mode and mocked, they run offline and free on every PR — the contract is checked without provisioning anything.

Variable validation rules are themselves contract checks, and the test confirms they fire. A test that passes an out-of-range value and expects the run to fail proves the validation guards the input as documented. The example asserts both an output and a binding the module promises.

# tests/contract.tftest.hcl
mock_provider "google" {}

run "exposes_stable_outputs" {
  command = plan

  assert {
    condition     = output.topic_id != ""
    error_message = "topic_id output is part of the contract — do not rename or remove"
  }

  assert {
    condition     = google_pubsub_topic_iam_member.publisher.role == "roles/pubsub.publisher"
    error_message = "ingest SA must keep publisher on the topic"
  }
}

Each assertion names the contract it guards. If a refactor renames topic_id or drops the binding, this run fails in the module's CI with a message that says what broke, long before a consumer feels it.

Terratest for Heavier Integration

Terratest is Go-based: it does a real apply, makes live assertions against the deployed resources, then destroys. You can call the deployed Cloud Run URL and check the response, read the bucket's actual IAM policy, or confirm the BigQuery dataset exists — checks that need a real resource standing in real GCP. Native terraform test cannot reach those, because it asserts on plan or state, not on live behavior.

The cost is a Go toolchain, real provisioned resources, and the time to apply and destroy. So Terratest earns its place only for behavior that genuinely needs a deployed resource. Reaching for it to check an output that a mocked plan run already covers is paying apply time and resource cost for an assertion that never needed GCP.

Testing That Defaults Are Safe

The highest-value contract test asserts the no-input case. A consumer who sets nothing should get a private bucket, CMEK on, public-access-prevention enforced, and no 0.0.0.0/0 ingress. That is one mocked plan run with empty variables and a handful of assertions on the resulting posture — cheap to write, and it guards the property that matters most.

The reason it matters most is blast radius. A module whose defaults are insecure spreads that exposure to every team that adopts it with defaults — which is most of them. An output rename breaks one consumer loudly at their next plan; an unsafe default leaks quietly across everyone, with no error at all. Test the zero-input instantiation and assert it is private, encrypted, and closed.