プロバイダー受け入れテストパターン

terraform-plugin-testing と Plugin Framework を使用した受け入れテストの作成パターンです。

ソース: HashiCorp Testing Patterns

参考資料（必要に応じてロード）:

• references/checks.md — statecheck、plancheck、knownvalue 型、tfjsonpath、comparer
• references/sweepers.md — スウィーパー設定、TestMain、依存関係
• references/ephemeral.md — エフェメラルリソーステスト、echoprovider、マルチステップパターン

---

テストライフサイクル

フレームワークは各 TestStep を plan → apply → refresh → final plan の流れで実行します。最終プランが差分を示す場合、テストは失敗します (ExpectNonEmptyPlan が設定されている場合を除く)。 すべてのステップの後、破棄が実行され、その後 CheckDestroy が続きます。 つまり、すべてのテストは設定がクリーンに適用され、 ドリフトが発生しないことを自動的に検証します — その検証に対するアサーションは不要です。

---

テスト関数の構造

func TestAccExample_basic(t *testing.T) {
    var widget example.Widget
    rName := acctest.RandStringFromCharSet(10, acctest.CharSetAlphaNum)
    resourceName := "example_widget.test"

    resource.ParallelTest(t, resource.TestCase{
        PreCheck:                 func() { testAccPreCheck(t) },
        ProtoV6ProviderFactories: testAccProtoV6ProviderFactories,
        CheckDestroy:             testAccCheckExampleDestroy,
        Steps: []resource.TestStep{
            {
                Config: testAccExampleConfig_basic(rName),
                ConfigStateChecks: []statecheck.StateCheck{
                    stateCheckExampleExists(resourceName, &widget),
                    statecheck.ExpectKnownValue(resourceName,
                        tfjsonpath.New("name"), knownvalue.StringExact(rName)),
                    statecheck.ExpectKnownValue(resourceName,
                        tfjsonpath.New("id"), knownvalue.NotNull()),
                },
            },
        },
    })
}

デフォルトでは resource.ParallelTest を使用してください。 テストが状態を共有するか、並行実行できない場合のみ resource.Test を使用してください。

---

プロバイダーファクトリー

// provider_test.go — Plugin Framework with Protocol 6 (必要に応じて Protocol5 バリアントを使用)
var testAccProtoV6ProviderFactories = map[string]func() (tfprotov6.ProviderServer, error){
    "example": providerserver.NewProtocol6WithError(New("test")()),
}

---

TestCase フィールド

フィールド	目的
PreCheck	func() — 前提条件の確認（環境変数、API アクセス）
ProtoV6ProviderFactories	Plugin Framework プロバイダーファクトリー
CheckDestroy	TestCheckFunc — すべてのステップ後のリソース破棄を検証
Steps	[]TestStep — 順序付きテスト操作
TerraformVersionChecks	[]tfversion.TerraformVersionCheck — CLI バージョンでゲート

---

TestStep フィールド

Config モード

フィールド	目的
Config	インライン HCL 文字列を適用
ConfigStateChecks	[]statecheck.StateCheck — モダンなアサーション（推奨）
ConfigPlanChecks	resource.ConfigPlanChecks{PreApply: []plancheck.PlanCheck{...}}
ExpectError	*regexp.Regexp — パターンに一致する失敗を期待
ExpectNonEmptyPlan	bool — 適用後に空でないプランを期待
PlanOnly	bool — 適用なしでプラン
Destroy	bool — 破棄ステップを実行
PreConfig	func() — ステップ前のセットアップ

Import モード

フィールド	目的
ImportState	true でインポートモード有効化
ImportStateVerify	インポート状態が前の状態と一致することを検証
ImportStateVerifyIgnore	[]string — 検証時にスキップする属性
ImportStateKind	resource.ImportBlockWithID — インポートブロック生成
ResourceName	インポートするリソースアドレス
ImportStateId	インポートに使用する ID をオーバーライド

---

チェック関数

モダン: ConfigStateChecks（推奨）

型安全で、エラーレポートが集約されています。 組み込みチェックとカスタム statecheck.StateCheck 実装を組み合わせます。 完全な knownvalue 型、tfjsonpath ナビゲーション、comparer については references/checks.md を参照してください。

