Terraform tests
Writes and runs Terraform's native tests in .tftest.hcl files: run blocks, assertions, plan and apply modes, expect_failures, mock providers and CI pipelines. Use when adding tests to a Terraform module or fixing a failing terraform test.
terraform-test- Author
- HashiCorp
- Source
- hashicorp/agent-skills/plugins/terraform/skills/terraform-test @ 5e30fa5
- License
- MPL-2.0
About this skill
What it does
The skill covers Terraform's built-in test framework: .tftest.hcl files made of run blocks with assert conditions. It explains the file layout — a test block for parallel runs, file-level variables that override every other source, provider blocks — and the arguments of a run: command = plan or apply, a module to test (local or registry, not git or HTTP), state_key for shared state, plan_options for refresh-only or targeted plans, and expect_failures for negative tests of validation rules. Patterns cover outputs, conditional resources, counts, tags, chained runs that read run.<name>.<output>, and aliased providers.
The defaults it pushes: plan mode unless real resources are needed, file names *_unit_test.tftest.hcl for plan tests and *_integration_test.tftest.hcl for apply tests so CI can split them with -filter. Resources from apply runs are destroyed in reverse order unless -no-cleanup is set.
Three references load on demand. references/MOCK_PROVIDERS.md covers mock_provider with mock_resource and mock_data defaults (Terraform 1.7 and later) and where mocks do not fit. references/CI_CD.md has GitHub Actions and GitLab CI pipelines: unit tests on every PR without credentials, integration tests on merge to main with cloud secrets. references/EXAMPLES.md is a complete unit, integration and mock suite for a VPC module.
When to use it, and when not
Use it to add tests to a module, to prove a validation block rejects bad input, to wire terraform test into CI, or to fix a broken test file.
Apply-mode tests create real infrastructure and need cloud credentials. Go acceptance tests for a provider and .policytest.hcl files are other skills.
How to run it
We do not copy this skill: its files are under MPL-2.0, a file-level copyleft licence outside the set we copy under. Install it from HashiCorp's repository with the button to the source: one skill via npx skills add hashicorp/agent-skills/plugins/terraform/skills/terraform-test, or the whole terraform plugin, in Claude Code claude plugin marketplace add hashicorp/agent-skills and claude plugin install terraform@hashicorp. In Codex: codex plugin marketplace add hashicorp/agent-skills, then install terraform from /plugins and start a new session. In Claude Code, the plugin's skill may carry a prefix, as /terraform:terraform-test.
- Claude Code:
/terraform-test, or ask for the skill by name. - Codex:
$terraform-test. - Cursor: type
/in the Agent chat and pickterraform-test.
Example: /terraform-test Add plan-mode tests for modules/vpc: default CIDR, no NAT gateway when it is disabled, and an invalid environment rejected.
How it differs from similar skills
Unit test writer is the general method — find the public behavior, list edge cases, check that tests can fail — for the project's own language and framework; it knows nothing about HCL. Terraform provider test patterns is for provider authors writing Go acceptance tests with terraform-plugin-testing. Terraform policy files handles .policytest.hcl and sends .tftest.hcl work here, as does Refactor Terraform into modules for testing a new module.
Install
This skill is not copied to the catalog: its licence allows a copy only under the same licence, and the catalog does not copy under such licences. Install it from the author's repository.
Connect through AnyModel API
This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.
AnyModel