Adding plan checks for ExpectKnownValue, ExpectKnownOutputValue, and ExpectKnownOutputValueAtPath

.changes/unreleased/FEATURES-20231218-114539.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'plancheck: Added `ExpectKnownValue` plan check, which asserts that a given
+  resource attribute has a defined type, and value'
+time: 2023-12-18T11:45:39.181954Z
+custom:
+  Issue: "248"

.changes/unreleased/FEATURES-20231218-114553.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'plancheck: Added `ExpectKnownOutputValue` plan check, which asserts that a
+  given output value has a defined type, and value'
+time: 2023-12-18T11:45:53.272412Z
+custom:
+  Issue: "248"

.changes/unreleased/FEATURES-20231218-114611.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'plancheck: Added `ExpectKnownOutputValueAtPath` plan check, which asserts that
+  a given output value at a specified path has a defined type, and value'
+time: 2023-12-18T11:46:11.58053Z
+custom:
+  Issue: "248"

.changes/unreleased/FEATURES-20231218-114739.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'knownvalue: Introduced new `knownvalue` package which contains types for working
+  with plan checks and state checks'
+time: 2023-12-18T11:47:39.059813Z
+custom:
+  Issue: "248"

knownvalue/bool.go

@@ -0,0 +1,43 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package knownvalue
+
+import "strconv"
+
+var _ KnownValue = BoolValue{}
+
+// BoolValue is a KnownValue for asserting equality between the value
+// supplied to NewBoolValue and the value passed to the Equal method.
+type BoolValue struct {
+	value bool
+}
+
+// Equal determines whether the passed value is of type bool, and
+// contains a matching bool value.
+func (v BoolValue) Equal(other any) bool {
+	otherVal, ok := other.(bool)
+
+	if !ok {
+		return false
+	}
+
+	if otherVal != v.value {
+		return false
+	}
+
+	return true
+}
+
+// String returns the string representation of the bool value.
+func (v BoolValue) String() string {
+	return strconv.FormatBool(v.value)
+}
+
+// NewBoolValue returns a KnownValue for asserting equality between the
+// supplied bool and the value passed to the Equal method.
+func NewBoolValue(value bool) BoolValue {
+	return BoolValue{
+		value: value,
+	}
+}

knownvalue/bool_test.go

@@ -0,0 +1,57 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package knownvalue_test
+
+import (
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+
+	"github.com/hashicorp/terraform-plugin-testing/knownvalue"
+)
+
+func TestBoolValue_Equal(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		other    any
+		expected bool
+	}{
+		"nil": {},
+		"wrong-type": {
+			other: 1.23,
+		},
+		"not-equal": {
+			other: false,
+		},
+		"equal": {
+			other:    true,
+			expected: true,
+		},
+	}
+
+	for name, testCase := range testCases {
+		name, testCase := name, testCase
+
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			got := knownvalue.NewBoolValue(true).Equal(testCase.other)
+
+			if diff := cmp.Diff(got, testCase.expected); diff != "" {
+				t.Errorf("unexpected difference: %s", diff)
+			}
+		})
+	}
+}
+
+func TestBoolValue_String(t *testing.T) {
+	t.Parallel()
+
+	got := knownvalue.NewBoolValue(true).String()
+
+	if diff := cmp.Diff(got, "true"); diff != "" {
+		t.Errorf("unexpected difference: %s", diff)
+	}
+}

knownvalue/doc.go

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

knownvalue/float64.go

@@ -0,0 +1,45 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package knownvalue
+
+import (
+	"strconv"
+)
+
+var _ KnownValue = Float64Value{}
+
+// Float64Value is a KnownValue for asserting equality between the value
+// supplied to NewFloat64Value and the value passed to the Equal method.
+type Float64Value struct {
+	value float64
+}
+
+// Equal determines whether the passed value is of type float64, and
+// contains a matching float64 value.
+func (v Float64Value) Equal(other any) bool {
+	otherVal, ok := other.(float64)
+
+	if !ok {
+		return false
+	}
+
+	if otherVal != v.value {
+		return false
+	}
+
+	return true
+}
+
+// String returns the string representation of the float64 value.
+func (v Float64Value) String() string {
+	return strconv.FormatFloat(v.value, 'f', -1, 64)
+}
+
+// NewFloat64Value returns a KnownValue for asserting equality between the
+// supplied float64 and the value passed to the Equal method.
+func NewFloat64Value(value float64) Float64Value {
+	return Float64Value{
+		value: value,
+	}
+}

