terraform-test
Comprehensive guide for writing and running Terraform tests with assertions, mocking, and module validation.
- Write test files using
.tftest.hclsyntax with run blocks that execute in plan or apply mode, supporting sequential and parallel execution with optional state isolation - Assert conditions on resource attributes, outputs, and data sources; use
expect_failuresto validate that invalid inputs are properly rejected - Mock providers (Terraform 1.7.0+) simulate infrastructure behavior without creating real resources, enabling fast unit tests without cloud costs or credentials
- Test local modules and public registry modules with variable overrides, provider configuration, and cross-run output references for dependency validation
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 examplesreferences/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): Containsrunblocks 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) orplan(validates logic only)
More from hashicorp/agent-skills
terraform-style-guide
Generate Terraform HCL code following HashiCorp's official style conventions and best practices. Use when writing, reviewing, or generating Terraform configurations.
4.5Krefactor-module
Transform monolithic Terraform configurations into reusable, maintainable modules following HashiCorp's module design principles and community best practices.
2.2Kterraform-stacks
Comprehensive guide for working with HashiCorp Terraform Stacks. Use when creating, modifying, or validating Terraform Stack configurations (.tfcomponent.hcl, .tfdeploy.hcl files), working with stack components and deployments from local modules, public registry, or private registry sources, managing multi-region or multi-environment infrastructure, or troubleshooting Terraform Stacks syntax and structure.
2.1Kprovider-resources
Implement Terraform Provider resources and data sources using the Plugin Framework. Use when developing CRUD operations, schema design, state management, and acceptance testing for provider resources.
1.4Kterraform-search-import
Discover existing cloud resources using Terraform Search queries and bulk import them into Terraform management. Use when bringing unmanaged infrastructure under Terraform control, auditing cloud resources, or migrating to IaC.
1.4Knew-terraform-provider
Use this when scaffolding a new Terraform provider.
1.3K