paulasilvatech Azure Terratest Module Testing
Test one Terraform module with the least expensive and least mutating mode that can prove the requested behavior.
When to invoke
- Add or repair a test under
tests/terraform/modules/. - Cover module inputs, outputs, validation, plan shape, or a negative path.
- Select between static, plan, and Azure integration testing.
- Diagnose a focused Terratest failure without changing unrelated infrastructure.
Repository anchors
- Go module and dependency versions:
tests/terraform/go.mod - Current conventions and commands:
tests/terraform/README.md - Existing module tests:
tests/terraform/modules/*_test.go - CI behavior:
.github/workflows/terraform-test.yml - Implementation under test: the corresponding
terraform/modules/<name>/
Inspect these anchors before authoring a test. Do not assume the README, workflow labels, and test build tags are perfectly aligned; derive the runnable selector from the current Go files.
Modes
| Mode | Approval | Allowed behavior |
|---|---|---|
static |
Default | Compile tests, inspect files, and run checks that do not plan, apply, destroy, authenticate to Azure, or contact a remote backend. |
plan |
Explicit mode selection | Initialize with backend disabled, validate, and run a focused plan without applying. Stop if credentials, a remote backend, or provider API access was not approved. |
integration |
Exact environment approval | Create only uniquely named test resources through OIDC, enforce cost and timeout limits, and clean up only resources created by that test. |
Procedure
Resolve one test file and its corresponding Terraform module. Read module inputs, outputs, validations, provider requirements, and nearby test patterns.
Select
staticunless the acceptance criterion requires a plan. Selectintegrationonly when the environment, OIDC identity, subscription, region, expected cost, unique resource-group identity, timeout, and cleanup are all explicitly approved.Use
terraform.WithDefaultRetryableErrorsfor operations affected by transient provider failures. Keep retry behavior bounded and do not convert deterministic validation failures into retries.Prefer Terratest
*EAPIs such asInitAndValidateE,PlanE, orDestroyEwhen an error is an expected result or cleanup evidence must be reported. Assert the specific failure contract instead of accepting any error.Keep static tests free of Azure credentials and resource changes. A compile-only baseline is:
cd tests/terraform go test -run '^$' ./...In plan mode, use a focused test selector, backend-disabled initialization, deterministic variables, and no saved plan unless the caller requested one. Do not assume a plan is offline; providers may query remote APIs.
In integration mode, generate a collision-resistant resource-group name owned by the test, register scoped cleanup immediately with
t.Cleanup, and use OIDC (ARM_USE_OIDC=true). Cleanup may destroy only the Terraform resources or exact resource group created by that test.Never list and delete resource groups by a shared substring, prefix, tag, or subscription-wide query. Existing broad cleanup elsewhere is not a pattern to copy.
Run the smallest selected test from
tests/terraform, for example:go test -v -run '^TestExactName$' -timeout 30m ./modulesAdd
-tags=integration, the approved timeout, and approved OIDC environment only for integration mode.Report mode, selector, module, credentials used or not used, resource identity, timeout, cleanup result, test evidence, and residual resources.
Output template
## Terratest result
**Status:** completed | blocked
**Mode:** static | plan | integration
**Module/test:** <terraform module> / <exact Go test>
### Safety context
- Backend: disabled | <approved isolated backend>
- Azure/OIDC: not used | <approved environment and identity>
- Cost/timeout: <not applicable | approved bounds>
- Resource group: <not created | exact unique name>
- Cleanup: <not required | registered and verified | failed>
### Changes
- `<tests/terraform/...>`: <coverage added or repaired>
### Validation
- `<exact command>`: PASS | FAIL | NOT RUN - <evidence>
### Residual resources
- <none | exact resource and owner>
Limits
- Never run integration mode from ambient credentials or a client secret.
- Never run
terraform applyordestroyoutside the test's approved integration lifecycle. - Never use broad subscription or resource-group cleanup.
- Do not weaken assertions, skip cleanup, or raise timeout and cost limits merely to make a test pass.
Quality gate
- The test maps to one current Terraform module and follows
tests/terraform/go.mod. - Static is the default; plan and integration have the required approval.
- Negative paths use
*EAPIs and assert a specific error. - Retryable errors are bounded and only cover transient behavior.
- Integration identity, cost, unique resource group, timeout, and scoped cleanup are explicit.
- The exact focused command and cleanup evidence are reported.