Andrew Mercer
on this page

The testing pyramid for infrastructure

Layer Tool Speed Needs cloud? Catches
Format and syntax terraform fmt -check, terraform validate Seconds No Syntax, types, missing arguments
Lint TFLint + provider ruleset Seconds No Invalid SKUs, deprecated arguments, naming
Security / policy (static) Checkov, Trivy, Conftest (HCL) Seconds No Insecure settings, org rules
Unit tests terraform test with command = plan and mock providers Seconds No Module logic: for expressions, conditionals, naming, validations
Contract / plan tests Conftest on plan JSON, "no deletes" check Minutes Read-only Org rules on real values, unexpected replacements
Integration tests terraform test with command = apply Minutes Yes, sandbox Provider behaviour, real API constraints
End-to-end Terratest (Go) or terraform test + check/http Minutes–hours Yes The deployed thing actually works

Most module bugs are logic bugs: a for expression that drops an element, a conditional that's backwards, a name that exceeds 24 characters. Mocked plan-mode tests catch those in seconds with no credentials, so they should be the bulk of your tests.

terraform test

Built in since Terraform 1.6 (OpenTofu: tofu test). Tests live in *.tftest.hcl files, by default in the module root or a tests/ directory.

modules/storage/
├── main.tf
├── variables.tf
├── outputs.tf
└── tests/
    ├── unit.tftest.hcl
    └── integration.tftest.hcl
terraform init
terraform test                                  # everything
terraform test -filter=tests/unit.tftest.hcl    # one file
terraform test -verbose                         # print plans/state per run
terraform test -junit-xml=report.xml            # for CI test reports (GA in 1.11)

Anatomy of a test file

# tests/unit.tftest.hcl

# File-level variables apply to every run block
variables {
  name                = "stlogsdevcc001"
  resource_group_name = "rg-test"
  location            = "canadacentral"
}

run "secure_defaults" {
  command = plan            # default is apply

  assert {
    condition     = azurerm_storage_account.this.min_tls_version == "TLS1_2"
    error_message = "TLS 1.2 must be the minimum."
  }

  assert {
    condition     = azurerm_storage_account.this.public_network_access_enabled == false
    error_message = "Public network access must default to off."
  }
}

run "rejects_long_names" {
  command = plan

  variables {
    name = "thisnameiswaytoolongforazurestorage"
  }

  expect_failures = [var.name]     # the validation on var.name must fail
}
  • Each run block is a plan or apply against the module, in file order, sharing state with earlier runs in the same file (unless given a different state_key).
  • assert conditions can reference resources, outputs (output.x), variables and earlier runs (run.setup.some_output).
  • expect_failures lists checkable objects (variables, outputs, resources with conditions, check blocks) that must fail. The run passes only if they do.
  • After all runs, Terraform destroys whatever was applied, in reverse order.

Mock providers (1.7+)

Plan-mode tests still need provider credentials, because providers configure themselves and data sources read real APIs. Mock providers remove that:

# tests/unit.tftest.hcl
mock_provider "azurerm" {
  # Values for computed attributes, so assertions on them work
  mock_resource "azurerm_storage_account" {
    defaults = {
      id                    = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-test/providers/Microsoft.Storage/storageAccounts/stlogsdevcc001"
      primary_blob_endpoint = "https://stlogsdevcc001.blob.core.windows.net/"
    }
  }

  mock_data "azurerm_client_config" {
    defaults = {
      tenant_id = "11111111-1111-1111-1111-111111111111"
      object_id = "22222222-2222-2222-2222-222222222222"
    }
  }
}

run "outputs_wired_correctly" {
  command = apply        # "apply" against mocks: nothing real is created

  assert {
    condition     = output.blob_endpoint == "https://stlogsdevcc001.blob.core.windows.net/"
    error_message = "blob_endpoint output is wrong."
  }
}

With a mock provider, apply runs entirely in memory, so you can test outputs and computed values with no cloud at all. Unset computed attributes get generated placeholder values.

Shared mock data can live in *.tfmock.hcl files and be loaded with mock_provider "azurerm" { source = "./tests/mocks" }. Terraform 1.15+ allows function calls inside mock blocks.

Overrides

Override one resource, data source or module call instead of the whole provider:

run "with_existing_vnet" {
  command = plan

  override_data {
    target = data.azurerm_virtual_network.hub
    values = {
      id            = "/subscriptions/.../virtualNetworks/vnet-hub"
      address_space = ["10.0.0.0/16"]
    }
  }

  override_module {
    target  = module.diagnostics
    outputs = { setting_id = "mock-setting" }
  }

  assert {
    condition     = length(azurerm_virtual_network_peering.to_hub) == 1
    error_message = "Expected one peering to the hub."
  }
}

Testing with helper modules

A run block can execute a different module, typically a setup fixture or a verification module:

run "setup" {
  module {
    source = "./tests/fixtures/resource-group"
  }
}

run "create_storage" {
  variables {
    resource_group_name = run.setup.resource_group_name
  }
}

