Implement comparison state checks to replace TestCheckResourceAttrPtr, TestCheckResourceAttrPair and TestCheckTypeSetElemAttrPair

.changes/unreleased/FEATURES-20240717-155731.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'compare: Introduced new `compare` package, which contains interfaces and implementations
+  for value comparisons in state checks.'
+time: 2024-07-17T15:57:31.637692-04:00
+custom:
+  Issue: "330"

.changes/unreleased/FEATURES-20240717-160116.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'statecheck: Added `CompareValue` state check, which compares sequential values of the
+  specified attribute at the given managed resource, or data source, using the supplied value comparer.'
+time: 2024-07-17T16:01:16.194665-04:00
+custom:
+  Issue: "330"

.changes/unreleased/FEATURES-20240717-160331.yaml

@@ -0,0 +1,7 @@
+kind: FEATURES
+body: 'statecheck: Added `CompareValueCollection` state check, which compares each item in
+  the specified collection (e.g., list, set) attribute, with the second specified
+  attribute at the given managed resources, or data sources, using the supplied value comparer.'
+time: 2024-07-17T16:03:31.77827-04:00
+custom:
+  Issue: "330"

.changes/unreleased/FEATURES-20240717-164418.yaml

@@ -0,0 +1,7 @@
+kind: FEATURES
+body: 'statecheck: Added `CompareValuePairs` state check, which compares the
+  specified attributes at the given managed resources, or data sources, using
+  the supplied value comparer.'
+time: 2024-07-17T16:44:18.612874-04:00
+custom:
+  Issue: "330"

.changes/unreleased/NOTES-20240717-155810.yaml

@@ -0,0 +1,6 @@
+kind: NOTES
+body: 'compare: The `compare` package is considered experimental and may be altered
+  or removed in a subsequent release'
+time: 2024-07-17T15:58:10.435384-04:00
+custom:
+  Issue: "330"

.changes/unreleased/NOTES-20240717-164911.yaml

@@ -0,0 +1,7 @@
+kind: NOTES
+body: 'statecheck: `CompareValue`, `CompareValueCollection`, and `CompareValuePairs`
+  state checks are considered experimental and may be altered or removed in a subsequent
+  release.'
+time: 2024-07-17T16:49:11.296585-04:00
+custom:
+  Issue: "330"

compare/doc.go

@@ -0,0 +1,5 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+// Package compare contains the value comparer interface, and types implementing the value comparer interface.
+package compare

compare/value_comparer.go

@@ -0,0 +1,13 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package compare
+
+// ValueComparer defines an interface that is implemented to run comparison logic on multiple values. Individual
+// implementations determine how the comparison is performed (e.g., values differ, values equal).
+type ValueComparer interface {
+	// CompareValues should assert the given known values against any expectations.
+	// Values are always ordered in the order they were added. Use the error
+	// return to signal unexpected values or implementation errors.
+	CompareValues(values ...any) error
+}

compare/values_differ.go

@@ -0,0 +1,31 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package compare
+
+import (
+	"fmt"
+	"reflect"
+)
+
+var _ ValueComparer = valuesDiffer{}
+
+type valuesDiffer struct{}
+
+// CompareValues determines whether each value in the sequence of the supplied values
+// differs from the preceding value.
+func (v valuesDiffer) CompareValues(values ...any) error {
+	for i := 1; i < len(values); i++ {
+		if reflect.DeepEqual(values[i-1], values[i]) {
+			return fmt.Errorf("expected values to differ, but they are the same: %v == %v", values[i-1], values[i])
+		}
+	}
+
+	return nil
+}
+
+// ValuesDiffer returns a ValueComparer for asserting that each value in the sequence of
+// the values supplied to the CompareValues method differs from the preceding value.
+func ValuesDiffer() valuesDiffer {
+	return valuesDiffer{}
+}

compare/values_differ_test.go

@@ -0,0 +1,62 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package compare_test
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+
+	"github.com/hashicorp/terraform-plugin-testing/compare"
+)
+
+func TestValuesDiffer_CompareValues(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		in            []any
+		expectedError error
+	}{
+		"nil": {},
+		"single-value": {
+			in: []any{"str"},
+		},
+		"non-matching-sequential-values": {
+			in: []any{"str", "other_str", "str"},
+		},
+		"matching-values-string": {
+			in:            []any{"str", "other_str", "other_str"},
+			expectedError: fmt.Errorf("expected values to differ, but they are the same: other_str == other_str"),
+		},
+		"matching-values-slice": {
+			in: []any{
+				[]any{"other_str"},
+				[]any{"other_str"},
+			},
+			expectedError: fmt.Errorf("expected values to differ, but they are the same: [other_str] == [other_str]"),
+		},
+		"matching-values-map": {
+			in: []any{
+				map[string]any{"a": "other_str"},
+				map[string]any{"a": "other_str"},
+			},
+			expectedError: fmt.Errorf("expected values to differ, but they are the same: map[a:other_str] == map[a:other_str]"),
+		},
+	}
+
+	for name, testCase := range testCases {
+		name, testCase := name, testCase
+
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			err := compare.ValuesDiffer().CompareValues(testCase.in...)
+
+			if diff := cmp.Diff(err, testCase.expectedError, equateErrorMessage); diff != "" {
+				t.Errorf("unexpected difference: %s", diff)
+			}
+		})
+	}
+}

compare/values_same.go

