Add support for Plan Checks with plancheck.ExpectResourceAction, plancheck.ExpectEmptyPlan, and plancheck.ExpectNonEmptyPlan

.changes/unreleased/ENHANCEMENTS-20230321-174020.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'helper/resource: Added plan check functionality to config and refresh modes
+  with new fields `TestStep.ConfigPlanChecks` and `TestStep.RefreshPlanChecks`'
+time: 2023-03-21T17:40:20.521786-04:00
+custom:
+  Issue: "63"

.changes/unreleased/FEATURES-20230321-173506.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'plancheck: Introduced new `plancheck` package with interface and built-in plan
+  check functionality'
+time: 2023-03-21T17:35:06.650327-04:00
+custom:
+  Issue: "63"

.changes/unreleased/FEATURES-20230321-173639.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'plancheck: Added `ExpectResourceAction` built-in plan check, which asserts
+  that a given resource will have a specific resource change type in the plan'
+time: 2023-03-21T17:36:39.391477-04:00
+custom:
+  Issue: "63"

.changes/unreleased/FEATURES-20230321-173726.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'plancheck: Added `ExpectEmptyPlan` built-in plan check, which asserts that
+  there are no resource changes in the plan'
+time: 2023-03-21T17:37:26.076041-04:00
+custom:
+  Issue: "63"

.changes/unreleased/FEATURES-20230321-173805.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'plancheck: Added `ExpectNonEmptyPlan` built-in plan check, which asserts that
+  there is at least one resource change in the plan'
+time: 2023-03-21T17:38:05.815307-04:00
+custom:
+  Issue: "63"

helper/resource/plan_checks.go

@@ -0,0 +1,29 @@
+package resource
+
+import (
+	"context"
+
+	tfjson "github.com/hashicorp/terraform-json"
+	"github.com/hashicorp/terraform-plugin-testing/internal/errorshim"
+	"github.com/hashicorp/terraform-plugin-testing/plancheck"
+	"github.com/mitchellh/go-testing-interface"
+)
+
+func runPlanChecks(ctx context.Context, t testing.T, plan *tfjson.Plan, planChecks []plancheck.PlanCheck) error {
+	t.Helper()
+
+	var result error
+
+	for _, planCheck := range planChecks {
+		resp := plancheck.CheckPlanResponse{}
+		planCheck.CheckPlan(ctx, plancheck.CheckPlanRequest{Plan: plan}, &resp)
+
+		if resp.Error != nil {
+			// TODO: Once Go 1.20 is the minimum supported version for this module, replace with `errors.Join` function
+			// - https://github.com/hashicorp/terraform-plugin-testing/issues/99
+			result = errorshim.Join(result, resp.Error)
+		}
+	}
+
+	return result
+}

helper/resource/plan_checks_test.go

@@ -0,0 +1,19 @@
+package resource
+
+import (
+	"context"
+
+	"github.com/hashicorp/terraform-plugin-testing/plancheck"
+)
+
+var _ plancheck.PlanCheck = &planCheckSpy{}
+
+type planCheckSpy struct {
+	err    error
+	called bool
+}
+
+func (s *planCheckSpy) CheckPlan(ctx context.Context, req plancheck.CheckPlanRequest, resp *plancheck.CheckPlanResponse) {
+	s.called = true
+	resp.Error = s.err
+}

helper/resource/testing.go

