Terraform Test

作者 hashicorpf706481af9b8無授權條款890 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫3 天前更新

Comprehensive guide for writing and running Terraform tests. Use when creating test files (.tftest.hcl), writing test scenarios with run blocks, validating infrastructure behavior with assertions, mocking providers and data sources, testing module outputs and resource configurations, or troubleshooting Terraform test syntax and execution.

僅含說明Software DevelopmentDevOps & Cloud
AI 產生的概覽

指導撰寫與執行 Terraform 測試，涵蓋 .tftest.hcl 檔案、run 區塊、斷言、mock 與 CI 整合。

功能
此技能提供撰寫與執行 Terraform 內建測試框架的說明。內容涵蓋測試檔案結構、run 與 assert 區塊、plan 與 apply 模式、provider 與資料來源 mock、模組輸出、state key、平行執行以及清理行為。另附有關於 mock provider、CI/CD 流程與完整範例測試套件的參考文件。
適用情境
適用於建立或排解 Terraform 測試檔案、驗證基礎設施設定行為，或為 Terraform 模組建立單元測試與整合測試。也適合在需要 mock provider 以避免真實憑證，或將測試接入 CI 流程時使用。
執行需求
需要具備內建 test 指令的 Terraform；mock provider 需要 Terraform 1.7.0 或更新版本。apply 模式測試需要 provider 憑證與網路存取以建立真實資源。此技能未附帶指令碼，僅包含說明文件與三份參考文件。

Terraform Test

Terraform's built-in testing framework validates that configuration updates don't introduce breaking changes. Tests run against temporary resources, protecting existing infrastructure and state files.

Reference Files

  • references/MOCK_PROVIDERS.md — Mock provider syntax, common defaults, when to use mocks (Terraform 1.7.0+ only — skip if the user's version is below 1.7)
  • references/CI_CD.md — GitHub Actions and GitLab CI pipeline examples
  • references/EXAMPLES.md — Complete example test suite (unit, integration, and mock tests for a VPC module)

Read the relevant reference file when the user asks about mocking, CI/CD integration, or wants a full example.

Core Concepts

  • Test file (.tftest.hcl / .tftest.json): Contains run blocks that validate your configuration
  • Run block: A single test scenario with optional variables, providers, and assertions
  • Assert block: Conditions that must be true for the test to pass
  • Mock provider: Simulates provider behavior without real infrastructure (Terraform 1.7.0+)
  • Test modes: apply (default, creates real resources) or plan (validates logic only)

File Structure

my-module/├── main.tf├── variables.tf├── outputs.tf└── tests/    ├── defaults_unit_test.tftest.hcl         # plan mode — fast, no resources    ├── validation_unit_test.tftest.hcl        # plan mode    └── full_stack_integration_test.tftest.hcl # apply mode — creates real resources

Use *_unit_test.tftest.hcl for plan-mode tests and *_integration_test.tftest.hcl for apply-mode tests so they can be filtered separately in CI.

Test File Structure

hcl
# Optional: test-wide settingstest {  parallel = true  # Enable parallel execution for all run blocks (default: false)}
# Optional: file-level variables (highest precedence, override all other sources)variables {  aws_region    = "us-west-2"  instance_type = "t2.micro"}
# Optional: provider configurationprovider "aws" {  region = var.aws_region}
# Required: at least one run blockrun "test_default_configuration" {  command = plan
  assert {    condition     = aws_instance.example.instance_type == "t2.micro"    error_message = "Instance type should be t2.micro by default"  }}

Run Block

