Terraform Test skill for Claude Code: write and run .tftest.hcl tests

HashiCorp's skill that teaches Claude to write and run Terraform tests (.tftest.hcl) for your modules.

Installs: 9K; on skills.sh
Stars: 911; on GitHub
Files: 3; besides SKILL.md
Updated: Oct 2026; last repo commit

terraform-test makes Claude write test files with run and assert blocks, pick plan mode or apply mode, mock providers, and run terraform test. It triggers when you ask for .tftest.hcl files, test scenarios, assertions, mocks or help with test syntax and execution.

It needs the Terraform CLI. Apply-mode tests create real resources, so check which mode a test uses before you run it. The skill bundles 3 reference files and no scripts.

Good for

Terraform users who want tests for modules and configurations
Teams that want unit tests on every pull request and integration tests after merge
Anyone debugging a failing assertion or a Terraform test syntax error

Install terraform-test

Claude Code

Copy this prompt.

Install the terraform-test skill in Claude Code. Run this command:

claude plugin marketplace add hashicorp/agent-skills
claude plugin install terraform@hashicorp

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both. The plugin route installs the whole terraform bundle, which has 16 skills in the repo. The skills CLI and folder routes install only terraform-test. You also need the Terraform CLI on your machine.

From the project README. Source.

What's in the skill

When it loads

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.

Sections in SKILL.md

Reference Files
Core Concepts
File Structure
Test File Structure
Run Block
Common Test Patterns
Validate outputs
Conditional resources
Resource counts
Tags
Data sources
Validation rules
Sequential tests with dependencies
Plan options (refresh-only, targeted)
Parallel modules
State key sharing

Key facts

Author: HashiCorp, in HashiCorp's own hashicorp/agent-skills repo (SKILL.md frontmatter says Copyright IBM Corp. 2026)
License: MPL-2.0 (plugin manifest and README)
Version: 0.0.2 in the frontmatter, lifecycle-status active
Installs on skills.sh: 8,957 as of 2026-11-02
GitHub stars: 911 for the whole hashicorp/agent-skills repo, 2026-11-02
Last change to this skill: 2026-10-28
What is inside: 4 files including SKILL.md: 3 reference files (MOCK_PROVIDERS.md, CI_CD.md, EXAMPLES.md)
Part of: The terraform plugin in the hashicorp marketplace (16 skills)
Needs: The Terraform CLI. Mock providers need Terraform 1.7.0 or newer; parallel and state_key are marked v1.9.0.
Works in: Claude Code and Codex plugins; the README also lists GitHub Copilot, Opencode, Cursor and IBM Bob for single skills
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass

What it includes

Tests live in a tests/ folder as .tftest.hcl or .tftest.json files with run blocks.
SKILL.md describes a test file as a set of run blocks, each a scenario with its own variables, providers and assertions.
Write · Test files
Use *_unit_test and *_integration_test names so CI can filter them.
Plan-mode files end in _unit_test.tftest.hcl and apply-mode files end in _integration_test.tftest.hcl.
Unit and integration naming
Each run block sets a command, variables, a module, plan options and assertions.
Run blocks
An assert must hold to pass, and expect_failures passes a test when a check fails.
Assert and expect_failures
Checks that an output is set and matches a pattern such as a vpc- prefix.
Validate outputs
Checks that a resource is not created when its toggle variable is off.
Conditional resources
Checks that a variable such as instance_count creates the right number of resources.
Resource counts
Checks that tag values set through variables land on the resource.
Tags
Checks that a data source lookup returns a valid id.
Data sources
Uses expect_failures so a test passes when a bad input is rejected.
Validation rules
Chains run blocks so a later test reads outputs from an earlier setup run.
Sequential tests
Runs refresh-only or targeted plans from a run block.
Plan options
Runs independent module tests side by side with parallel = true.
Parallel modules
Lets run blocks share state with state_key.
State key sharing
Shows how resources are destroyed in reverse order, such as S3 objects before the bucket.
Cleanup ordering
Points a run block at a specific provider alias, such as a second region.
Aliased providers
Uses alltrue and for expressions to check every item in a set.
Complex conditions
Runs terraform test for all files, one file, one run block, or a custom folder.
The list covers a plain run, a file path, -filter, -test-directory, -verbose and -no-cleanup.
Try: “Write a plan-mode test for my vpc module that checks the vpc_id output, then run terraform test -verbose.”
Runs code · terraform test commands
Shows mock providers for credential-free tests, on Terraform 1.7.0 or newer.
Read · references/MOCK_PROVIDERS.md
Shows GitHub Actions and GitLab CI pipelines that split unit and integration tests.
Read · references/CI_CD.md
Holds a full example suite with unit, integration and mock tests for a VPC module.
Read · references/EXAMPLES.md
Maps 5 common problems, such as failing assertions and missing credentials, to fixes.
Troubleshooting table

