provider-test-patterns

Name: provider-test-patterns
Author: hashicorp

750stars110forks

How to install provider-test-patterns?

hashicorp/agent-skills/provider-test-patterns

$npx -y skills add hashicorp/agent-skills --skill provider-test-patterns

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Provider Acceptance Test Patterns
2
3	Patterns for writing acceptance tests using
4	[terraform-plugin-testing](https://github.com/hashicorp/terraform-plugin-testing)
5	with the [Plugin Framework](https://github.com/hashicorp/terraform-plugin-framework).
6
7	Source: [HashiCorp Testing Patterns](https://developer.hashicorp.com/terraform/plugin/testing/testing-patterns)
8
9	References (load when needed):
10	- `references/checks.md` — statecheck, plancheck, knownvalue types, tfjsonpath, comparers
11	- `references/sweepers.md` — sweeper setup, TestMain, dependencies
12	- `references/ephemeral.md` — ephemeral resource testing, echoprovider, multi-step patterns
13
14	---
15
16	## Test Lifecycle
17
18	The framework runs each TestStep through: **plan → apply → refresh → final
19	plan**. If the final plan shows a diff, the test fails (unless
20	`ExpectNonEmptyPlan` is set). After all steps, destroy runs followed by
21	`CheckDestroy`. This means every test automatically verifies that
22	configurations apply cleanly and produce no drift — no assertions needed for
23	that.
24
25	---
26
27	## Test Function Structure
28
29	```go
30	func TestAccExample_basic(t *testing.T) {
31	var widget example.Widget
32	rName := acctest.RandStringFromCharSet(10, acctest.CharSetAlphaNum)
33	resourceName := "example_widget.test"
34
35	resource.ParallelTest(t, resource.TestCase{
36	PreCheck: func() { testAccPreCheck(t) },
37	ProtoV6ProviderFactories: testAccProtoV6ProviderFactories,
38	CheckDestroy: testAccCheckExampleDestroy,
39	Steps: []resource.TestStep{
40	{
41	Config: testAccExampleConfig_basic(rName),
42	ConfigStateChecks: []statecheck.StateCheck{
43	stateCheckExampleExists(resourceName, &widget),
44	statecheck.ExpectKnownValue(resourceName,
45	tfjsonpath.New("name"), knownvalue.StringExact(rName)),
46	statecheck.ExpectKnownValue(resourceName,
47	tfjsonpath.New("id"), knownvalue.NotNull()),
48	},
49	},
50	},
51	})
52	}
53	```
54
55	Use `resource.ParallelTest` by default. Use `resource.Test` only when tests
56	share state or cannot run concurrently.
57
58	---
59
60	## Provider Factory
61
62	```go
63	// provider_test.go — Plugin Framework with Protocol 6 (use Protocol5 variant if needed)
64	var testAccProtoV6ProviderFactories = map[string]func() (tfprotov6.ProviderServer, error){
65	"example": providerserver.NewProtocol6WithError(New("test")()),
66	}
67	```
68
69	---
70
71	## TestCase Fields
72
73	\| Field \| Purpose \|
74	\|-------\|---------\|
75	\| `PreCheck` \| `func()` — verify prerequisites (env vars, API access) \|
76	\| `ProtoV6ProviderFactories` \| Plugin Framework provider factories \|
77	\| `CheckDestroy` \| `TestCheckFunc` — verify resources destroyed after all steps \|
78	\| `Steps` \| `[]TestStep` — sequential test operations \|
79	\| `TerraformVersionChecks` \| `[]tfversion.TerraformVersionCheck` — gate by CLI version \|
80
81	---
82
83	## TestStep Fields
84
85	### Config Mode
86
87	\| Field \| Purpose \|
88	\|-------\|---------\|
89	\| `Config` \| Inline HCL string to apply \|
90	\| `ConfigStateChecks` \| `[]statecheck.StateCheck` — modern assertions (preferred) \|
91	\| `ConfigPlanChecks` \| `resource.ConfigPlanChecks{PreApply: []plancheck.PlanCheck{...}}` \|
92	\| `ExpectError` \| `*regexp.Regexp` — expect failure matching pattern \|
93	\| `ExpectNonEmptyPlan` \| `bool` — expect non-empty plan after apply \|
94	\| `PlanOnly` \| `bool` — plan without applying \|
95	\| `Destroy` \| `bool` — run destroy step \|
96	\| `PreConfig` \| `func()` — setup before step \|
97
98	### Import Mode
99
100	\| Field \| Purpose \|
101	\|-------\|---------\|
102	\| `ImportState` \| `true` to enable import mode \|
103	\| `ImportStateVerify` \| Verify imported state matches prior state \|
104	\| `ImportStateVerifyIgnore` \| `[]string` — attributes to skip during verify \|
105	\| `ImportStateKind` \| `resource.ImportBlockWithID` — import block generation \|
106	\| `ResourceName` \| Resource address to import \|
107	\| `ImportStateId` \| Override the ID used for import \|
108
109	---
110
111	## Check Functions
112
113	### Modern: ConfigStateChecks (preferred)
114
115	Type-safe with aggregated error reporting. Compose built-in checks with custom
116	`statecheck.StateCheck` implementations. See `references/checks.md` for full
117	kno

People who liked this also viewed

6 picks

Type

provider-test-patterns

750stars110forks

View on GitHub

How to install provider-test-patterns?

hashicorp/agent-skills/provider-test-patterns

$npx -y skills add hashicorp/agent-skills --skill provider-test-patterns

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Provider Acceptance Test Patterns
2
3	Patterns for writing acceptance tests using
4	[terraform-plugin-testing](https://github.com/hashicorp/terraform-plugin-testing)
5	with the [Plugin Framework](https://github.com/hashicorp/terraform-plugin-framework).
6
7	Source: [HashiCorp Testing Patterns](https://developer.hashicorp.com/terraform/plugin/testing/testing-patterns)
8
9	References (load when needed):
10	- `references/checks.md` — statecheck, plancheck, knownvalue types, tfjsonpath, comparers
11	- `references/sweepers.md` — sweeper setup, TestMain, dependencies
12	- `references/ephemeral.md` — ephemeral resource testing, echoprovider, multi-step patterns
13
14	---
15
16	## Test Lifecycle
17
18	The framework runs each TestStep through: **plan → apply → refresh → final
19	plan**. If the final plan shows a diff, the test fails (unless
20	`ExpectNonEmptyPlan` is set). After all steps, destroy runs followed by
21	`CheckDestroy`. This means every test automatically verifies that
22	configurations apply cleanly and produce no drift — no assertions needed for
23	that.
24
25	---
26
27	## Test Function Structure
28
29	```go
30	func TestAccExample_basic(t *testing.T) {
31	var widget example.Widget
32	rName := acctest.RandStringFromCharSet(10, acctest.CharSetAlphaNum)
33	resourceName := "example_widget.test"
34
35	resource.ParallelTest(t, resource.TestCase{
36	PreCheck: func() { testAccPreCheck(t) },
37	ProtoV6ProviderFactories: testAccProtoV6ProviderFactories,
38	CheckDestroy: testAccCheckExampleDestroy,
39	Steps: []resource.TestStep{
40	{
41	Config: testAccExampleConfig_basic(rName),
42	ConfigStateChecks: []statecheck.StateCheck{
43	stateCheckExampleExists(resourceName, &widget),
44	statecheck.ExpectKnownValue(resourceName,
45	tfjsonpath.New("name"), knownvalue.StringExact(rName)),
46	statecheck.ExpectKnownValue(resourceName,
47	tfjsonpath.New("id"), knownvalue.NotNull()),
48	},
49	},
50	},
51	})
52	}
53	```
54
55	Use `resource.ParallelTest` by default. Use `resource.Test` only when tests
56	share state or cannot run concurrently.
57
58	---
59
60	## Provider Factory
61
62	```go
63	// provider_test.go — Plugin Framework with Protocol 6 (use Protocol5 variant if needed)
64	var testAccProtoV6ProviderFactories = map[string]func() (tfprotov6.ProviderServer, error){
65	"example": providerserver.NewProtocol6WithError(New("test")()),
66	}
67	```
68
69	---
70
71	## TestCase Fields
72
73	\| Field \| Purpose \|
74	\|-------\|---------\|
75	\| `PreCheck` \| `func()` — verify prerequisites (env vars, API access) \|
76	\| `ProtoV6ProviderFactories` \| Plugin Framework provider factories \|
77	\| `CheckDestroy` \| `TestCheckFunc` — verify resources destroyed after all steps \|
78	\| `Steps` \| `[]TestStep` — sequential test operations \|
79	\| `TerraformVersionChecks` \| `[]tfversion.TerraformVersionCheck` — gate by CLI version \|
80
81	---
82
83	## TestStep Fields
84
85	### Config Mode
86
87	\| Field \| Purpose \|
88	\|-------\|---------\|
89	\| `Config` \| Inline HCL string to apply \|
90	\| `ConfigStateChecks` \| `[]statecheck.StateCheck` — modern assertions (preferred) \|
91	\| `ConfigPlanChecks` \| `resource.ConfigPlanChecks{PreApply: []plancheck.PlanCheck{...}}` \|
92	\| `ExpectError` \| `*regexp.Regexp` — expect failure matching pattern \|
93	\| `ExpectNonEmptyPlan` \| `bool` — expect non-empty plan after apply \|
94	\| `PlanOnly` \| `bool` — plan without applying \|
95	\| `Destroy` \| `bool` — run destroy step \|
96	\| `PreConfig` \| `func()` — setup before step \|
97
98	### Import Mode
99
100	\| Field \| Purpose \|
101	\|-------\|---------\|
102	\| `ImportState` \| `true` to enable import mode \|
103	\| `ImportStateVerify` \| Verify imported state matches prior state \|
104	\| `ImportStateVerifyIgnore` \| `[]string` — attributes to skip during verify \|
105	\| `ImportStateKind` \| `resource.ImportBlockWithID` — import block generation \|
106	\| `ResourceName` \| Resource address to import \|
107	\| `ImportStateId` \| Override the ID used for import \|
108
109	---
110
111	## Check Functions
112
113	### Modern: ConfigStateChecks (preferred)
114
115	Type-safe with aggregated error reporting. Compose built-in checks with custom
116	`statecheck.StateCheck` implementations. See `references/checks.md` for full
117	kno

People who liked this also viewed

6 picks

Type