What you'll learn: This guide explains what Terratest is, how it compares to Terraform tests, and walks you through a Terratest tutorial with runnable Terratest examples and CI/CD integration. You'll leave with a working test, a GitHub Actions workflow, and a path to GitOps with Terrateam.

## Introduction Making Terraform code changes without automated tests is a gamble. A small refactor can break a module, create security drift, or slow your release process. Terratest and terraform test give you two complementary ways to bring testing discipline to Infrastructure as Code (IaC). In this post, you'll learn what Terratest is, how it compares to Terraform's built-in testing, and how to implement a practical, CI-ready testing workflow. We'll also show where [Terrateam](https://terrateam.io/) fits in to optimize GitOps-native plans, applies, and policy checks right in your pull requests.

⚡ ⚡ ⚡

## What is Terratest? Terratest is an open-source Go library from Gruntwork that helps you write automated tests for infrastructure. It provides helpers to run Terraform, validate outputs, hit real endpoints, and clean up resources - even with retries for flaky cloud calls. You write tests in Go, run them with go test, and exercise your infrastructure as close to reality as you need (from unit-ish to full integration). Why teams use Terratest: * **Realistic coverage** - stand up ephemeral infrastructure, assert behavior, then tear it down. * **Go ecosystem** - use Go's testing, assertions, and tooling. * **Flexibility** - test Terraform, Packer, Kubernetes/Helm, and more, not just .tf files. ### Terratest vs. Terraform test Terraform has a native testing framework via the terraform test command and \*.tftest.hcl files. It validates modules and root modules using declarative runs and assertions tied closely to Terraform plans/applies. Terraform is fast and great for module contracts. By contrast, Terratest runs outside Terraform, in Go, and can perform complete end-to-end checks against deployed infrastructure. **At a glance: Terratest vs. Terraform test** | | Terratest | Terraform test | | :---- | :---- | :---- | | **Language and style** | Imperative Go code using the testing package | Declarative HCL test files (run blocks and asserts) | | **Scope** | Excels at integration tests - provision, check live behavior (HTTP, ports, IAM), and then destroy | Excellent for module interface and plan-level assertions, can validate during plan/apply | | **Tooling and ecosystem** | Full Go ecosystem including assert libs and parallel tests, cross-tool coverage including Kubernetes, Helm, and Packer) | Native Terraform CLI, easy for module authors and quick CI lint-like checks | **Recommendation:** Use both. Start with terraform test to lock down inputs/outputs and plan-time behaviors. Add Terratest for higher-confidence integration tests that touch real cloud services.

⚡ ⚡ ⚡

## How to write a simple test In this Terratest tutorial, you'll learn how to write a minimal test for a Terraform module that provisions an S3 bucket (or any simple resource). The test will: 1. Initialize and apply the module in a temporary workspace 2. Assert an output value 3. Destroy resources on completion, whether pass or fail ### Project layout ``` repo/ ├─ modules/ │ └─ bucket/ │ ├─ main.tf │ ├─ variables.tf │ └─ outputs.tf └─ test/ └─ bucket_test.go ``` ### Go module setup Initialize Go in the repo root and pull Terratest: ```bash go mod init example.com/iac-repo go get github.com/gruntwork-io/terratest/modules/terraform ``` Terratest provides Terraform helpers with sensible retries for transient cloud errors. **bucket_test.go** ```go package test import ( "path/filepath" "testing" "github.com/gruntwork-io/terratest/modules/terraform" "github.com/stretchr/testify/require" ) func TestBucketModule(t *testing.T) { t.Parallel() // Path to the Terraform code we want to test tfDir := filepath.Join("modules", "bucket") // Configure Terraform with default retryable errors opts := &terraform.Options{ TerraformDir: tfDir, Vars: map[string]interface{}{ "bucket_name": "tt-example-%[1]d", // assume variable in module }, } // Ensure cleanup even if test fails defer terraform.Destroy(t, opts) terraform.InitAndApply(t, opts) // Validate an output bucketId := terraform.Output(t, opts, "bucket_id") require.NotEmpty(t, bucketId, "expected bucket_id output to be set") } ``` ### What this does: * terraform.InitAndApply provisions the module * You assert the bucket_id output exists * defer Destroy ensures cleanup Use environment variables or a test fixture to inject unique names to avoid collisions when running tests in parallel. Run it locally: ```bash AWS_REGION=us-east-1 go test -v ./test -timeout 30m ``` This is one of many terratest examples you can extend with HTTP checks, IAM policy validations, or Kubernetes probes.

⚡ ⚡ ⚡