From the official docs

Permissions

Medium risk

Integration tests created with this skill can build and then destroy real cloud resources when they run. Run them against a test account, and keep to command = plan and mock providers until you trust the setup.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Apply-mode tests create real resources
SKILL.md says apply is the default command and creates real resources. Ask Claude for command = plan unless you mean to build something, and run against a test account. github.com
-no-cleanup leaves resources behind
SKILL.md offers terraform test -no-cleanup to skip cleanup for debugging. Resources it leaves are yours to find and destroy. github.com
The CI examples use cloud secrets
references/CI_CD.md passes AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from CI secrets to integration tests. Use a limited test-account key there. github.com

Technical details

Turning on read-only	There is no read-only switch. SKILL.md describes command = plan as the mode that validates logic, and its file-layout comment calls plan-mode tests "fast, no resources".
Scopes	Writes .tftest.hcl files in your module Runs terraform test, which can create and then destroy real resources in apply mode

Questions

What does the terraform-test skill do?

It teaches Claude how to write and run Terraform tests. Claude creates .tftest.hcl files with run blocks and assertions, chooses plan or apply mode, adds mock providers when needed, and runs terraform test.

Is it an official HashiCorp skill?

Yes. It lives in HashiCorp's own hashicorp/agent-skills repo, and the marketplace file there describes the repo as "Official HashiCorp product plugins and Agent Skills for Claude Code".

How do I install it in Claude Code?

Use the install box above. The plugin route installs the whole terraform bundle of 16 skills, and the skills CLI or folder routes install only this one. You also need Terraform installed.

Do the tests create real resources?

Apply-mode tests do. SKILL.md says apply is the default and creates real resources, while plan mode only validates logic. Mock providers (Terraform 1.7.0 or newer) simulate a provider and work only with plan mode.

Do I need cloud credentials?

Only for integration tests. references/CI_CD.md says unit tests in plan mode or with mocks need no credentials, and integration tests need cloud credentials stored as CI secrets, never in code.

Can I use it in the Claude app or Codex?

The skill runs terraform test on your machine, so it fits Claude Code or Codex better than the Claude app. HashiCorp documents a Codex plugin route, shown in the install box. It documents no Claude app route.

Is it safe?

Treat apply-mode tests like any Terraform apply. They create real resources, and terraform test -no-cleanup leaves them in place. Our advice: start with plan-mode tests and mock providers, and use credentials for a test account.

Information

updated Nov 2, 2026

Repository: hashicorp/agent-skills
Folder: plugins/terraform/skills/terraform-test

hashicorp/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 9

hashicorp/agent-skills README · github.com
Terraform plugin README · github.com
marketplace.json · github.com
terraform-test SKILL.md · github.com
terraform plugin.json · github.com
skills.sh listing · skills.sh
references/MOCK_PROVIDERS.md · github.com
references/CI_CD.md · github.com
references/EXAMPLES.md · github.com