skilld
All skills
hashicorp avatar

/terraform-test

@4451cec official
by hashicorphashicorp/agent-skills880 stars
130

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.

Ask your Agent

Use this Skill: https://skilld.dev/gh/hashicorp/agent-skills/terraform-test

This session only. Nothing lands on disk.

referencesCI_CD.md

≈483 tokens on demand. Your agent reads this file only when SKILL.md points to it.

CI/CD Integration

GitHub Actions

name: Terraform Tests

on:
  pull_request:
    branches: [ main ]
  push:
    branches: [ main ]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.9.0

      - run: terraform fmt -check -recursive
      - run: terraform init
      - run: terraform validate
      - name: Run unit tests (plan mode, no credentials needed)
        run: terraform test -filter=unit_test -verbose

  integration-tests:
    runs-on: ubuntu-latest
    needs: unit-tests
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.9.0

      - run: terraform init
      - name: Run integration tests
        run: terraform test -filter=integration_test -verbose
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

GitLab CI

stages:
  - validate
  - test

terraform-unit-tests:
  image: hashicorp/terraform:1.9
  stage: validate
  before_script:
    - terraform init
  script:
    - terraform fmt -check -recursive
    - terraform validate
    - terraform test -filter=unit_test -verbose

terraform-integration-tests:
  image: hashicorp/terraform:1.9
  stage: test
  before_script:
    - terraform init
  script:
    - terraform test -filter=integration_test -verbose
  only:
    - main

Recommended CI Strategy

  • Run unit tests (plan mode + mock tests) on every PR — fast, no credentials needed
  • Run integration tests only on merge to main or nightly — requires cloud credentials
  • Use -filter=unit_test / -filter=integration_test to separate test types based on naming convention
  • Store cloud credentials as CI secrets, never in code

Source: SKILL.md on GitHub

Third-party checks

No alerts17d5 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    This skill provides a comprehensive guide for Terraform testing. It follows security best practices, particularly in its CI/CD documentation and the use of mock providers for isolated testing.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer7mo

    1/1 file flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 4451cec. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 2 months ago

Capability

Other metadata
metadata
{
  "lifecycle-status": "active",
  "copyright": "Copyright IBM Corp. 2026",
  "version": "0.0.2"
}

Topics

README badge

README badge for hashicorp/agent-skills/terraform-test

What it does

Guides writing and running Terraform tests using the built-in testing framework (.tftest.hcl files), including run blocks for validating configuration, assertions to check resource behavior, and mock providers to simulate infrastructure without real resources. Covers plan-mode unit tests, apply-mode integration tests, testing outputs and validation rules, and structuring tests in CI/CD pipelines.

Generated from the current SKILL.md.

Frequently asked

What Terraform version do I need for this skill?
Terraform 1.6.0+ supports the testing framework. Mock providers require Terraform 1.7.0 or later. The skill includes version checks and will guide you to skip unsupported features if your version is below 1.7.
Can I test modules from git repositories or HTTP sources?
No. Test files only support local module paths and registry modules. You must convert git or HTTP sources to local modules before testing them.
What's the difference between plan mode and apply mode tests?
Plan mode (`command = plan`) validates logic without creating real resources — faster and no credentials needed. Apply mode (`command = apply`) creates actual infrastructure and is slower but tests real resource behavior. Use unit tests in plan mode and integration tests in apply mode.
How do I test modules in parallel?
Set `parallel = true` on individual run blocks (Terraform 1.9.0+) or enable test-wide parallel execution with `test { parallel = true }`. Parallel tests use isolated state files and should not depend on each other.
How are resources cleaned up after tests run?
Resources created by apply-mode tests are destroyed in reverse run block order automatically. Use `terraform test -no-cleanup` to skip cleanup for debugging.

Generated from the current SKILL.md. These answers refresh after source changes.