hcl
run "test_name" {  command  = plan  # or apply (default)  parallel = true  # optional, since v1.9.0
  # Override file-level variables  variables {    instance_type = "t3.large"  }
  # Reference a specific module  module {    source  = "./modules/vpc"  # local or registry only (not git/http)    version = "5.0.0"          # registry modules only  }
  # Control state isolation  state_key = "shared_state"  # since v1.9.0
  # Plan behavior  plan_options {    mode    = refresh-only  # or normal (default)    refresh = true    replace = [aws_instance.example]    target  = [aws_instance.example]  }
  # Assertions  assert {    condition     = aws_instance.example.id != ""    error_message = "Instance should have a valid ID"  }
  # Expected failures (test passes if these fail)  expect_failures = [    var.instance_count  ]}

Common Test Patterns

Validate outputs

hcl
run "test_outputs" {  command = plan
  assert {    condition     = output.vpc_id != null    error_message = "VPC ID output must be defined"  }
  assert {    condition     = can(regex("^vpc-", output.vpc_id))    error_message = "VPC ID should start with 'vpc-'"  }}

Conditional resources

hcl
run "test_nat_gateway_disabled" {  command = plan
  variables {    create_nat_gateway = false  }
  assert {    condition     = length(aws_nat_gateway.main) == 0    error_message = "NAT gateway should not be created when disabled"  }}

Resource counts

hcl
run "test_resource_count" {  command = plan
  variables {    instance_count = 3  }
  assert {    condition     = length(aws_instance.workers) == 3    error_message = "Should create exactly 3 worker instances"  }}

Tags

hcl
run "test_resource_tags" {  command = plan
  variables {    common_tags = {      Environment = "production"      ManagedBy   = "Terraform"    }  }
  assert {    condition     = aws_instance.example.tags["Environment"] == "production"    error_message = "Environment tag should be set correctly"  }
  assert {    condition     = aws_instance.example.tags["ManagedBy"] == "Terraform"    error_message = "ManagedBy tag should be set correctly"  }}

Data sources

hcl
run "test_data_source_lookup" {  command = plan
  assert {    condition     = data.aws_ami.ubuntu.id != ""    error_message = "Should find a valid Ubuntu AMI"  }
  assert {    condition     = can(regex("^ami-", data.aws_ami.ubuntu.id))    error_message = "AMI ID should be in correct format"  }}

Validation rules

hcl
run "test_invalid_environment" {  command = plan
  variables {    environment = "invalid"  }
  expect_failures = [    var.environment  ]}

Sequential tests with dependencies

hcl
run "setup_vpc" {  command = apply
  assert {    condition     = output.vpc_id != ""    error_message = "VPC should be created"  }}
run "test_subnet_in_vpc" {  command = plan
  variables {    vpc_id = run.setup_vpc.vpc_id  }
  assert {    condition     = aws_subnet.example.vpc_id == run.setup_vpc.vpc_id    error_message = "Subnet should be in the VPC from setup_vpc"  }}

Plan options (refresh-only, targeted)

hcl
run "test_refresh_only" {  command = plan
  plan_options {    mode = refresh-only  }
  assert {    condition     = aws_instance.example.tags["Environment"] == "production"    error_message = "Tags should be refreshed correctly"  }}
run "test_specific_resource" {  command = plan
  plan_options {    target = [aws_instance.example]  }
  assert {    condition     = aws_instance.example.instance_type == "t2.micro"    error_message = "Targeted resource should be planned"  }}

Parallel modules

hcl
run "test_networking_module" {  command  = plan  parallel = true
  module {    source = "./modules/networking"  }
  assert {    condition     = output.vpc_id != ""    error_message = "VPC should be created"  }}
run "test_compute_module" {  command  = plan  parallel = true
  module {    source = "./modules/compute"  }
  assert {    condition     = output.instance_id != ""    error_message = "Instance should be created"  }}

State key sharing

hcl
run "create_foundation" {  command   = apply  state_key = "foundation"
  assert {    condition     = aws_vpc.main.id != ""    error_message = "Foundation VPC should be created"  }}
run "create_application" {  command   = apply  state_key = "foundation"
  variables {    vpc_id = run.create_foundation.vpc_id  }
  assert {    condition     = aws_instance.app.vpc_id == run.create_foundation.vpc_id    error_message = "Application should use foundation VPC"  }}

Cleanup ordering (S3 objects before bucket)

hcl
run "create_bucket" {  command = apply
  assert {    condition     = aws_s3_bucket.example.id != ""    error_message = "Bucket should be created"  }}
run "add_objects" {  command = apply
  assert {    condition     = length(aws_s3_object.files) > 0    error_message = "Objects should be added"  }}
# Cleanup destroys in reverse: objects first, then bucket

Multiple aliased providers

hcl
provider "aws" {  alias  = "primary"  region = "us-west-2"}
provider "aws" {  alias  = "secondary"  region = "us-east-1"}
run "test_with_specific_provider" {  command = plan
  providers = {    aws = provider.aws.secondary  }
  assert {    condition     = aws_instance.example.availability_zone == "us-east-1a"    error_message = "Instance should be in us-east-1 region"  }}

Complex conditions

hcl
assert {  condition = alltrue([    for subnet in aws_subnet.private :    can(regex("^10\\.0\\.", subnet.cidr_block))  ])  error_message = "All private subnets should use 10.0.0.0/8 CIDR range"}

Cleanup

Resources are destroyed in reverse run block order after test completion. This matters for dependencies (e.g., S3 objects before bucket). Use terraform test -no-cleanup to skip cleanup for debugging.

Running Tests

bash
terraform test                                        # all teststerraform test tests/defaults.tftest.hcl             # specific fileterraform test -filter=test_vpc_configuration        # by run block nameterraform test -test-directory=integration-tests     # custom directoryterraform test -verbose                              # detailed outputterraform test -no-cleanup                           # skip resource cleanup

Best Practices

  1. Naming: *_unit_test.tftest.hcl for plan mode, *_integration_test.tftest.hcl for apply mode
  2. Test naming: Use descriptive run block names that explain the scenario being tested
  3. Default to plan: Use command = plan unless you need to test real resource behavior
  4. Use mocks for external dependencies — faster and no credentials needed (see references/MOCK_PROVIDERS.md)
  5. Error messages: Make them specific enough to diagnose failures without running the test again
  6. Negative tests: Use expect_failures to verify validation rules reject bad inputs
  7. Variable coverage: Test different variable combinations to validate all code paths — test variables have the highest precedence and override all other sources
  8. Module sources: Test files only support local paths and registry modules — not git or HTTP URLs
  9. Parallel execution: Use parallel = true for independent tests with different state files
  10. Cleanup: Integration tests destroy resources in reverse run block order automatically; use -no-cleanup for debugging
  11. CI/CD: Run unit tests on every PR, integration tests on merge (see references/CI_CD.md)

Troubleshooting

IssueSolution
Assertion failuresUse -verbose to see actual vs expected values
Missing credentialsUse mock providers for unit tests
Unsupported module sourceConvert git/HTTP sources to local modules
Tests interferingUse state_key or separate modules for isolation
Slow testsUse command = plan and mocks; run integration tests separately

References

來源與署名

來源：hashicorp/agent-skills位於plugins/terraform/skills/terraform-test提交f706481

授權條款： 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 hashicorp/agent-skills 的技能

Terraform Style Guide

hashicorp

依照 HashiCorp 官方風格慣例與最佳實務產生並審查 Terraform HCL 程式碼。

DevOps & Cloud8903 天前更新

Terraform Stacks

hashicorp

指導撰寫與驗證 HashiCorp Terraform Stacks 設定檔，用於多環境基礎架構。

DevOps & Cloud8903 天前更新

Terraform Policy

hashicorp

撰寫、測試與轉換 Terraform Policy 檔案（.policy.hcl、.policytest.hcl）以及 Sentinel 政策。

Software Development8903 天前更新

Refactor Module

hashicorp

引導將單體式 Terraform 組態重構為可重複使用、易於維護的模組，並涵蓋移轉與測試。

Software Development8903 天前更新

Provider Resources

hashicorp

Implement Terraform Provider resources and data sources using the Plugin Framework: CRUD operations, schema design, plan modifiers and validators, not-found handling, waiters for eventually consistent APIs, import support, resource design principles, and required acceptance test coverage. Use when adding or changing a resource or data source, deciding whether an API concept should be a resource, wiring a resource to the provider's configured client, handling drift or resource-not-found, or reviewing a resource implementation before submission.

待分類8903 天前更新

Provider Framework Migration

hashicorp

指導將 Terraform provider 資源從 Plugin SDKv2 遷移到 Plugin Framework，並使用混合式 provider。

Software Development8903 天前更新

更多Software Development技能

Playground

anthropics

精選

建立自成一體的互動式 HTML 遊樂場，包含控制項、即時預覽與可複製的提示詞輸出。

Software Development37K今天更新

M5 Onboard

anthropics

精選

透過 USB 偵測 M5Stack ESP32 開發板，燒錄 UIFlow 2.0 韌體並安裝 MicroPython 應用程式套件。

Software Development37K今天更新

Cardputer Buddy

anthropics

精選

指導迭代 Cardputer-Adv 的 MicroPython 應用程式套件：新增應用程式、透過 USB 序列埠推送檔案、查看日誌並執行 REPL 指令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精選

依據從遠端來源取得的 Web Interface Guidelines 審查 UI 程式碼，並以 file:line 形式回報問題。

Software Development32K5 週前更新

Vercel React Native Skills

vercel-labs

精選

React Native 與 Expo 最佳實務規則，涵蓋清單效能、動畫、導覽、UI 模式、狀態與 monorepo 設定。

Software Development32K5 週前更新

Vercel React Best Practices

vercel-labs

精選

Vercel 的 React 與 Next.js 效能指南，以 70 條規則的形式用於撰寫、審查與重構程式碼。

Software Development32K5 週前更新