gstruct handles extra unexported fields

Author: Maxime

docs/index.md

@@ -2786,7 +2786,14 @@ Due to the global nature of these methods, keep in mind that signaling processes
 
 ### Testing type `struct`
 
-`gstruct` provides the `FieldsMatcher` through the `MatchAllFields` and `MatchFields` functions for applying a separate matcher to each field of a struct:
+`gstruct` provides the `FieldsMatcher` through the `MatchAllFields` and `MatchFields` functions for applying a separate matcher to each field of a struct.
+
+To match a subset or superset of a struct, you should use the `MatchFields` function with the `IgnoreExtras`, `IgnoreUnexportedExtras` and `IgnoreMissing` options.
+The options can be combined with the binary or, for instance : `IgnoreMissing|IgnoreExtras`.
+
+#### Match all fields
+
+`MatchAllFields` requires that every field is matched, and each matcher is mapped to a field. This is useful for test maintainability, as it ensures that all fields are tested, and will fail in the future if you add or remove a field and forget to update the test, e.g.
 
 ```go
 actual := struct{
@@ -2801,7 +2808,9 @@ Expect(actual).To(MatchAllFields(Fields{
 }))
 ```
 
-`MatchAllFields` requires that every field is matched, and each matcher is mapped to a field. To match a subset or superset of a struct, you should use the `MatchFields` function with the `IgnoreExtras` and `IgnoreMissing` options. `IgnoreExtras` will ignore fields that don't map to a matcher, e.g.
+#### Ignore extra fields
+
+`IgnoreExtras` will ignore fields that don't map to a matcher, e.g.
 
 ```go
 Expect(actual).To(MatchFields(IgnoreExtras, Fields{
@@ -2811,6 +2820,28 @@ Expect(actual).To(MatchFields(IgnoreExtras, Fields{
 }))
 ```
 
+Using IgnoreExtras will ignore any new field that you will add to the struct in the future, you might want to consider using `gstruct.Ignore()` instead if you want to ignore only specific fields.
+
+#### Ignore unexported extra fields
+
+`IgnoreUnexportedExtras` will ignore fields that don't map to a matcher, but only if they are unexported e.g.
+
+```go
+Expect(actual).To(MatchFields(IgnoreUnexportedExtras, Fields{
+    "A": BeNumerically("<", 10),
+    "B": BeTrue(),
+    // Ignore lack of "c" in the matcher.
+	// But does not ignore "C" in the matcher, because it is exported.
+}))
+```
+
+This is useful because gstruct uses the `reflect` package to access the fields of a struct, and it will not be able to access unexported fields. 
+This is a compromise between using MatchAllFields and MatchFields with IgnoreExtras, as it allows you to ignore unexported fields without having to specify them in the matcher.
+If you prefer to list the unexported fields you want to ignore, you can use `gstruct.Ignore()` instead, the matcher will make sure to not use reflect on those fields.
+
+
+#### Ignore missing fields
+
 `IgnoreMissing` will ignore matchers that don't map to a field, e.g.
 
 ```go
@@ -2822,8 +2853,6 @@ Expect(actual).To(MatchFields(IgnoreMissing, Fields{
 }))
 ```
 
-The options can be combined with the binary or: `IgnoreMissing|IgnoreExtras`.
-
 ### Testing type slice
 
 `gstruct` provides the `ElementsMatcher` through the `MatchAllElements` and `MatchElements` function for applying a separate matcher to each element, identified by an `Identifier` function:

gstruct/fields.go