## CI/CD integration You can run Terratest in any CI. Many teams start with GitHub Actions because it's close to their PR workflow and secrets. A simple workflow might: * Check out your project code from GitHub and set up Go. * Assume cloud credentials (OIDC recommended). * Run go test ./test. * Publish artifacts (logs, JUnit) for visibility. **Why this matters:** CI ensures every pull request runs tests automatically, blocking merges when infrastructure behavior regresses. If you're on a GitOps path, Terrateam takes this a step further by centralizing plans, applies, and policies in pull requests: open a PR, it plans; merge, it applies - at scale and with audit trails. It's GitOps-native and supports Terraform and OpenTofu today. ## Example Terratest GitHub Actions workflow ```yaml name: terratest on: pull_request: paths: - "modules/**" - "test/**" workflow_dispatch: {} jobs: test: runs-on: ubuntu-latest permissions: id-token: write # for OIDC contents: read steps: - uses: actions/checkout@v4 - name: Setup Go uses: actions/setup-go@v5 with: go-version: "1.22" - name: Configure AWS creds via OIDC uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_IAM_ROLE_ARN }} aws-region: us-east-1 - name: Run Terratest run: go test -v ./test -timeout 30m - name: Upload test artifacts uses: actions/upload-artifact@v4 with: name: terratest-logs path: | **/terraform.tfstate **/*.log ``` You can also adopt a pre-built action maintained by the community to run Terratest, but rolling your own keeps dependencies minimal and lets you tune caching and IAM.

⚡ ⚡ ⚡

## Terratest code examples ### 1) Validating a public HTTP endpoint ```go package test import ( "net/http" "testing" "time" "github.com/gruntwork-io/terratest/modules/http-helper" "github.com/gruntwork-io/terratest/modules/terraform" ) func TestServiceResponds200(t *testing.T) { t.Parallel() opts := &terraform.Options{TerraformDir: "../modules/service"} defer terraform.Destroy(t, opts) terraform.InitAndApply(t, opts) url := terraform.Output(t, opts, "service_url") maxRetries := 15 timeBetween := 10 * time.Second http_helper.HttpGetWithRetry( t, url, nil, 200, "OK", maxRetries, timeBetween, ) } ``` **Why it helps:** It proves the module deploys a working endpoint, not just a syntactically valid plan. ### 2) Asserting Terraform output types and values ```go package test import ( "testing" "github.com/gruntwork-io/terratest/modules/terraform" "github.com/stretchr/testify/assert" ) func TestOutputs(t *testing.T) { opts := &terraform.Options{TerraformDir: "../modules/network"} defer terraform.Destroy(t, opts) terraform.InitAndApply(t, opts) vpcId := terraform.Output(t, opts, "vpc_id") publicSubnets := terraform.OutputList(t, opts, "public_subnet_ids") assert.Regexp(t, "^vpc-", vpcId) assert.GreaterOrEqual(t, len(publicSubnets), 2) } ``` **Why it helps:** It catches regressions in outputs that downstream modules rely on. ### 3) Combining Terraform test with Terratest Use terraform test to assert plan-time constraints, then run Terratest for runtime behavior: **tests/network.tftest.hcl** ```hcl run "plan_module" { command = plan variables { cidr_block = "10.0.0.0/16" } assert { condition = length(outputs.public_subnet_ids.value) >= 2 error_message = "At least two public subnets are required." } } ``` **CI sequence:** terraform test (fast, contract checks) → go test (integration). This layered approach strikes a balance between speed and confidence.

⚡ ⚡ ⚡

## CI/CD with Terrateam (GitOps-native) While GitHub Actions or any CI can execute tests, you still need a reliable way to orchestrate plans and apply them across many workspaces with policy, review gates, and audit trails. Terrateam is purpose-built for that: * **PR-native plans and applies** - open a PR to get a terraform plan as a comment or check, then merge to apply. * **GitOps-native architecture** - no brittle glue, as Terrateam operates directly in your repos and workflows. * **Scale to thousands of workspaces** - built for monorepos or many repos with complex dependencies. * **Enterprise features** - policy enforcement, drift detection, audit trails, and simple pricing without hidden resource fees. In practice, you combine them like this: 1. **Push branch / open PR** 2. **CI runs tests:** terraform test + Terratest 3. **Terrateam posts the plan** in the PR with an impact summary 4. **Reviewers approve** 5. **Merge to apply** via Terrateam, with logs and audit trail attached to the PR Using a GitHub Action gives you both testing confidence and operational safety within pull requests.

⚡ ⚡ ⚡

## Practical tips and pitfalls * **Control blast radius** - in Terratest, target small, well-scoped modules first (network, IAM roles), keep timeouts realistic, and always Destroy. * **Parallelize carefully** - use t.Parallel() but avoid naming collisions (random suffixes, isolated states) * **Use OIDC in CI** - prefer short-lived credentials over long-lived keys when running tests in GitHub Actions (see Terrateam's [CI/CD Terraform guide](https://terrateam.io/blog/ci-cd-pipeline-for-terraform) for examples) * **Cache providers/modules** - speed up CI by caching .terraform or using a shared module mirror where possible * **Fail fast, log richly** - upload terraform logs and tfstate (sanitized) as CI artifacts to debug flaky tests

⚡ ⚡ ⚡

## Conclusion Testing Terraform isn't optional at scale. Use terraform test to lock down module contracts and **Terratest** for realistic, integration-level confidence. Then run both automatically in CI so every pull request proves infrastructure behavior before merge. Streamline your workflow - plans, applies, policy, drift detection, audit trails - directly in pull requests using Terrateam. This GitOps-native solution for Terraform and OpenTofu scales across monorepos and teams, without relying on fragile pipelines. [Sign up for Terrateam](https://app.terrateam.io/#/login) and make your Terraform updates safer and easier to test and review.

Features

Learn More

Learn

Connect

Posts tagged "testing"

Automated Testing for Terraform with Terratest in CI/CD