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,
+ }
+}