@@ -8,6 +8,7 @@ import (
 	"reflect"
 	"runtime/debug"
 	"strings"
+	"unicode"
 
 	"github.com/onsi/gomega/format"
 	errorsutil "github.com/onsi/gomega/gstruct/errors"
@@ -65,6 +66,7 @@ func MatchFields(options Options, fields Fields) types.GomegaMatcher {
 	return &FieldsMatcher{
 		Fields:        fields,
 		IgnoreExtras:  options&IgnoreExtras != 0,
+		IgnoreUnexportedExtras: options&IgnoreUnexportedExtras != 0,
 		IgnoreMissing: options&IgnoreMissing != 0,
 	}
 }
@@ -75,6 +77,8 @@ type FieldsMatcher struct {
 
 	// Whether to ignore extra elements or consider it an error.
 	IgnoreExtras bool
+	// Whether to ignore unexported extra elements or consider it an error.
+	IgnoreUnexportedExtras bool
 	// Whether to ignore missing elements or consider it an error.
 	IgnoreMissing bool
 
@@ -97,6 +101,14 @@ func (m *FieldsMatcher) Match(actual any) (success bool, err error) {
 	return true, nil
 }
 
+func isExported(fieldName string) bool {
+	if fieldName == "" {
+		return false
+	}
+	r := []rune(fieldName)[0]
+	return unicode.IsUpper(r)
+}
+
 func (m *FieldsMatcher) matchFields(actual any) (errs []error) {
 	val := reflect.ValueOf(actual)
 	typ := val.Type()
@@ -116,13 +128,21 @@ func (m *FieldsMatcher) matchFields(actual any) (errs []error) {
 
 			matcher, expected := m.Fields[fieldName]
 			if !expected {
+				if m.IgnoreUnexportedExtras && !isExported(fieldName) {
+					return nil
+				}
 				if !m.IgnoreExtras {
 					return fmt.Errorf("unexpected field %s: %+v", fieldName, actual)
 				}
 				return nil
 			}
 
-			field := val.Field(i).Interface()
+			var field any
+			if _, isIgnoreMatcher := matcher.(*IgnoreMatcher) ; isIgnoreMatcher {
+				field = struct {}{} // the matcher does not care about the actual value
+			} else {
+				field = val.Field(i).Interface()
+			}
 
 			match, err := matcher.Match(field)
 			if err != nil {

gstruct/fields_test.go

@@ -9,7 +9,8 @@ import (
 var _ = Describe("Struct", func() {
 	allFields := struct{ A, B string }{"a", "b"}
 	missingFields := struct{ A string }{"a"}
-	extraFields := struct{ A, B, C string }{"a", "b", "c"}
+	extraFields := struct{ A, B, C, D string }{"a", "b", "c", "d"}
+	extraUnexportedFields := struct{ A, B, c, d string }{"a", "b", "c", "d"}
 	emptyFields := struct{ A, B string }{}
 
 	It("should strictly match all fields", func() {
@@ -20,6 +21,7 @@ var _ = Describe("Struct", func() {
 		Expect(allFields).Should(m, "should match all fields")
 		Expect(missingFields).ShouldNot(m, "should fail with missing fields")
 		Expect(extraFields).ShouldNot(m, "should fail with extra fields")
+		Expect(extraUnexportedFields).ShouldNot(m, "should fail with extra unexported fields")
 		Expect(emptyFields).ShouldNot(m, "should fail with empty fields")
 
 		m = MatchAllFields(Fields{
@@ -43,6 +45,7 @@ var _ = Describe("Struct", func() {
 		Expect(allFields).Should(m, "should match all fields")
 		Expect(missingFields).Should(m, "should ignore missing fields")
 		Expect(extraFields).ShouldNot(m, "should fail with extra fields")
+		Expect(extraUnexportedFields).ShouldNot(m, "should fail extra unexported fields")
 		Expect(emptyFields).ShouldNot(m, "should fail with empty fields")
 	})
 
@@ -54,9 +57,76 @@ var _ = Describe("Struct", func() {
 		Expect(allFields).Should(m, "should match all fields")
 		Expect(missingFields).ShouldNot(m, "should fail with missing fields")
 		Expect(extraFields).Should(m, "should ignore extra fields")
+		Expect(extraUnexportedFields).Should(m, "should ignore unexported extra fields")
 		Expect(emptyFields).ShouldNot(m, "should fail with empty fields")
 	})
 
+	It("should ignore unexported extra fields", func() {
+		m := MatchFields(IgnoreUnexportedExtras, Fields{
+			"B": Equal("b"),
+			"A": Equal("a"),
+		})
+		Expect(allFields).Should(m, "should match all fields")
+		Expect(missingFields).ShouldNot(m, "should fail with missing fields")
+		Expect(extraFields).ShouldNot(m, "should fail with exported extra fields")
+		Expect(extraUnexportedFields).Should(m, "should ignore unexported extra fields")
+		Expect(emptyFields).ShouldNot(m, "should fail with empty fields")
+	})
+
+	It("should ignore ignored fields", func() {
+		m := MatchAllFields(Fields{
+			"B": Equal("b"),
+			"A": Equal("a"),
+		})
+		Expect(extraFields).ShouldNot(m, "should fail with exported extra fields")
+
+		m = MatchAllFields(Fields{
+			"B": Equal("b"),
+			"A": Equal("a"),
+			"C": Ignore(),
+		})
+		Expect(extraFields).ShouldNot(m, "should fail with exported extra fields partially ignored")
+
+		m = MatchAllFields(Fields{
+			"B": Equal("b"),
+			"A": Equal("a"),
+			"C": Ignore(),
+			"D": Ignore(),
+		})
+		Expect(extraFields).Should(m, "should match with all remaining fields ignored")
+	})
+
+	It("should ignore ignored unexported fields", func() {
+		m := MatchAllFields(Fields{
+			"B": Equal("b"),
+			"A": Equal("a"),
+		})
+		Expect(extraUnexportedFields).ShouldNot(m, "should fail with exported extra fields")
+
+		m = MatchAllFields(Fields{
+			"B": Equal("b"),
+			"A": Equal("a"),
+			"c": Ignore(),
+		})
+		Expect(extraUnexportedFields).ShouldNot(m, "should fail with exported extra fields partially ignored")
+
+		m = MatchAllFields(Fields{
+			"B": Equal("b"),
+			"A": Equal("a"),
+			"c": Ignore(),
+			"d": Ignore(),
+		})
+		Expect(extraUnexportedFields).Should(m, "should match with all remaining fields ignored")
+
+		m = MatchAllFields(Fields{
+			"B": Equal("b"),
+			"A": Equal("a"),
+			"c": Ignore(),
+			"d": Reject(),
+		})
+		Expect(extraUnexportedFields).ShouldNot(m, "should fail if we used Reject() on an unexported field")
+	})
+
 	It("should ignore missing and extra fields", func() {
 		m := MatchFields(IgnoreMissing|IgnoreExtras, Fields{
 			"B": Equal("b"),
@@ -65,6 +135,7 @@ var _ = Describe("Struct", func() {
 		Expect(allFields).Should(m, "should match all fields")
 		Expect(missingFields).Should(m, "should ignore missing fields")
 		Expect(extraFields).Should(m, "should ignore extra fields")
+		Expect(extraUnexportedFields).Should(m, "should ignore unexported extra fields")
 		Expect(emptyFields).ShouldNot(m, "should fail with empty fields")
 
 		m = MatchFields(IgnoreMissing|IgnoreExtras, Fields{

gstruct/types.go

@@ -12,4 +12,8 @@ const (
 	//considered by the identifier function. All members that map to a given key must still match successfully
 	//with the matcher that is provided for that key.
 	AllowDuplicates
+	//IgnoreUnexportedExtras tells the matcher to ignore extra unexported fields, rather than triggering a failure.
+	//it is not possible to check the value of unexported fields, so this option is only useful when you want to
+	//check every exported fields, but you don't care about extra unexported fields.
+	IgnoreUnexportedExtras
 )