@@ -0,0 +1,31 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package compare
+
+import (
+	"fmt"
+	"reflect"
+)
+
+var _ ValueComparer = valuesSame{}
+
+type valuesSame struct{}
+
+// CompareValues determines whether each value in the sequence of the supplied values
+// is the same as the preceding value.
+func (v valuesSame) CompareValues(values ...any) error {
+	for i := 1; i < len(values); i++ {
+		if !reflect.DeepEqual(values[i-1], values[i]) {
+			return fmt.Errorf("expected values to be the same, but they differ: %v != %v", values[i-1], values[i])
+		}
+	}
+
+	return nil
+}
+
+// ValuesSame returns a ValueComparer for asserting that each value in the sequence of
+// the values supplied to the CompareValues method is the same as the preceding value.
+func ValuesSame() valuesSame {
+	return valuesSame{}
+}

compare/values_same_test.go

@@ -0,0 +1,73 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package compare_test
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+
+	"github.com/hashicorp/terraform-plugin-testing/compare"
+)
+
+func TestValuesSame_CompareValues(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		in            []any
+		expectedError error
+	}{
+		"nil": {},
+		"single-value": {
+			in: []any{"str"},
+		},
+		"matching-values": {
+			in: []any{"str", "str", "str"},
+		},
+		"non-matching-values-string": {
+			in:            []any{"str", "str", "other_str"},
+			expectedError: fmt.Errorf("expected values to be the same, but they differ: str != other_str"),
+		},
+		"non-matching-values-slice": {
+			in: []any{
+				[]any{"str"},
+				[]any{"str"},
+				[]any{"other_str"},
+			},
+			expectedError: fmt.Errorf("expected values to be the same, but they differ: [str] != [other_str]"),
+		},
+		"non-matching-values-map": {
+			in: []any{
+				map[string]any{"a": "str"},
+				map[string]any{"a": "str"},
+				map[string]any{"a": "other_str"},
+			},
+			expectedError: fmt.Errorf("expected values to be the same, but they differ: map[a:str] != map[a:other_str]"),
+		},
+	}
+
+	for name, testCase := range testCases {
+		name, testCase := name, testCase
+
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			err := compare.ValuesSame().CompareValues(testCase.in...)
+
+			if diff := cmp.Diff(err, testCase.expectedError, equateErrorMessage); diff != "" {
+				t.Errorf("unexpected difference: %s", diff)
+			}
+		})
+	}
+}
+
+// equateErrorMessage reports errors to be equal if both are nil
+// or both have the same message.
+var equateErrorMessage = cmp.Comparer(func(x, y error) bool {
+	if x == nil || y == nil {
+		return x == nil && y == nil
+	}
+	return x.Error() == y.Error()
+})

statecheck/compare_value.go

@@ -0,0 +1,114 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package statecheck
+
+import (
+	"context"
+	"fmt"
+
+	tfjson "github.com/hashicorp/terraform-json"
+
+	"github.com/hashicorp/terraform-plugin-testing/compare"
+	"github.com/hashicorp/terraform-plugin-testing/tfjsonpath"
+)
+
+// Resource State Check
+var _ StateCheck = &compareValue{}
+
+type compareValue struct {
+	resourceAddresses []string
+	attributePaths    []tfjsonpath.Path
+	stateValues       []any
+	comparer          compare.ValueComparer
+}
+
+func (e *compareValue) AddStateValue(resourceAddress string, attributePath tfjsonpath.Path) StateCheck {
+	e.resourceAddresses = append(e.resourceAddresses, resourceAddress)
+	e.attributePaths = append(e.attributePaths, attributePath)
+
+	return e
+}
+
+// CheckState implements the state check logic.
+func (e *compareValue) CheckState(ctx context.Context, req CheckStateRequest, resp *CheckStateResponse) {
+	var resource *tfjson.StateResource
+
+	if req.State == nil {
+		resp.Error = fmt.Errorf("state is nil")
+
+		return
+	}
+
+	if req.State.Values == nil {
+		resp.Error = fmt.Errorf("state does not contain any state values")
+
+		return
+	}
+
+	if req.State.Values.RootModule == nil {
+		resp.Error = fmt.Errorf("state does not contain a root module")
+
+		return
+	}
+
+	// All calls to AddStateValue occur before any TestStep is run, populating the resourceAddresses
+	// and attributePaths slices. The stateValues slice is populated during execution of each TestStep.
+	// Each call to CheckState happens sequentially during each TestStep.
+	// The currentIndex is reflective of the current state value being checked.
+	currentIndex := len(e.stateValues)
+
+	if len(e.resourceAddresses) <= currentIndex {
+		resp.Error = fmt.Errorf("resource addresses index out of bounds: %d", currentIndex)
+
+		return
+	}
+
+	resourceAddress := e.resourceAddresses[currentIndex]
+
+	for _, r := range req.State.Values.RootModule.Resources {
+		if resourceAddress == r.Address {
+			resource = r
+
+			break
+		}
+	}
+
+	if resource == nil {
+		resp.Error = fmt.Errorf("%s - Resource not found in state", resourceAddress)
+
+		return
+	}
+
+	if len(e.attributePaths) <= currentIndex {
+		resp.Error = fmt.Errorf("attribute paths index out of bounds: %d", currentIndex)
+
+		return
+	}
+
+	attributePath := e.attributePaths[currentIndex]
+
+	result, err := tfjsonpath.Traverse(resource.AttributeValues, attributePath)
+
+	if err != nil {
+		resp.Error = err
+
+		return
+	}
+
+	e.stateValues = append(e.stateValues, result)
+
+	err = e.comparer.CompareValues(e.stateValues...)
+
+	if err != nil {
+		resp.Error = err
+	}
+}
+
+// CompareValue returns a state check that compares values retrieved from state using the
+// supplied value comparer.
+func CompareValue(comparer compare.ValueComparer) *compareValue {
+	return &compareValue{
+		comparer: comparer,
+	}
+}