run "verify_blob_reachable" {
  command = plan
  module {
    source = "./tests/fixtures/http-check"
  }
  variables {
    url = run.create_storage.blob_endpoint
  }
  assert {
    condition     = data.http.check.status_code == 200
    error_message = "Blob endpoint not reachable."
  }
}

Integration tests against a sandbox

Real-apply tests need a subscription where creating and destroying things is cheap and safe:

# tests/integration.tftest.hcl
provider "azurerm" {
  features {}
  subscription_id = "33333333-3333-3333-3333-333333333333"   # sandbox
}

variables {
  location = "canadacentral"
  # name_suffix is deliberately not set here: values in the test file win over
  # TF_VAR_*, so CI supplies TF_VAR_name_suffix=$CI_PIPELINE_ID instead and
  # concurrent pipelines don't collide.
}

run "create" {
  # command = apply (default)
  assert {
    condition     = azurerm_storage_account.this.id != ""
    error_message = "Storage account was not created."
  }
}

Practices:

  • A dedicated sandbox subscription with a budget alert and a scheduled cleanup of anything older than a day (tests that crash can leave resources behind).
  • Unique names per pipeline, from CI_PIPELINE_ID passed as a variable, so concurrent runs don't collide.
  • Run integration tests on module release MRs and nightly, not on every commit.
  • Since Terraform 1.14, prevent_destroy is ignored during test cleanup, so modules with protective lifecycles can still be tested. Terraform 1.16 reports leftovers when skip_cleanup is set.

Parallel runs (1.12+)

Independent run blocks can be annotated to run concurrently, and terraform test -parallelism=n controls concurrency within a run's plan/apply. Use separate state_keys for runs that must not share state. Check the docs for your version for the exact attributes.

Contract tests on plan JSON

For root modules (environments), the useful test is often "does the plan do anything surprising?":

terraform plan -out=tfplan -detailed-exitcode || [ $? -eq 2 ]
terraform show -json tfplan > tfplan.json

# Fail on any delete/replace unless explicitly allowed
jq -e '[.resource_changes[] | select(.change.actions | index("delete"))] | length == 0' tfplan.json

# Policy checks
conftest test tfplan.json --policy policy/

This is what makes automated module upgrades safe (shared modules).

Terratest

Terratest is a Go library: tests apply real infrastructure, then use Go to inspect it (HTTP calls, SSH, cloud SDKs, Kubernetes clients), then destroy.

func TestStorageModule(t *testing.T) {
    t.Parallel()

    opts := terraform.WithDefaultRetryableErrors(t, &terraform.Options{
        TerraformDir: "../examples/basic",
        Vars: map[string]interface{}{
            "name": fmt.Sprintf("stterratest%s", strings.ToLower(random.UniqueId())),
        },
    })
    defer terraform.Destroy(t, opts)
    terraform.InitAndApply(t, opts)

    endpoint := terraform.Output(t, opts, "blob_endpoint")
    http_helper.HttpGetWithRetry(t, endpoint+"?comp=list", nil, 400, "", 10, 5*time.Second)
}

When to reach for it over terraform test: you need real verification logic (SSH into a VM, query a database, run kubectl), retries with backoff, or you already have Go tests. For most module testing, terraform test is now enough, and it's one less language.

In CI

module-tests:
  stage: test
  image: hashicorp/terraform:1.16
  script:
    - terraform init -backend=false
    - terraform fmt -check -recursive
    - terraform validate
    - terraform test -filter=tests/unit.tftest.hcl -junit-xml=unit.xml
  artifacts:
    reports:
      junit: unit.xml

module-integration:
  stage: test
  rules:
    - if: $CI_COMMIT_TAG
    - if: $CI_PIPELINE_SOURCE == "schedule"
  id_tokens:
    ARM_OIDC_TOKEN: { aud: api://AzureADTokenExchange }
  variables:
    ARM_USE_OIDC: "true"
    ARM_CLIENT_ID: $SANDBOX_CLIENT_ID
    ARM_TENANT_ID: $AZURE_TENANT_ID
    ARM_SUBSCRIPTION_ID: $SANDBOX_SUBSCRIPTION_ID
    TF_VAR_name_suffix: $CI_PIPELINE_ID
  script:
    - terraform init -backend=false
    - terraform test -filter=tests/integration.tftest.hcl -junit-xml=integration.xml
  artifacts:
    reports:
      junit: integration.xml

Terraform 1.15+ validate also checks the backend block. If your backend values come from environment variables or -backend-config, run init -backend=false first, or validate in a job that has them.

What to test in a module

  • Secure defaults: public access off, TLS minimums, encryption, diagnostics on.
  • Validation rules reject bad input: one expect_failures run per validation.
  • Conditional logic: each toggle on and off produces the expected resource count.
  • Naming: generated names meet the provider's length and character rules.
  • Collections: adding an element to an input map adds exactly one instance, with the expected key.
  • Outputs: present, correctly keyed, sensitive where they should be.
  • Upgrade safety: plan the previous release's example state with the new version and assert no replacements (the plan-JSON check above, run against a long-lived sandbox).