Terraform テスト

Terraform の組み込みテストフレームワークは、設定の更新が破壊的な変更をもたらさないことを検証します。テストは一時的なリソースに対して実行されるため、既存のインフラストラクチャと状態ファイルを保護します。

リファレンスファイル

• references/MOCK_PROVIDERS.md — モックプロバイダーの構文、一般的なデフォルト、モックの使用時期 (Terraform 1.7.0+ のみ — ユーザーのバージョンが 1.7 以下の場合はスキップ)
• references/CI_CD.md — GitHub Actions と GitLab CI パイプラインの例
• references/EXAMPLES.md — 完全なテストスイートの例 (VPC モジュールのユニット、統合、モックテスト)

ユーザーがモッキング、CI/CD 統合について質問する場合、または完全な例を希望する場合は関連するリファレンスファイルを読んでください。

コア概念

• テストファイル (.tftest.hcl / .tftest.json): 設定を検証する run ブロックを含みます
• Run ブロック: オプションの変数、プロバイダー、アサーションを含む単一のテストシナリオ
• Assert ブロック: テストが成功するために真である必要がある条件
• モックプロバイダー: 実際のインフラストラクチャなしにプロバイダーの動作をシミュレート (Terraform 1.7.0+)
• テストモード: apply (デフォルト、実リソースを作成) または plan (ロジックのみを検証)

ファイル構造

my-module/
├── main.tf
├── variables.tf
├── outputs.tf
└── tests/
    ├── defaults_unit_test.tftest.hcl         # plan モード — 高速、リソースなし
    ├── validation_unit_test.tftest.hcl        # plan モード
    └── full_stack_integration_test.tftest.hcl # apply モード — 実リソースを作成

plan モードテストは *_unit_test.tftest.hcl、apply モードテストは *_integration_test.tftest.hcl を使用することで、CI で別々にフィルタリングできます。

テストファイル構造

# オプション: テスト全体の設定
test {
  parallel = true  # すべての run ブロックの並列実行を有効化 (デフォルト: false)
}

# オプション: ファイルレベルの変数 (最高優先度、他のすべてのソースをオーバーライド)
variables {
  aws_region    = "us-west-2"
  instance_type = "t2.micro"
}

# オプション: プロバイダー設定
provider "aws" {
  region = var.aws_region
}

# 必須: 最低 1 つの run ブロック
run "test_default_configuration" {
  command = plan

  assert {
    condition     = aws_instance.example.instance_type == "t2.micro"
    error_message = "Instance type should be t2.micro by default"
  }
}

Run ブロック

run "test_name" {
  command  = plan  # または apply (デフォルト)
  parallel = true  # オプション、v1.9.0 以降

  # ファイルレベルの変数をオーバーライド
  variables {
    instance_type = "t3.large"
  }

  # 特定のモジュールを参照
  module {
    source  = "./modules/vpc"  # ローカルまたはレジストリのみ (git/http ではない)
    version = "5.0.0"          # レジストリモジュールのみ
  }

  # 状態の分離を制御
  state_key = "shared_state"  # v1.9.0 以降

  # Plan の動作
  plan_options {
    mode    = refresh-only  # または normal (デフォルト)
    refresh = true
    replace = [aws_instance.example]
    target  = [aws_instance.example]
  }

  # アサーション
  assert {
    condition     = aws_instance.example.id != ""
    error_message = "Instance should have a valid ID"
  }

  # 予期される失敗 (これらが失敗すればテストは成功)
  expect_failures = [
    var.instance_count
  ]
}

一般的なテストパターン

出力の検証

run "test_outputs" {
  command = plan

  assert {
    condition     = output.vpc_id != null
    error_message = "VPC ID output must be defined"
  }

  assert {
    condition     = can(regex("^vpc-", output.vpc_id))
    error_message = "VPC ID should start with 'vpc-'"
  }
}

条件付きリソース

run "test_nat_gateway_disabled" {
  command = plan

  variables {
    create_nat_gateway = false
  }

  assert {
    condition     = length(aws_nat_gateway.main) == 0
    error_message = "NAT gateway should not be created when disabled"
  }
}

リソース数

run "test_resource_count" {
  command = plan

  variables {
    instance_count = 3
  }

  assert {
    condition     = length(aws_instance.workers) == 3
    error_message = "Should create exactly 3 worker instances"
  }
}

タグ

run "test_resource_tags" {
  command = plan

  variables {
    common_tags = {
      Environment = "production"
      ManagedBy   = "Terraform"
    }
  }

  assert {
    condition     = aws_instance.example.tags["Environment"] == "production"
    error_message = "Environment tag should be set correctly"
  }

  assert {
    condition     = aws_instance.example.tags["ManagedBy"] == "Terraform"
    error_message = "ManagedBy tag should be set correctly"
  }
}

データソース

run "test_data_source_lookup" {
  command = plan

  assert {
    condition     = data.aws_ami.ubuntu.id != ""
    error_message = "Should find a valid Ubuntu AMI"
  }

  assert {
    condition     = can(regex("^ami-", data.aws_ami.ubuntu.id))
    error_message = "AMI ID should be in correct format"
  }
}

検証ルール

run "test_invalid_environment" {
  command = plan

  variables {
    environment = "invalid"
  }

  expect_failures = [
    var.environment
  ]
}

依存関係のある連続テスト

run "setup_vpc" {
  command = apply

  assert {
    condition     = output.vpc_id != ""
    error_message = "VPC should be created"
  }
}