ConfigStateChecks: []statecheck.StateCheck{
    stateCheckExampleExists(resourceName, &widget),
    statecheck.ExpectKnownValue(resourceName,
        tfjsonpath.New("name"), knownvalue.StringExact("my-widget")),
    statecheck.ExpectKnownValue(resourceName,
        tfjsonpath.New("enabled"), knownvalue.Bool(true)),
    statecheck.ExpectKnownValue(resourceName,
        tfjsonpath.New("id"), knownvalue.NotNull()),
    statecheck.ExpectSensitiveValue(resourceName,
        tfjsonpath.New("api_key")),
},

同じステップで Check（レガシー）と ConfigStateChecks を混在させないでください。

レガシー: Check（CheckDestroy および移行用）

TestCase の CheckDestroy には TestCheckFunc が必要です。 TestStep の Check フィールドも TestCheckFunc を受け入れますが、 新しいテストでは ConfigStateChecks を優先してください。

Check: resource.ComposeAggregateTestCheckFunc(
    resource.TestCheckResourceAttr(name, "key", "expected"),
    resource.TestCheckResourceAttrSet(name, "id"),
    resource.TestCheckNoResourceAttr(name, "removed"),
    resource.TestMatchResourceAttr(name, "url", regexp.MustCompile(`^https://`)),
    resource.TestCheckResourceAttrPair(res1, "ref_id", res2, "id"),
),

ComposeAggregateTestCheckFunc はすべてのエラーを報告します。 ComposeTestCheckFunc は最初のエラーで失敗します。

---

設定ヘルパー

番号付きフォーマット動詞を使用してください — 引用文字列には %[1]q、 生の文字列には %[1]s：

func testAccExampleConfig_basic(rName string) string {
    return fmt.Sprintf(`
resource "example_widget" "test" {
  name = %[1]q
}
`, rName)
}

func testAccExampleConfig_full(rName, description string) string {
    return fmt.Sprintf(`
resource "example_widget" "test" {
  name        = %[1]q
  description = %[2]q
  enabled     = true
}
`, rName, description)
}

---

シナリオパターン

基本 + 更新（1 つのテストに統合 — 更新は基本のスーパーセット）

Steps: []resource.TestStep{
    {
        Config: testAccExampleConfig_basic(rName),
        ConfigStateChecks: []statecheck.StateCheck{
            stateCheckExampleExists(resourceName, &widget),
            statecheck.ExpectKnownValue(resourceName,
                tfjsonpath.New("name"), knownvalue.StringExact(rName)),
        },
    },
    {
        Config: testAccExampleConfig_full(rName, "updated"),
        ConfigStateChecks: []statecheck.StateCheck{
            stateCheckExampleExists(resourceName, &widget),
            statecheck.ExpectKnownValue(resourceName,
                tfjsonpath.New("description"), knownvalue.StringExact("updated")),
        },
    },
},

インポート

設定ステップの後、インポートが同一の状態を生成することを検証します。 ImportStateKind を使用してインポートブロック生成を行います：

{
    ResourceName:      resourceName,
    ImportState:       true,
    ImportStateVerify: true,
    ImportStateKind:   resource.ImportBlockWithID,
},

消失（リソースが外部から削除）

{
    Config: testAccExampleConfig_basic(rName),
    ConfigStateChecks: []statecheck.StateCheck{
        stateCheckExampleExists(resourceName, &widget),
        stateCheckExampleDisappears(resourceName),
    },
    ExpectNonEmptyPlan: true,
},

検証（エラー期待）

{
    Config:      testAccExampleConfig_invalidName(""),
    ExpectError: regexp.MustCompile(`name must not be empty`),
},

リグレッション（2 コミットワークフロー）

適切なバグ修正では、最低でも 2 つのコミットを使用します： 最初のコミットでリグレッションテストを提出し（失敗してバグを確認）、 次に修正をコミットします（テストが成功）。 これにより、レビュアーは最初のコミットをチェックアウトしてテストが 問題を再現することを独立して検証してから、修正に進むことができます。

リグレッションテストに名前を付けてドキュメント化し、 修正対象の問題を特定します。可能な限り、オリジナルのバグレポートへのリンクを含めます。

