terraform-test

terraform-test の概要

terraform-test は、.tftest.hcl のシナリオを作成し、モジュールの挙動を確認し、構文やワークフローを勘に頼らずにインフラのロジックを検証するための Terraform テストスキルです。テストファイル、run ブロック、assert、mock を実務的に整理した terraform-test のガイドを求めるエンジニアに最適で、特にマージ前に Terraform の変更をより安全にしたい場合に向いています。

terraform-test が得意なこと

出力値、リソース引数、条件分岐ロジック、環境ごとの挙動を確認したいときに terraform-test スキルを使ってください。特に、モジュール作者、プラットフォームチーム、そして手作業の plan 確認ではなく再現可能なチェックを求めるレビュー担当者に有用です。

Terraform ワークフローのどこに位置づくか

このスキルは terraform init と terraform validate の後、CI 実行の前または並行して使うのが適しています。大まかな設定意図を、plan モードまたは apply モードで実行できる明示的なテストケースへ落とし込むのに役立ちます。

主な違い

terraform-test の主な価値は、汎用的なプロンプト助言ではなく Terraform ネイティブのテストに軸足を置いている点です。テスト構造、assert の書き方、Terraform 1.7+ における mock provider の使い方、CI で回しやすい実行方法までカバーしているため、ユーザーは「たぶん動くはず」から具体的なテストファイルへ素早く移れます。

terraform-test スキルの使い方

インストールして、読むべきファイルを開く

npx skills add hashicorp/agent-skills --skill terraform-test でインストールします。次に、まず SKILL.md を読み、その後で完全なテストスイートのパターンを確認するために references/EXAMPLES.md、モックを使ったユニットテストなら references/MOCK_PROVIDERS.md、パイプライン実行が必要なら references/CI_CD.md を確認してください。

テスト可能な目的をはっきり伝える

良いプロンプトは、モジュール名、検証したい挙動、期待する結果を明示します。たとえば「VPC モジュール向けに、plan モードで public subnet の数、private subnet のルーティング、出力値を検証する .tftest.hcl を書いてください」という形です。「テストを追加して」だけよりもこちらのほうが適切です。なぜなら、スキルが run ブロックと assert にすぐ対応づけられるからです。

適切な入力の形を渡す

Terraform のバージョン、provider 制約、モジュール入力、そして何を証明したいのかを伝えると、このスキルは最もよく機能します。mock provider を使いたいならその旨を明記し、Terraform 1.7+ であることも確認してください。実際の統合テストを行いたいなら、対象クラウド、必要な認証情報、CI 上の前提条件も含めてください。

空のファイルからではなく、ワークフローから始める

実用的な terraform-test の流れは、挙動を特定し、plan か apply かを決め、mock を許可するか判断し、シナリオごとに 1 つの run ブロックを書いていくことです。まず references/EXAMPLES.md でテスト全体のレイアウトを確認し、その後で変数、assert、ファイル名を自分のリポジトリ規約に合わせて調整してください。

terraform-test スキル FAQ

terraform-test はモジュールテスト専用ですか？

いいえ。モジュールで最も威力を発揮しますが、ルート構成、出力値の検証、provider の挙動確認、CI でのテスト実行にも役立ちます。Terraform ネイティブの検証が必要なら、このスキルはよい選択です。

どんなときに terraform-test を使わないほうがいいですか？

一度きりの terraform plan の説明が欲しいだけの場合や、CI で Terraform テストを実行できない環境では避けてください。また、Terraform が 1.7 未満なら mock provider のパターンも使えないので、そのワークフローは適用できません。

terraform-test は手でプロンプトを書くより簡単ですか？

たいていはそうです。Terraform の実際のテスト構文とファイル構造に作業を絞り込めるからです。一般的なプロンプトだと広い助言にとどまりがちですが、terraform-test スキルは、特に run ブロックと assert を含む使えるテストケースを作ることを狙っています。

terraform-test は Code Generation タスクにも使えますか？

はい。terraform-test for Code Generation は、モジュールのインターフェースと期待挙動に合った生成済みテストファイルが欲しいときに有用です。ただし、生成したテストでも実際の入力、現実的な assert、そして plan と apply のどちらをカバーするかの明確な判断は必要です。

terraform-test スキルを改善する方法

具体的なモジュール情報を渡す

入力が具体的であるほど、テストもよくなります。変数名、必須出力、リソース名、provider alias、そして「public subnet は 2 つでなければならない」「instance type の既定値は t3.micro であるべき」といった不変条件を含めてください。

何をモックできるかを明示する

最も効く品質改善は、provider 呼び出しを mock にするのか、それとも実際に行うのかを明確にすることです。terraform-test の導入判断では特に重要です。mock は認証情報の必要性を減らし、ユニットテストを高速化しますが、plan モードでしか使えず、provider 固有の挙動を見逃すことがあります。

ユニット、統合、リグレッションを分ける

挙動が異なるなら、1 つの大きなファイルにまとめず、別々のテストシナリオとして依頼してください。整った terraform-test ガイドは、速い plan モードの確認と遅い統合テストを分けることが多く、CI をシンプルにし、失敗の原因も読みやすくなります。

思い込みではなく、失敗から改善する

最初の実行後は、弱すぎる assert、範囲が広すぎる条件、変動しやすい値に依存した条件を絞り込んでください。計算済み属性で失敗するなら、より安定した確認方法を依頼します。モジュール変更が意図したものなら、テストの意味が薄れるまで条件を広げるのではなく、期待条件を更新してください。