Contract Testing for Modules

When teams share a module, its interface is a contract. The inputs it accepts, the outputs it returns, and the behavior it promises are what every consumer writes their code against — and a change to any of them ripples to every stack that calls the module. Rename an output and a dozen downstream configurations break on their next plan. Contract testing verifies that a module honors its promised interface across versions, so consumers can upgrade with confidence instead of dread.

This is where the module chapter and the testing chapter meet. A shared module is a published API, and the same discipline that keeps a library's API trustworthy applies here: the interface is the thing under test, not the internals. A consumer does not care which resources the module creates; they care that the outputs they depend on still exist, still mean the same thing, and still appear under the same names.

The Module as a Contract

The contract has three parts: the input variables a consumer sets, the outputs they read, and the documented behavior between them. A consumer of a VPC module passes a CIDR block and a list of availability zones, and reads back a VPC ID and a list of subnet IDs. Those names and types are the promise. The module is free to change how it builds the VPC internally, but the moment an output disappears or an input becomes required, the promise is broken and someone's stack stops planning.

Testing the Interface

The native terraform test framework from the previous topic is how you assert the contract. A test sets the inputs a consumer would set and asserts that the promised outputs exist and carry the expected shape and values. The point is not to test that AWS works — it is to test that the module's surface behaves as documented for the input combinations consumers actually use.

run "exposes_vpc_and_subnet_outputs" {
  command = plan

  variables {
    cidr_block         = "10.0.0.0/16"
    availability_zones = ["us-east-1a", "us-east-1b"]
  }

  # the contract: these outputs must exist and match the inputs
  assert {
    condition     = length(output.subnet_ids) == 2
    error_message = "module must return one subnet id per availability zone"
  }
}

This run pins the promise: given two availability zones, the module returns two subnet IDs through its subnet_ids output. If a refactor drops that output or changes its cardinality, the test fails before the change is published, and the breakage is caught by the author rather than discovered by a consumer in production.

Versioning and Backward Compatibility

Interface changes are SemVer-significant. Removing an output, renaming one, or making a previously optional input required is a breaking change and demands a major version bump — consumers pinned to ~> 2.0 must not silently receive it. Adding a new optional input or a new output is backward-compatible and belongs in a minor version. Contract tests are what enforce this distinction mechanically: a minor bump that breaks the interface fails its own tests, so the discipline is not left to the author's memory.

Example-Driven Tests

A module's examples/ directory should hold runnable configurations that call the module the way real consumers do — the minimal example, the example with every option set, the common production shape. These examples double as documentation and as integration tests: a test run that plans each example proves the module still works for the usage patterns you ship. The trap is letting examples/ rot until it no longer reflects real usage; a stale example is worse than none, because it documents a contract the module no longer honors.

Catching Breaking Changes

The payoff is a test suite that fails loudly the moment the interface breaks — an output removed or renamed, a required input added, a type changed. Run it in CI on every change before publishing a new version, and a breaking change cannot ship under a non-breaking version number without someone seeing red. That is the whole point of contract testing: move the discovery of a breaking change from the consumer's production plan, weeks later, to the author's pull request, before it is ever tagged.