9 Testing and Refactoring

Automated tests improve module quality by catching bugs early, speed up pull request reviews, and help maintain backward compatibility by failing when breaking changes are introduced. Just as importantly, a solid test suite boosts team psychological safety, giving developers confidence to refactor and ship changes without fear of regressions.

Focus on testing your module’s logic and behavior, not the providers themselves. Good targets include data transformations, string construction, regex behavior, dynamic blocks (zero/one/many), and real system functionality (e.g., endpoints are reachable, credentials work). Avoid “pass-through” tests that merely restate provider behavior (e.g., asserting an input equals a corresponding provider attribute).

Two big differences: time and cost. Creating real infrastructure often takes minutes to tens of minutes and costs money while resources run. This makes cleanup critical and motivates strategies like test grouping, concurrency-safe naming, and CI timeouts. Skipping tests carries its own costs, as outages from untested changes can be much more expensive.

Most Terraform tests are integration tests because Terraform configures external systems. Providers themselves generally have unit tests. Use integration tests to verify that resources and modules work together for various configurations, supplemented by small “unit-like” checks of your data transformations and logic.

Use the native Terraform Testing Framework if your team prefers HCL, wants first-party integration, and can target Terraform/OpenTofu 1.6+. It can assert on internal values without outputs and supports mocks (1.7+). Choose Terratest if you need broad version flexibility, rich helper libraries, community ecosystem, or want to leverage Go and third-party packages. Existing teams with Terratest can continue with it confidently.

• Follow a simple flow: pick config → apply → validate → destroy.
• Use working examples as test inputs; group multiple assertions per environment to save time.
• Run tests concurrently; add randomness (e.g., random_string) to resource names to avoid collisions.
• Set generous timeouts in test runners and CI to prevent orphaned resources.
• Automate cleanup (e.g., vendor “nuke” tools) in isolated test accounts; never in prod.
• Use secure auth in CI, preferably OIDC.
• Treat tests as code: clear names, comments, refactor when needed.

Follow a consistent pattern: build terraform.Options, defer destroy, run init/apply, then assert (outputs or real endpoints). Parameterize the Terraform/OpenTofu binary via an env var, and always pass a longer test timeout (e.g., 60m). Use Terratest’s helper modules (cloud providers, HTTP/DNS, retries). In CI, use a matrix to test multiple engines/versions and optionally run each test function separately for cleaner logs and faster parallelism. A Makefile target can hide the boilerplate (timeouts, go mod tidy, env vars).

Write tests in .tftest.hcl with variables, run, and assert blocks. Assertions can access outputs and named values (e.g., resource attributes, locals) directly—no need to expose outputs. Use command = plan when you only need planned values, but remember plan can’t assert unknowns. Mocks (1.7+, beta) replace providers with fake values to speed logic checks and reduce cost; you can override defaults via mock_provider, mock_data, mock_resource, and override_* blocks, or reuse definitions via tfmock.hcl. Keep in mind mocks can drift from reality—use them to supplement, not replace, integration tests.

Copilot performs well with Terratest (Go) and can draft useful assertions and patterns you adapt into your test skeletons. It’s currently weak at generating native Terraform Test Framework files and may suggest outdated/less robust patterns. Use it for inspiration, then refine: keep your chosen structure, add robust options (e.g., retryable errors), and have experienced reviewers sanity-check generated code.

• Internal refactoring (reorganizing files, improving names, adding validation) should not change inputs/outputs and should not break tests—do this regularly.
• Rename resources via moved blocks to avoid recreation; don’t remove those blocks casually.
• Rename variables with “expand and contract”: add the new var, deprecate the old (default null), then use a local to prefer the old if set; remove deprecated vars in the next major release.
• Batch breaking changes into planned major versions; publish upgrade notes (CHANGELOG/UPGRADE). Maintain prior major versions for critical fixes while teams migrate.