---
title: "terraform-test skill: write and run Terraform tests with an agent"
canonical_url: https://cookiesforai.app/skills/hashicorp/terraform-test
last_updated: 2026-10-02T01:58:30+02:00
type: skill
summary: "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: "npx skills add hashicorp/agent-skills --skill terraform-test"
related:
  - "https://cookiesforai.app/skills/antonbabenko/terraform-skill"
  - "https://cookiesforai.app/skills/hashicorp/refactor-module"
  - "https://cookiesforai.app/skills/hashicorp/terraform-policy"
  - "https://cookiesforai.app/skills/hashicorp/terraform-style-guide"
---

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

| Fact | Value |
|---|---|
| Publisher | HashiCorp (official, own GitHub account) |
| Source | https://github.com/hashicorp/agent-skills/tree/HEAD/plugins/terraform/skills/terraform-test |
| License | MPL-2.0 |
| Repository stars | 881 on 2026-10-02 |
| Skill name | terraform-test |
| Version | 0.0.2 (from its SKILL.md, https://github.com/hashicorp/agent-skills/blob/HEAD/plugins/terraform/skills/terraform-test/SKILL.md, read 2026-10-02) |
| Category | Infrastructure as code |
| Skill last changed | 2026-08-10 |
| Page updated | 2026-10-02 |
| Facts checked | 2026-10-02 |

## Install

Install this skill with the skills CLI:

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

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

```
claude plugin marketplace add hashicorp/agent-skills
```

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

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

## Ask your coding agent

A skill can include scripts that run on your computer, so read its source first: https://github.com/hashicorp/agent-skills/tree/HEAD/plugins/terraform/skills/terraform-test

```text
Install the agent skill terraform-test from github.com/hashicorp/agent-skills.
```

## What it 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 it

- 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 it 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 it works in

HashiCorp documents it for GitHub Copilot, Claude Code, Codex, Cursor, OpenCode, IBM Bob. The open skills CLI also installs it into 78 agents (listed with the CLI on 2026-10-01).

## License

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

### Related skills for infrastructure as code

- [Terraform skill](https://cookiesforai.app/skills/antonbabenko/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](https://cookiesforai.app/skills/hashicorp/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](https://cookiesforai.app/skills/hashicorp/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](https://cookiesforai.app/skills/hashicorp/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.