# Terraform Test

Comprehensive guide for writing and running Terraform tests.

- Repository: https://github.com/hashicorp/agent-skills (911 stars)
- Category: Testing
- License: MPL-2.0
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add hashicorp/agent-skills --skill terraform-test -g -a claude-code -y`
Codex: `npx skills add hashicorp/agent-skills --skill terraform-test -g -a codex -y`
Cursor: `npx skills add hashicorp/agent-skills --skill terraform-test -g -a cursor -y`
Gemini CLI: `npx skills add hashicorp/agent-skills --skill terraform-test -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add hashicorp/agent-skills`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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 settings
test {
  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"
}

The rest: https://github.com/hashicorp/agent-skills/blob/HEAD/plugins/terraform/skills/terraform-test/SKILL.md