knownvalue/float64_test.go

@@ -0,0 +1,57 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package knownvalue_test
+
+import (
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+
+	"github.com/hashicorp/terraform-plugin-testing/knownvalue"
+)
+
+func TestFloat64Value_Equal(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		other    any
+		expected bool
+	}{
+		"nil": {},
+		"wrong-type": {
+			other: 123,
+		},
+		"not-equal": {
+			other: false,
+		},
+		"equal": {
+			other:    1.23,
+			expected: true,
+		},
+	}
+
+	for name, testCase := range testCases {
+		name, testCase := name, testCase
+
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			got := knownvalue.NewFloat64Value(1.23).Equal(testCase.other)
+
+			if diff := cmp.Diff(got, testCase.expected); diff != "" {
+				t.Errorf("unexpected difference: %s", diff)
+			}
+		})
+	}
+}
+
+func TestFloat64Value_String(t *testing.T) {
+	t.Parallel()
+
+	got := knownvalue.NewFloat64Value(1.234567890123e+09).String()
+
+	if diff := cmp.Diff(got, "1234567890.123"); diff != "" {
+		t.Errorf("unexpected difference: %s", diff)
+	}
+}

knownvalue/int64.go

@@ -0,0 +1,45 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package knownvalue
+
+import (
+	"strconv"
+)
+
+var _ KnownValue = Int64Value{}
+
+// Int64Value is a KnownValue for asserting equality between the value
+// supplied to NewInt64Value and the value passed to the Equal method.
+type Int64Value struct {
+	value int64
+}
+
+// Equal determines whether the passed value is of type int64, and
+// contains a matching int64 value.
+func (v Int64Value) Equal(other any) bool {
+	otherVal, ok := other.(int64)
+
+	if !ok {
+		return false
+	}
+
+	if otherVal != v.value {
+		return false
+	}
+
+	return true
+}
+
+// String returns the string representation of the int64 value.
+func (v Int64Value) String() string {
+	return strconv.FormatInt(v.value, 10)
+}
+
+// NewInt64Value returns a KnownValue for asserting equality between the
+// supplied int64 and the value passed to the Equal method.
+func NewInt64Value(value int64) Int64Value {
+	return Int64Value{
+		value: value,
+	}
+}

knownvalue/int64_test.go

@@ -0,0 +1,57 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package knownvalue_test
+
+import (
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+
+	"github.com/hashicorp/terraform-plugin-testing/knownvalue"
+)
+
+func TestInt64Value_Equal(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		other    any
+		expected bool
+	}{
+		"nil": {},
+		"wrong-type": {
+			other: 1.23,
+		},
+		"not-equal": {
+			other: false,
+		},
+		"equal": {
+			other:    int64(123),
+			expected: true,
+		},
+	}
+
+	for name, testCase := range testCases {
+		name, testCase := name, testCase
+
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			got := knownvalue.NewInt64Value(123).Equal(testCase.other)
+
+			if diff := cmp.Diff(got, testCase.expected); diff != "" {
+				t.Errorf("unexpected difference: %s", diff)
+			}
+		})
+	}
+}
+
+func TestInt64Value_String(t *testing.T) {
+	t.Parallel()
+
+	got := knownvalue.NewInt64Value(1234567890123).String()
+
+	if diff := cmp.Diff(got, "1234567890123"); diff != "" {
+		t.Errorf("unexpected difference: %s", diff)
+	}
+}

knownvalue/known_value.go

@@ -0,0 +1,10 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package knownvalue
+
+// KnownValue defines an interface that is implemented to determine equality on the basis of type and value.
+type KnownValue interface {
+	// Equal should perform equality testing.
+	Equal(other any) bool
+}