Your Terraform Examples Are Broken (And You Don't Know It Yet)

TL;DR: Stop maintaining separate examples and tests. Test your examples directly. One source of truth. Your docs stay correct automatically. The Problem You publish an example in your module docs. Users follow it. Six months later, you refactor your module. The example breaks. But you don't know until someone opens an issue. This happens because: documentation lives in examples/, tests live in tests/, and they drift apart. With Terraform's native testing (1.6+), there's a better way. Stop writing your examples separately from your tests. Make every example self-validating. This post shows how to do it—and why it's a game-changer for module maintainers. Part 1: Foundation (Level 200) The Traditional Problem You've built an S3 module with three examples: Basic usage - Just create a bucket with defaults With versioning - Add version tracking With lifecycle policies - Add archival and cleanup Then you: Write examples in examples/ Write t