feat: added Kind and NotKind to compare with reflect.Kind

This adapts stretchr#1803.

We have adopted slightly different design choices:
* we think checking for nil and reflect.Invalid is a legit use case
* we prefer to use [reflect.Value.Kind] over [reflect.Type.Kind] so as
  to reflect the concrete type of the object.

This way  we don't have to handle the case when [reflect.TypeOf] is nil,
which again may well be a legitimate assertion.

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

Author: fredbi

internal/assertions/type.go

@@ -146,6 +146,67 @@ func NotZero(t T, i any, msgAndArgs ...any) bool {
 	return true
 }
 
+// Kind asserts that the [reflect.Kind] of a given object matches the expected [reflect.Kind].
+//
+// Kind reflects the concrete value stored in the object. The nil value (or interface with nil value)
+// are comparable to [reflect.Invalid]. See also [reflect.Value.Kind].
+//
+// # Usage
+//
+//	assertions.Kind(t, reflect.String, "Hello World")
+//
+// # Examples
+//
+//	success: reflect.String, "hello"
+//	failure: reflect.String, 0
+func Kind(t T, expectedKind reflect.Kind, object any, msgAndArgs ...any) bool {
+	// Domain: type
+	if h, ok := t.(H); ok {
+		h.Helper()
+	}
+
+	val := reflect.ValueOf(object)
+	kind := val.Kind()
+	if kind != expectedKind {
+		if kind == reflect.Invalid {
+			// add some explanation when reflect.Invalid does not match the expectation (common gotcha with reflect)
+			return Fail(t, "object has reflect.Invalid kind: this is nil or an interface with nil value", msgAndArgs...)
+		}
+
+		return Fail(t, fmt.Sprintf("object expected to be of kind %v, but was %v", expectedKind, kind), msgAndArgs...)
+	}
+
+	return true
+}
+
+// NotKind asserts that the [reflect.Kind] of a given object does not match the expected [reflect.Kind].
+//
+// Kind reflects the concrete value stored in the object. The nil value (or interface with nil value)
+// are comparable to [reflect.Invalid]. See also [reflect.Value.Kind].
+//
+// # Usage
+//
+//	assertions.NotKind(t, reflect.Int, "Hello World")
+//
+// # Examples
+//
+//	success: reflect.String, 0
+//	failure: reflect.String, "hello"
+func NotKind(t T, expectedKind reflect.Kind, object any, msgAndArgs ...any) bool {
+	// Domain: type
+	if h, ok := t.(H); ok {
+		h.Helper()
+	}
+
+	val := reflect.ValueOf(object)
+	kind := val.Kind()
+	if kind != expectedKind {
+		return true
+	}
+
+	return Fail(t, fmt.Sprintf("object expected not to be of kind %v, but was %v", expectedKind, kind), msgAndArgs...)
+}
+
 func isType(expectedType, object any) bool {
 	return ObjectsAreEqual(reflect.TypeOf(object), reflect.TypeOf(expectedType))
 }

internal/assertions/type_test.go

@@ -4,7 +4,9 @@
 package assertions
 
 import (
+	"errors"
 	"iter"
+	"reflect"
 	"slices"
 	"testing"
 )
@@ -101,6 +103,39 @@ func TestTypeNotZero(t *testing.T) {
 	}
 }
 
+func TestTypeKind(t *testing.T) {
+	t.Parallel()
+
+	for tt := range kindCases() {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			mock := new(mockT)
+			result := Kind(mock, tt.expectedKind, tt.value)
+			resultNot := NotKind(mock, tt.expectedKind, tt.value)
+
+			if tt.result {
+				if !result {
+					t.Errorf("expected kind of %T to be %q, but Kind reported %t", tt.value, tt.expectedKind, result)
+				}
+				if resultNot {
+					t.Errorf("expected kind of %T to be %q, but NotKind reported %t", tt.value, tt.expectedKind, resultNot)
+				}
+
+				return
+			}
+
+			// expected: false
+			if result {
+				t.Errorf("expected kind of %T NOT to be %q, but Kind reported %t", tt.value, tt.expectedKind, result)
+			}
+			if !resultNot {
+				t.Errorf("expected kind of %T NOT to be %q, but NotKind reported %t", tt.value, tt.expectedKind, resultNot)
+			}
+		})
+	}
+}
+
 func TestTypeDiffEmptyCases(t *testing.T) {
 	t.Parallel()
 
@@ -216,3 +251,42 @@ func typeNonZeros() iter.Seq[any] {
 		(chan<- any)(make(chan any)),
 	})
 }
+
+type kindCase struct {
+	expectedKind reflect.Kind
+	value        any
+	result       bool
+	name         string
+}
+
+func kindCases() iter.Seq[kindCase] {
+	var iface any = "string"
+
+	return slices.Values([]kindCase{
+		// True cases
+		{reflect.String, "Hello World", true, "is string"},
+		{reflect.Int, 123, true, "is int"},
+		{reflect.Array, [6]int{2, 3, 5, 7, 11, 13}, true, "is array"},
+		{reflect.Func, Kind, true, "is func"},
+		{reflect.Float64, 0.0345, true, "is float64"},
+		{reflect.Map, make(map[string]int), true, "is map"},
+		{reflect.Bool, true, true, "is bool"},
+		{reflect.Ptr, new(int), true, "is pointer"},
+		// False cases
+		{reflect.String, 13, false, "not string"},
+		{reflect.Int, [6]int{2, 3, 5, 7, 11, 13}, false, "not int"},
+		{reflect.Float64, 12, false, "not float64"},
+		{reflect.Bool, make(map[string]int), false, "not bool"},
+		// Edge cases
+		// True
+		{reflect.Invalid, any(nil), true, "legitimate expectation of reflect.Invalid (any)"},
+		{reflect.Ptr, (*any)(nil), true, "legitimate expectation of reflect.Pointer (*any)"},
+		{reflect.Invalid, (error)(nil), true, "legitimate expectation of reflect.Invalid (error)"},
+		{reflect.Invalid, nil, true, "legitimate nil input"},
+		// False
+		{reflect.Interface, iface, false, "interface returns concrete type (any)"},
+		{reflect.Interface, errors.New("stuff"), false, "interface returns concrete type (error)"},
+		{reflect.Invalid, "string", false, "wrong expectation of reflect.Invalid"},
+		{reflect.Ptr, nil, false, "nil input"},
+	})
+}