@@ -23,6 +23,7 @@ import (
 
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
 
+	"github.com/hashicorp/terraform-plugin-testing/plancheck"
 	"github.com/hashicorp/terraform-plugin-testing/terraform"
 
 	"github.com/hashicorp/terraform-plugin-testing/internal/addrs"
@@ -510,6 +511,20 @@ type TestStep struct {
 	// test to pass.
 	ExpectError *regexp.Regexp
 
+	// ConfigPlanChecks allows assertions to be made against the plan file at different points of a Config (apply) test using a plan check.
+	// Custom plan checks can be created by implementing the [PlanCheck] interface, or by using a PlanCheck implementation from the provided [plancheck] package
+	//
+	// [PlanCheck]: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-testing/plancheck#PlanCheck
+	// [plancheck]: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-testing/plancheck
+	ConfigPlanChecks ConfigPlanChecks
+
+	// RefreshPlanChecks allows assertions to be made against the plan file at different points of a Refresh test using a plan check.
+	// Custom plan checks can be created by implementing the [PlanCheck] interface, or by using a PlanCheck implementation from the provided [plancheck] package
+	//
+	// [PlanCheck]: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-testing/plancheck#PlanCheck
+	// [plancheck]: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-testing/plancheck
+	RefreshPlanChecks RefreshPlanChecks
+
 	// PlanOnly can be set to only run `plan` with this configuration, and not
 	// actually apply it. This is useful for ensuring config changes result in
 	// no-op plans
@@ -679,6 +694,28 @@ type TestStep struct {
 	ExternalProviders map[string]ExternalProvider
 }
 
+// ConfigPlanChecks defines the different points in a Config TestStep when plan checks can be run.
+type ConfigPlanChecks struct {
+	// PreApply runs all plan checks in the slice. This occurs before the apply of a Config test is run. This slice cannot be populated
+	// with TestStep.PlanOnly, as there is no PreApply plan run with that flag set. All errors by plan checks in this slice are aggregated, reported, and will result in a test failure.
+	PreApply []plancheck.PlanCheck
+
+	// PostApplyPreRefresh runs all plan checks in the slice. This occurs after the apply and before the refresh of a Config test is run.
+	// All errors by plan checks in this slice are aggregated, reported, and will result in a test failure.
+	PostApplyPreRefresh []plancheck.PlanCheck
+
+	// PostApplyPostRefresh runs all plan checks in the slice. This occurs after the apply and refresh of a Config test are run.
+	// All errors by plan checks in this slice are aggregated, reported, and will result in a test failure.
+	PostApplyPostRefresh []plancheck.PlanCheck
+}
+
+// RefreshPlanChecks defines the different points in a Refresh TestStep when plan checks can be run.
+type RefreshPlanChecks struct {
+	// PostRefresh runs all plan checks in the slice. This occurs after the refresh of the Refresh test is run.
+	// All errors by plan checks in this slice are aggregated, reported, and will result in a test failure.
+	PostRefresh []plancheck.PlanCheck
+}
+
 // ParallelTest performs an acceptance test on a resource, allowing concurrency
 // with other ParallelTest. The number of concurrent tests is controlled by the
 // "go test" command -parallel flag.

helper/resource/testing_new_config.go

@@ -51,6 +51,24 @@ func testStepNewConfig(ctx context.Context, t testing.T, c TestCase, wd *plugint
 			return fmt.Errorf("Error running pre-apply plan: %w", err)
 		}
 
+		// Run pre-apply plan checks
+		if len(step.ConfigPlanChecks.PreApply) > 0 {
+			var plan *tfjson.Plan
+			err = runProviderCommand(ctx, t, func() error {
+				var err error
+				plan, err = wd.SavedPlan(ctx)
+				return err
+			}, wd, providers)
+			if err != nil {
+				return fmt.Errorf("Error retrieving pre-apply plan: %w", err)
+			}
+
+			err = runPlanChecks(ctx, t, plan, step.ConfigPlanChecks.PreApply)
+			if err != nil {
+				return fmt.Errorf("Pre-apply plan check(s) failed:\n%w", err)
+			}
+		}
+
 		// We need to keep a copy of the state prior to destroying such
 		// that the destroy steps can verify their behavior in the
 		// check function
@@ -131,6 +149,14 @@ func testStepNewConfig(ctx context.Context, t testing.T, c TestCase, wd *plugint
 		return fmt.Errorf("Error retrieving post-apply plan: %w", err)
 	}
 
+	// Run post-apply, pre-refresh plan checks
+	if len(step.ConfigPlanChecks.PostApplyPreRefresh) > 0 {
+		err = runPlanChecks(ctx, t, plan, step.ConfigPlanChecks.PostApplyPreRefresh)
+		if err != nil {
+			return fmt.Errorf("Post-apply, pre-refresh plan check(s) failed:\n%w", err)
+		}
+	}
+
 	if !planIsEmpty(plan) && !step.ExpectNonEmptyPlan {
 		var stdout string
 		err = runProviderCommand(ctx, t, func() error {
@@ -174,6 +200,14 @@ func testStepNewConfig(ctx context.Context, t testing.T, c TestCase, wd *plugint
 		return fmt.Errorf("Error retrieving second post-apply plan: %w", err)
 	}
 
+	// Run post-apply, post-refresh plan checks
+	if len(step.ConfigPlanChecks.PostApplyPostRefresh) > 0 {
+		err = runPlanChecks(ctx, t, plan, step.ConfigPlanChecks.PostApplyPostRefresh)
+		if err != nil {
+			return fmt.Errorf("Post-apply, post-refresh plan check(s) failed:\n%w", err)
+		}
+	}
+
 	// check if plan is empty
 	if !planIsEmpty(plan) && !step.ExpectNonEmptyPlan {
 		var stdout string