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.

Checked by CookiesForAI on : license and last change of the skill re-read from GitHub.

Written by

Install Terraform test

Install this skill with the skills CLI

Terminal
npx skills add hashicorp/agent-skills --skill terraform-test

Or, for Claude Code, add HashiCorp's plugin marketplace

Terminal
claude plugin marketplace add hashicorp/agent-skills

Then install the terraform plugin, which holds all 16 Terraform skills

Terminal
claude plugin install terraform@hashicorp

In 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. Checked by CookiesForAI on : license and last change of the skill re-read from GitHub. 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 ) 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 ). See where each agent looks for skills.

We also list this company's other pages: Terraform MCP server.

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 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.

Lists that include terraform-test