Terraform provider acceptance test patterns using terraform-plugin-testing with the Plugin Framework. Covers test structure, TestCase/TestStep fields, ConfigStateChecks with custom statecheck.StateCheck implementations, plan checks, CompareValue for cross-step assertions, config helpers, import testing with ImportStateKind, sweepers, and scenario patterns (basic, update, disappears, validation, regression), and ephemeral resource testing with the echoprovider package. Use when writing, reviewing
Detected risks:
Documents acceptance-test patterns for Terraform providers built on the Plugin Framework and exercised with terraform-plugin-testing. It is the reference to reach for when writing, reviewing, or debugging provider acceptance tests, or when questions come up about statecheck, plancheck, TestCheckFunc, CheckDestroy, ExpectError, import verification, or ephemeral resources. The core idea is that every TestStep runs through plan, apply, refresh, and a final plan, and a diff on that final plan fails the test unless ExpectNonEmptyPlan is set, so each step automatically proves that a configuration applies cleanly and produces no drift. After all steps run, destroy executes and CheckDestroy confirms teardown.
The material lays out TestCase fields (PreCheck, ProtoV6ProviderFactories, CheckDestroy, Steps, TerraformVersionChecks) and TestStep fields split between config mode (Config, ConfigStateChecks, ConfigPlanChecks, ExpectError, ExpectNonEmptyPlan, PlanOnly, Destroy, PreConfig) and import mode (ImportState, ImportStateVerify, ImportStateVerifyIgnore, ImportStateKind, ResourceName, ImportStateId). It favors ConfigStateChecks with statecheck.StateCheck implementations for type-safe, aggregated assertions using tfjsonpath and knownvalue, and shows the legacy Check path with ComposeAggregateTestCheckFunc for CheckDestroy and migration, warning against mixing the two in one step.
Beyond structure, it covers config helpers that use numbered format verbs, and a set of scenario patterns: basic and update combined into one test, import verification with ImportStateKind, disappears tests for externally deleted resources, validation, and regression. resource.ParallelTest is the default, with resource.Test reserved for tests that share state. Supplementary references address checks, sweepers, and ephemeral-resource testing with the echoprovider package.
It covers terraform-plugin-testing paired with the Plugin Framework, using Protocol 6 provider factories (with a Protocol 5 variant available when needed).
ConfigStateChecks with statecheck.StateCheck implementations, which are type-safe and report aggregated errors. You should not mix the legacy Check field with ConfigStateChecks in the same step.
Each step runs plan, apply, refresh, and a final plan. A diff on the final plan fails the test unless ExpectNonEmptyPlan is set, so clean apply and no drift are checked without extra assertions.
Use resource.ParallelTest by default. Reserve resource.Test for tests that share state or cannot run concurrently.
Add an import-mode step with ImportState set to true, ImportStateVerify to confirm imported state matches prior state, and ImportStateKind such as resource.ImportBlockWithID for import block generation.
Quick Setup:
.claude/skills/Repository
hashicorp/agent-skills