Terraform module maintainers often maintain separate `examples/` and `tests/` directories, leading to documentation drift. When you refactor a module, the examples break, but CI passes because tests weren't updated. This creates a poor user experience and debugging headaches.

The solution is Terraform's native testing framework (1.6+). It lets you write tests in HCL that directly validate your example code. Instead of duplicating work, your examples become the single source of truth. Tests assert that the example configuration works as intended, catching breaks immediately.

This approach ensures your documentation stays accurate automatically. You can test progression from basic to advanced usage, validate output contracts, and catch backwards incompatibility before release. Run `terraform test` locally or integrate JUnit XML output into CI for continuous validation.