Provider Test Patterns
Structure HashiCorp Terraform provider acceptance tests with terraform-plugin-testing instead of guessing TestStep, statecheck, and import patterns.
Overview
Provider-test-patterns is an agent skill for the Ship phase that teaches Terraform Plugin Framework provider acceptance tests using terraform-plugin-testing, statecheck, plancheck, imports, sweepers, and ephemeral patter
Install
npx skills add https://github.com/hashicorp/agent-skills --skill provider-test-patternsWhat is this skill?
- TestCase and TestStep structure for terraform-plugin-testing with the Terraform Plugin Framework
- ConfigStateChecks with custom statecheck.StateCheck implementations plus plancheck and CompareValue cross-step assertion
- Five documented scenario patterns: basic, update, disappears, validation, and regression
- Import testing with ImportStateKind, TestMain sweeper setup, and ephemeral resource flows via echoprovider
- On-demand reference splits for checks, sweepers, and ephemeral multi-step patterns aligned with HashiCorp testing docs
- Five scenario patterns documented: basic, update, disappears, validation, and regression
- Three focused reference guides: checks, sweepers, and ephemeral testing
- Covers terraform-plugin-testing with the Terraform Plugin Framework per HashiCorp testing-patterns guidance
Adoption & trust: 1k installs on skills.sh; 654 GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
You are shipping a Terraform provider but acceptance tests are brittle or misaligned because plugin-testing state checks, plan checks, import state, and sweepers are unfamiliar.
Who is it for?
Maintainers writing or reviewing Terraform provider acceptance tests with Go, the Plugin Framework, and real cloud-backed test configs.
Skip if: Builders who only test Terraform modules, application services without a provider SDK, or teams that want quick unit-test snippets with no acceptance harness.
When should I use this skill?
Writing, reviewing, or debugging provider acceptance tests, including statecheck, plancheck, TestCheckFunc, CheckDestroy, ExpectError, import state verification, ephemeral resources, or test file structure.
What do I get? / Deliverables
You get review-ready acceptance test files with consistent TestCase/TestStep structure, correct state and plan assertions, import and sweeper coverage, and scenario templates that follow HashiCorp testing patterns.
- Structured acceptance test files with TestCase and TestStep definitions
- State and plan check implementations using statecheck and plancheck
- Import, sweeper, and ephemeral test scenarios aligned with HashiCorp patterns
Recommended Skills
Journey fit
Acceptance tests gate whether a Terraform provider is safe to ship, so the canonical shelf is the Ship phase rather than Build or Operate. The skill is entirely about QA mechanics—TestCase layout, plan/state checks, import verification, and sweepers—which maps directly to the testing subphase.
How it compares
Use for HashiCorp provider acceptance-test recipes—not generic pytest/Jest guides or Terraform plan-only module tests.
Common Questions / FAQ
Who is provider-test-patterns for?
It is for solo builders and small teams authoring or reviewing Terraform providers who need terraform-plugin-testing patterns with the Plugin Framework, including import, sweeper, and ephemeral cases.
When should I use provider-test-patterns?
Use it during Ship when writing new acceptance tests, debugging failing TestSteps, verifying ImportStateKind behavior, setting up sweepers in TestMain, or structuring ephemeral resource tests with echoprovider.
Is provider-test-patterns safe to install?
Treat it as procedural documentation for your agent; review the Security Audits panel on this Prism page and inspect the skill package in your repo before granting shell, network, or cloud credentials to automated test runs.
SKILL.md
READMESKILL.md - Provider Test Patterns
# Provider Acceptance Test Patterns Patterns for writing acceptance tests using [terraform-plugin-testing](https://github.com/hashicorp/terraform-plugin-testing) with the [Plugin Framework](https://github.com/hashicorp/terraform-plugin-framework). Source: [HashiCorp Testing Patterns](https://developer.hashicorp.com/terraform/plugin/testing/testing-patterns) **References** (load when needed): - `references/checks.md` — statecheck, plancheck, knownvalue types, tfjsonpath, comparers - `references/sweepers.md` — sweeper setup, TestMain, dependencies - `references/ephemeral.md` — ephemeral resource testing, echoprovider, multi-step patterns --- ## Test Lifecycle The framework runs each TestStep through: **plan → apply → refresh → final plan**. If the final plan shows a diff, the test fails (unless `ExpectNonEmptyPlan` is set). After all steps, destroy runs followed by `CheckDestroy`. This means every test automatically verifies that configurations apply cleanly and produce no drift — no assertions needed for that. --- ## Test Function Structure ```go 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()), }, }, }, }) } ``` Use `resource.ParallelTest` by default. Use `resource.Test` only when tests share state or cannot run concurrently. --- ## Provider Factory ```go // provider_test.go — Plugin Framework with Protocol 6 (use Protocol5 variant if needed) var testAccProtoV6ProviderFactories = map[string]func() (tfprotov6.ProviderServer, error){ "example": providerserver.NewProtocol6WithError(New("test")()), } ``` --- ## TestCase Fields | Field | Purpose | |-------|---------| | `PreCheck` | `func()` — verify prerequisites (env vars, API access) | | `ProtoV6ProviderFactories` | Plugin Framework provider factories | | `CheckDestroy` | `TestCheckFunc` — verify resources destroyed after all steps | | `Steps` | `[]TestStep` — sequential test operations | | `TerraformVersionChecks` | `[]tfversion.TerraformVersionCheck` — gate by CLI version | --- ## TestStep Fields ### Config Mode | Field | Purpose | |-------|---------| | `Config` | Inline HCL string to apply | | `ConfigStateChecks` | `[]statecheck.StateCheck` — modern assertions (preferred) | | `ConfigPlanChecks` | `resourc