Terraform Test

This is the Terraform test framework reference you'll actually use when writing `.tftest.hcl` files. It covers the full structure: run blocks with plan vs apply modes, assertions on outputs and resource attributes, sequential tests that chain state, and parallel execution patterns. The mock provider section only applies to Terraform 1.7.0+, so it'll tell you to skip that if you're on an older version. What I like here is the naming convention guidance (use `*_unit_test.tftest.hcl` for plan mode, `*_integration_test.tftest.hcl` for apply mode) since that makes CI filtering dead simple. Also includes CI/CD pipeline examples and a complete VPC module test suite in the references.

skills.sh installs: 9.2K
GitHub stars: 924
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add hashicorp/agent-skills --skill terraform-test --agent claude-code

Installs into .claude/skills of the current project.

Files

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)