terraform testによるコード検証の始め方｜1.6以降のネイティブテスト機能でリグレッションを防ぐ

この記事のポイント

・terraform testはTerraform 1.6から正式搭載されたネイティブテスト機能
・.tftest.hclにrunブロックとassertを書くだけでモジュール検証ができる
・tflintの静的解析とterraform testの動的テストは役割が異なる二軸
・GitHub Actionsへの組み込みでリグレッションを自動防止できる

# ディレクトリ構成例
modules/
  s3_bucket/
    main.tf
    variables.tf
    outputs.tf
    tests/
      main.tftest.hcl    # テストファイル

# tests/main.tftest.hcl

# テスト用変数の設定
variables {
  bucket_name_prefix = "test-app"
  environment        = "stg"
}

run "s3_bucket_name_check" {
  command = plan   # plan のみ実行（実リソースは作成しない）

  assert {
    condition     = output.bucket_name == "test-app-stg"
    error_message = "バケット名が期待値と一致しません: ${output.bucket_name}"
  }
}

run "s3_versioning_enabled" {
  command = apply  # 実際に apply して属性を確認

  assert {
    condition     = aws_s3_bucket_versioning.this.versioning_configuration[0].status == "Enabled"
    error_message = "バージョニングが有効になっていません"
  }
}

$ cd modules/s3_bucket
$ terraform init
$ terraform test

tests/main.tftest.hcl... in progress
  run "s3_bucket_name_check"... pass
  run "s3_versioning_enabled"... pass
tests/main.tftest.hcl... timed out

Success! 2 passed, 0 failed.

tests/main.tftest.hcl... in progress
  run "s3_bucket_name_check"... fail

Failure! 0 passed, 1 failed.

---
Failure in run "s3_bucket_name_check"
in tests/main.tftest.hcl

Error: Test assertion failed

  on tests/main.tftest.hcl line 15, in run "s3_bucket_name_check":
  15:   condition = output.bucket_name == "test-app-stg"

バケット名が期待値と一致しません: my-app-stg

# variables.tf（テスト対象モジュール側）
variable "environment" {
  type        = string
  description = "デプロイ環境（prod/stg/dev のみ許可）"

  validation {
    condition     = contains(["prod", "stg", "dev"], var.environment)
    error_message = "environment は prod / stg / dev のいずれかを指定してください。"
  }
}

# tests/validation.tftest.hcl
run "invalid_environment_should_fail" {
  command = plan

  variables {
    environment = "production"   # 無効な値
  }

  expect_failures = [
    var.environment,
  ]
}

# tests/outputs.tftest.hcl
variables {
  bucket_name_prefix = "myapp"
  environment        = "dev"
}

run "check_bucket_arn_format" {
  command = plan

  assert {
    condition     = startswith(output.bucket_arn, "arn:aws:s3:::")
    error_message = "バケットARNのフォーマットが不正です: ${output.bucket_arn}"
  }

  assert {
    condition     = output.bucket_name == "myapp-dev"
    error_message = "バケット名が命名規則に従っていません: ${output.bucket_name}"
  }
}

# tests/mock.tftest.hcl
mock_provider "aws" {
  mock_resource "aws_s3_bucket" {
    defaults = {
      arn    = "arn:aws:s3:::mock-bucket"
      region = "ap-northeast-1"
    }
  }
}

run "name_check_with_mock" {
  command = plan

  assert {
    condition     = output.bucket_name == "myapp-dev"
    error_message = "バケット名が期待値と異なります: ${output.bucket_name}"
  }
}

# .github/workflows/terraform-test.yml
name: Terraform Test

on:
  pull_request:
    paths:
      - 'modules/**'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "1.9.0"

      - name: Terraform Init
        run: terraform init
        working-directory: modules/s3_bucket

      - name: Terraform Test
        run: terraform test
        working-directory: modules/s3_bucket
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_DEFAULT_REGION: ap-northeast-1

      - name: Terraform Test (mock)
        run: terraform test -filter=tests/mock.tftest.hcl
        working-directory: modules/s3_bucket
        # AWS クレデンシャル不要（mock_provider 使用時）

$ terraform test
No test files

Error: Reference to undeclared output value

  on tests/main.tftest.hcl line 15, in run "check_name":
  15:   condition = output.bucket_id == "..."

An output value with the name "bucket_id" has not been declared.

# テスト用stateファイルの確認
$ ls tests/*.tfstate

# テスト用リソースを手動でdestroy
$ terraform destroy -state=tests/terraform.tfstate