1.5.1.1. Unit Testing

In the development and maintenance of large-scale Terraform modules, unit testing is a critical means to ensure the correctness of module logic, improve development efficiency, and reduce regression risks. With the introduction of the native test framework in Terraform 1.6 and above—and specifically the Mocking capabilities added in version 1.7—module authors can now verify module logic quickly and stably without relying on real cloud resources.

This section will explore the core concepts of Terraform unit testing, best practices, the application of Mocking techniques, and how to build reusable test structures, helping you achieve a high-quality, low-cost testing system during module development. Before reading this section, please ensure you are familiar with the contents of:

1.5.1.1.1. What is Terraform Unit Testing?

Unit testing aims to verify whether the behavior of a specific logical unit within a module meets expectations. Its characteristics include:

Fast Execution: Tests should run quickly to facilitate frequent execution.
Low Cost: No need to create real resources, avoiding cloud resource costs.
Stable and Repeatable: Consistent results for every run, avoiding test failures caused by external factors.
Easy to Debug: Accurately pinpoints the location of the code causing the error when a test fails.

In Terraform, it is recommended to use the native terraform test command and framework to write unit tests. Test files end with .tftest.hcl or .tftest.json and are typically placed in the module's root directory or a tests/ directory.

1.5.1.1.2. Objects of Unit Testing

The target objects of unit testing should be the module code itself, rather than the individual examples found under the examples directory.

1.5.1.1.3. Structure and Syntax of Unit Tests

A typical Terraform test file contains the following structure:

variables {
  # Define variables required for testing
}

mock_provider "azurerm" {
  # Define Mock Provider to simulate resources and data sources
}

run "test_case_name" {
  command = plan  # or apply
  providers = {
    azurerm = azurerm.mock
  }
  assert {
    condition     = azurerm_storage_account.example.name == "expected-name"
    error_message = "Account name does not match expected value."
  }
}

variables block: Defines the input variables required for the test.
mock_provider block: Defines the simulated Provider to avoid creating real resources.
run block: Defines specific test cases, including the execution command (plan or apply), the Providers used, and assertion conditions.

1.5.1.1.4. Simulating Resources and Data Sources with Mock Providers

To avoid creating real resources during unit testing, Terraform provides the Mock Provider feature. Through the mock_provider block, you can simulate the behavior of resources and data sources and return predefined attribute values.

Since the native Terraform test framework offers the most powerful Mock Provider capabilities and assertions for resource attributes, Terraform unit tests can essentially only be written using the Terraform test framework.

1.5.1.1.4.1. Using External Mock Data Files

To achieve Mock data reuse, you can define mock_resource and mock_data blocks in separate .tfmock.hcl files and import them via the source attribute:

mock_provider "azurerm" {
  alias  = "mock"
  source = "./mocks/azurerm"
}

Define shared Mock data in the ./mocks/azurerm.tfmock.hcl file:

mock_resource "azurerm_storage_account" {
  defaults = {
    id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourcegroup/providers/Microsoft.Storage/storageAccounts/myaccount"
  }
}

1.5.1.1.5. High-Quality Unit Test Cases

1.5.1.1.5.1. Focusing on Complex Logic Verification

Unit tests should focus on validating complex expressions, conditional logic, or data transformations within the module. For example, verifying naming conventions, tag generation rules, resource dependencies, etc.

run "validate_account_naming" {
  command = plan
  assert {
    condition     = startswith(azurerm_storage_account.example.name, "prod-")
    error_message = "Storage Account's name must start with 'prod-'."
  }
}

1.5.1.1.5.2. Clear Test Naming

The name of the run block should clearly describe the purpose of the test and the expected result to facilitate understanding and maintenance. For example:

Good Naming: run "ensure_versioning_enabled", clearly indicates that the purpose of the test is to ensure versioning is enabled.
Bad Naming: run "test1", lacks descriptiveness, making it impossible to know the specific content of the test from the name alone.

1.5.1.1.5.3. Writing Assertion Conditions

Use the assert block to define test assertions. The condition expression should return a boolean value, and error_message provides the error prompt upon failure.

assert {
  condition     = azurerm_storage_account.example.versioning_enabled == true
  error_message = "Versioning must be enabled for the storage account."
}

1.5.1.1.6. Building a Reusable Test Structure

To improve the maintainability and reusability of Terraform module unit tests, it is recommended to organize test files using the following directory structure:

module/
├── main.tf
├── variables.tf
├── outputs.tf
├── unit-tests/
│   ├── test_account_naming.tftest.hcl
│   ├── test_versioning.tftest.hcl
│   └── mocks/
│       └── azurerm.tfmock.hcl

unit-tests/: Located under the module root directory, dedicated to storing unit test files.
unit-tests/mocks/: Stores shared Mock data files for import by multiple test files.

This structure allows for modular test logic and centralized management of Mock data, enhancing the maintainability and scalability of tests.

1.5.1.1.7. Summary

Terraform unit testing is an important means of guaranteeing module quality and improving development efficiency. By reasonably using the terraform test command, Mock Providers, and a clear test structure, you can build an efficient and maintainable testing system. It is recommended to introduce unit testing early in the module development phase and continuously improve test coverage to ensure the module remains stable and reliable throughout its evolution.

Unit Testing