terraform-test
Terraform test
terraform-test is HashiCorp's agent skill for writing and running Terraform's built-in tests: .tftest.hcl files with run blocks, assertions, expected failures, mock providers and CI pipelines.
Install Terraform test
Install this skill with the skills CLI
npx skills add hashicorp/agent-skills --skill terraform-testOr, for Claude Code, add HashiCorp's plugin marketplace
claude plugin marketplace add hashicorp/agent-skillsThen install the terraform plugin, which holds all 16 Terraform skills
claude plugin install terraform@hashicorpIn Codex, HashiCorp's README says to add the repository's .agents/plugins/marketplace.json as a repository marketplace, then install the terraform plugin.
Or paste this into your coding agent: Install the agent skill terraform-test from github.com/hashicorp/agent-skills.
A skill can include scripts that run on your computer, so read its source first.
What Terraform test does
terraform-test is an agent skill from HashiCorp that teaches an agent the terraform test framework. It covers test files ending in .tftest.hcl or .tftest.json, run blocks with their own variables and module sources, assert blocks with clear error messages, and expect_failures for checking that validation rules reject bad input. Tests can run in plan mode, which creates nothing, or apply mode, which builds real resources and destroys them afterwards in reverse order.
The skill in terraform-test gives ready patterns for common checks: outputs, conditional resources, resource counts, tags, data source lookups, sequential runs that pass values between each other, parallel runs, shared state keys and multiple aliased providers. It recommends naming plan-mode files *_unit_test.tftest.hcl and apply-mode files *_integration_test.tftest.hcl so CI can run them separately, and defaulting to plan mode unless real behavior must be tested.
Three reference files in the terraform-test folder load only when needed. One covers mock providers, which need Terraform 1.7.0 or newer and let tests run without cloud credentials. One gives GitHub Actions and GitLab CI pipelines that run unit tests on every pull request and integration tests on merge. The last is a complete example suite for a VPC module.
When to use Terraform test
- You have a Terraform module with no tests and want unit tests that run in plan mode.
- You want to test a module without cloud credentials by mocking the provider.
- You need to check that a variable's validation rule rejects bad values.
- You want Terraform tests running in GitHub Actions or GitLab CI.
When to pick something else
- Reviewing the output of terraform plan before an apply: HashiCorp's 20 skills (read 2026-10-01) include none made only for that job.
- Testing Terraform Policy files (.policytest.hcl): use terraform-policy from the same repository.
What Terraform test needs
- Terraform CLI with the test command; mock providers need Terraform 1.7.0 or newer
- Cloud credentials only for apply-mode integration tests
Which agents Terraform test works in
HashiCorp documents Terraform test for GitHub Copilot, Claude Code, Codex, Cursor, OpenCode, IBM Bob. The open skills CLI also installs it into 78 agents, including Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode (we listed it with the CLI on October 1, 2026). See where each agent looks for skills.
Terraform test license
Terraform test is published under MPL-2.0. MPL-2.0 is a file-level copyleft license: you can use and copy the skill in any project, including closed source ones, but if you distribute changed versions of its files, those files stay under MPL-2.0 and must be shared as source.
Questions people ask
Does HashiCorp have an agent skill that reviews terraform plan output?
No. On 2026-10-01 hashicorp/agent-skills held 20 skills, 16 for Terraform and 4 for Packer, and none is dedicated to reading or reviewing terraform plan output. The closest is terraform-test, which can run tests in plan mode against assertions you write.
Can I copy this HashiCorp skill into my own repository?
Yes. The skill is MPL-2.0. You can copy and use it in any project, open or closed source. If you change its files and distribute them, the changed files must stay MPL-2.0 and be available as source; your own files are not affected.
Related skills for infrastructure as code
- Terraform skill: terraform-skill is Anton Babenko's agent skill for writing, testing and reviewing Terraform and OpenTofu, which names the risk before it writes code and never recommends a production apply without a reviewed plan.
- Refactor module: refactor-module is HashiCorp's agent skill for turning a monolithic Terraform configuration into reusable modules, with typed interfaces, documentation, tests and a state migration that recreates no resources.
- Terraform policy: terraform-policy is HashiCorp's agent skill for writing Terraform Policy files (.policy.hcl), testing them with .policytest.hcl, and converting Sentinel policies to the new format.
- Terraform style guide: terraform-style-guide is HashiCorp's agent skill for writing and reviewing Terraform HCL to the official style conventions: file layout, formatting, naming, typed variables, version pinning and a review checklist.