gstruct

gstruct: matching complex data types

gstruct builds composite matchers that apply a separate matcher to each field of a struct, each element of a slice, each key of a map, or the target of a pointer. It is the tool for fuzzy-matching large, deeply nested values. Docs: https://onsi.github.io/gomega/#gstruct-testing-complex-data-types.

Dot-import gomega; import gstruct normally (or dot-import it too):

import (
	. "github.com/onsi/gomega"
	"github.com/onsi/gomega/gstruct"
)

The values in Fields/Elements/Keys are themselves matchers. That is the whole point: compose with the core catalog (gomega:matchers) and combinators like And/Or/Not/WithTransform (gomega:composing-matchers). Examples below assume gstruct is dot-imported for brevity.

If you find yourself building an overly complex gstruct matcher, consider if you should be building a custom matcher (gomega:custom-matchers) instead.

Structs — Fields

Fields is map[string]types.GomegaMatcher keyed by field name.

actual := struct {
	A int
	B bool
	C string
}{5, true, "foo"}

Expect(actual).To(MatchAllFields(Fields{
	"A": BeNumerically("<", 10),
	"B": BeTrue(),
	"C": Equal("foo"),
}))

MatchAllFields requires an exact 1:1 mapping — every field must have a matcher and every matcher must map to a field. This is great for maintainability: adding or removing a struct field breaks the test until you update it.

To match a subset/superset, use MatchFields(options, Fields{...}):

// IgnoreExtras: ignore struct fields with no matcher
Expect(actual).To(MatchFields(IgnoreExtras, Fields{
	"A": BeNumerically("<", 10),
	"B": BeTrue(), // no entry for C — fine
}))

// IgnoreMissing: ignore matchers with no corresponding field
Expect(actual).To(MatchFields(IgnoreMissing, Fields{
	"A": BeNumerically("<", 10),
	"B": BeTrue(),
	"C": Equal("foo"),
	"D": Equal("bar"), // ignored — actual has no field D
}))

IgnoreUnexportedExtras is a middle ground: it ignores only unexported extra fields (gstruct can't read them via reflect anyway) while still requiring all exported fields to be matched.