run "test_subnet_in_vpc" {
  command = plan

  variables {
    vpc_id = run.setup_vpc.vpc_id
  }

  assert {
    condition     = aws_subnet.example.vpc_id == run.setup_vpc.vpc_id
    error_message = "Subnet should be in the VPC from setup_vpc"
  }
}

Plan オプション (refresh-only、ターゲット指定)

run "test_refresh_only" {
  command = plan

  plan_options {
    mode = refresh-only
  }

  assert {
    condition     = aws_instance.example.tags["Environment"] == "production"
    error_message = "Tags should be refreshed correctly"
  }
}

run "test_specific_resource" {
  command = plan

  plan_options {
    target = [aws_instance.example]
  }

  assert {
    condition     = aws_instance.example.instance_type == "t2.micro"
    error_message = "Targeted resource should be planned"
  }
}

並列モジュール

run "test_networking_module" {
  command  = plan
  parallel = true

  module {
    source = "./modules/networking"
  }

  assert {
    condition     = output.vpc_id != ""
    error_message = "VPC should be created"
  }
}

run "test_compute_module" {
  command  = plan
  parallel = true

  module {
    source = "./modules/compute"
  }

  assert {
    condition     = output.instance_id != ""
    error_message = "Instance should be created"
  }
}

状態キーの共有

run "create_foundation" {
  command   = apply
  state_key = "foundation"

  assert {
    condition     = aws_vpc.main.id != ""
    error_message = "Foundation VPC should be created"
  }
}

run "create_application" {
  command   = apply
  state_key = "foundation"

  variables {
    vpc_id = run.create_foundation.vpc_id
  }

  assert {
    condition     = aws_instance.app.vpc_id == run.create_foundation.vpc_id
    error_message = "Application should use foundation VPC"
  }
}

クリーンアップの順序 (バケット前にS3 オブジェクト)

run "create_bucket" {
  command = apply

  assert {
    condition     = aws_s3_bucket.example.id != ""
    error_message = "Bucket should be created"
  }
}

run "add_objects" {
  command = apply

  assert {
    condition     = length(aws_s3_object.files) > 0
    error_message = "Objects should be added"
  }
}

# クリーンアップは逆順で破棄: 最初にオブジェクト、次にバケット

複数のエイリアス付きプロバイダー

provider "aws" {
  alias  = "primary"
  region = "us-west-2"
}

provider "aws" {
  alias  = "secondary"
  region = "us-east-1"
}

run "test_with_specific_provider" {
  command = plan

  providers = {
    aws = provider.aws.secondary
  }

  assert {
    condition     = aws_instance.example.availability_zone == "us-east-1a"
    error_message = "Instance should be in us-east-1 region"
  }
}

複雑な条件

assert {
  condition = alltrue([
    for subnet in aws_subnet.private :
    can(regex("^10\\.0\\.", subnet.cidr_block))
  ])
  error_message = "All private subnets should use 10.0.0.0/8 CIDR range"
}

クリーンアップ

リソースはテスト完了後に run ブロックの逆順 で破棄されます。これは依存関係 (例: バケット前のS3 オブジェクト) に関して重要です。デバッグのため terraform test -no-cleanup を使用してクリーンアップをスキップできます。

テストの実行

terraform test                                        # すべてのテスト
terraform test tests/defaults.tftest.hcl             # 特定のファイル
terraform test -filter=test_vpc_configuration        # run ブロック名で指定
terraform test -test-directory=integration-tests     # カスタムディレクトリ
terraform test -verbose                              # 詳細出力
terraform test -no-cleanup                           # リソースクリーンアップをスキップ

ベストプラクティス

1. 命名: plan モードは *_unit_test.tftest.hcl、apply モードは *_integration_test.tftest.hcl
2. テスト命名: テストしているシナリオを説明する説明的な run ブロック名を使用
3. デフォルトは plan: 実リソースの動作をテストする必要がない限り command = plan を使用
4. モックを使用: 外部依存関係の場合 — より高速で認証情報不要 (references/MOCK_PROVIDERS.md を参照)
5. エラーメッセージ: テストを再度実行せずに障害を診断できるほど具体的に
6. ネガティブテスト: expect_failures を使用して検証ルールが不正な入力を拒否することを確認
7. 変数カバレッジ: すべてのコードパスを検証するために異なる変数の組み合わせをテスト — テスト変数は最高優先度で他のすべてのソースをオーバーライド
8. モジュールソース: テストファイルはローカルパスとレジストリモジュールのみをサポート — git や HTTP URL ではない
9. 並列実行: 異なる状態ファイルを持つ独立したテストに parallel = true を使用
10. クリーンアップ: 統合テストはリソースを run ブロックの逆順で自動的に破棄; デバッグの場合は -no-cleanup を使用
11. CI/CD: すべての PR でユニットテストを実行、マージ時に統合テストを実行 (references/CI_CD.md を参照)

トラブルシューティング

問題	解決策
アサーション失敗	-verbose を使用して実際値と期待値を確認
認証情報が不足	ユニットテストではモックプロバイダーを使用
サポートされていないモジュールソース	git/HTTP ソースをローカルモジュールに変換
テスト間の干渉	分離のため state_key または別々のモジュールを使用
テストが遅い	command = plan とモックを使用; 統合テストは別々に実行

参照

• Terraform テストドキュメント
• Terraform test コマンド
• テストベストプラクティス