// TestAccExample_regressionGH1234 は https://github.com/org/repo/issues/1234 の修正を検証します
func TestAccExample_regressionGH1234(t *testing.T) {
    rName := acctest.RandStringFromCharSet(10, acctest.CharSetAlphaNum)
    resourceName := "example_widget.test"

    resource.ParallelTest(t, resource.TestCase{
        PreCheck:                 func() { testAccPreCheck(t) },
        ProtoV6ProviderFactories: testAccProtoV6ProviderFactories,
        CheckDestroy:             testAccCheckExampleDestroy,
        Steps: []resource.TestStep{
            {
                // 問題を再現: この設定はバグをトリガーしました
                Config: testAccExampleConfig_regressionGH1234(rName),
                ConfigStateChecks: []statecheck.StateCheck{
                    stateCheckExampleExists(resourceName, nil),
                    statecheck.ExpectKnownValue(resourceName,
                        tfjsonpath.New("computed_field"), knownvalue.NotNull()),
                },
            },
        },
    })
}

---

ヘルパー関数

カスタム StateCheck: Exists

API 存在検証用に statecheck.StateCheck を実装します。 exists チェックを独立した関数に分離し、 ステップ間で再利用できるようにしてください — ソースではこれを設計原則として推奨しています：

type exampleExistsCheck struct {
    resourceAddress string
    widget          *example.Widget
}

func (e exampleExistsCheck) CheckState(ctx context.Context, req statecheck.CheckStateRequest, resp *statecheck.CheckStateResponse) {
    r, err := stateResourceAtAddress(req.State, e.resourceAddress)
    if err != nil {
        resp.Error = err
        return
    }

    id, ok := r.AttributeValues["id"].(string)
    if !ok {
        resp.Error = fmt.Errorf("no id found for %s", e.resourceAddress)
        return
    }

    conn := testAccAPIClient()
    widget, err := conn.GetWidget(id)
    if err != nil {
        resp.Error = fmt.Errorf("%s not found via API: %w", e.resourceAddress, err)
        return
    }

    if e.widget != nil {
        *e.widget = *widget
    }
}

func stateCheckExampleExists(name string, widget *example.Widget) statecheck.StateCheck {
    return exampleExistsCheck{resourceAddress: name, widget: widget}
}

カスタム StateCheck: 消失

API 経由でリソースを削除し、外部削除をシミュレートします：

type exampleDisappearsCheck struct {
    resourceAddress string
}

func (e exampleDisappearsCheck) CheckState(ctx context.Context, req statecheck.CheckStateRequest, resp *statecheck.CheckStateResponse) {
    r, err := stateResourceAtAddress(req.State, e.resourceAddress)
    if err != nil {
        resp.Error = err
        return
    }

    id := r.AttributeValues["id"].(string)
    conn := testAccAPIClient()
    resp.Error = conn.DeleteWidget(id)
}

func stateCheckExampleDisappears(name string) statecheck.StateCheck {
    return exampleDisappearsCheck{resourceAddress: name}
}

状態リソースルックアップ（共有ユーティリティ）

func stateResourceAtAddress(state *tfjson.State, address string) (*tfjson.StateResource, error) {
    if state == nil || state.Values == nil || state.Values.RootModule == nil {
        return nil, fmt.Errorf("no state available")
    }
    for _, r := range state.Values.RootModule.Resources {
        if r.Address == address {
            return r, nil
        }
    }
    return nil, fmt.Errorf("not found in state: %s", address)
}

破棄チェック（TestCheckFunc — CheckDestroy で必須）

func testAccCheckExampleDestroy(s *terraform.State) error {
    conn := testAccAPIClient()
    for _, rs := range s.RootModule().Resources {
        if rs.Type != "example_widget" {
            continue
        }
        _, err := conn.GetWidget(rs.Primary.ID)
        if err == nil {
            return fmt.Errorf("widget %s still exists", rs.Primary.ID)
        }
        if !isNotFoundError(err) {
            return err
        }
    }
    return nil
}

PreCheck

func testAccPreCheck(t *testing.T) {
    t.Helper()
    if os.Getenv("EXAMPLE_API_KEY") == "" {
        t.Fatal("EXAMPLE_API_KEY must be set for acceptance tests")
    }
}