Skip to content
Skills Library
Programming · Testing

gstruct

/gstruct

Deep, partial matching of nested structs, slices, maps, and pointers with gstruct — MatchAllFields/MatchFields/Fields, MatchAllElements/MatchElements/Elements (idFn), MatchAllKeys/MatchKeys/Keys, PointTo, and the IgnoreExtras/IgnoreMissing/IgnoreUnexportedExtras/AllowDuplicates options, plus Ignore()/Reject(). Use when asserting against large or deeply nested data structures where you want to apply a different matcher to each field, element, or key.

Author
onsi ↗
Repository
gomega ↗
Licence
MIT
Last repository change
09.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 09.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Deep, partial matching of nested structs, slices, maps, and pointers with gstruct — MatchAllFields/MatchFields/Fields, MatchAllElements/MatchElements/Elements (idFn), MatchAllKeys/MatchKeys/Keys, PointTo, and the IgnoreExtras/IgnoreMissing/IgnoreUnexportedExtras/AllowDuplicates options, plus Ignore()/Reject(). Use when asserting against large or deeply nested data structures where you want to apply a different matcher to each field, element, or key.

Original author description

Deep, partial matching of nested structs, slices, maps, and pointers with gstruct — MatchAllFields/MatchFields/Fields, MatchAllElements/MatchElements/Elements (idFn), MatchAllKeys/MatchKeys/Keys, PointTo, and the IgnoreExtras/IgnoreMissing/IgnoreUnexportedExtras/AllowDuplicates options, plus Ignore()/Reject(). Use when asserting against large or deeply nested data structures where you want to apply a different matcher to each field, element, or key.

How it works

  1. Structs — Fields
  2. Slices — Elements + an id function
  3. Maps — Keys
  4. Pointers — PointTo
  5. Ignore() and Reject()
  6. Putting it all together
  7. Gotchas
Original SKILL.md headings · 154 lines, 735 words
SKILL.md preview
---
name: gstruct
description: Deep, partial matching of nested structs, slices, maps, and pointers with gstruct — MatchAllFields/MatchFields/Fields, MatchAllElements/MatchElements/Elements (idFn), MatchAllKeys/MatchKeys/Keys, PointTo, and the IgnoreExtras/IgnoreMissing/IgnoreUnexportedExtras/AllowDuplicates options, plus Ignore()/Reject(). Use when asserting against large or deeply nested data structures where you want to apply a different matcher to each field, element, or key.
---

# 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):

```go
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.

```go
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{...})`:

```go
// 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.

## Slices — `Elements` + an id function

`Elements` is `map[string]types.GomegaMatcher` keyed by a string id. You supply an `Identifier` (`func(element any) string`) that maps each element to its key.

```go
actual := []string{"A: foo bar baz", "B: once upon a time", "C: the end"}
id := func(element any) string { return string(element.(string)[0]) }

Expect(actual).To(MatchAllElements(id, Elements{
	"A": Not(BeZero()),
	"B": MatchRegexp("[A-Z]: [a-z ]+"),
	"C": ContainSubstring("end"),
}))
```

`MatchAllElements` requires a 1:1 mapping. Use `MatchElements(id, options, Elements{...})` with `IgnoreExtras`/`IgnoreMissing` to relax, exactly as with fields. `AllowDuplicates` lets several elements share one key/matcher (all of them must pass).

Index-based variants `MatchAllElementsWithIndex`/`MatchElementsWithIndex` take an `IdentifierWithIndex` (`func(index int, element any) string`); the built-in `IndexIdentity` just uses the index as the key.

## Maps — `Keys`

The `*Fields` API has a `*Keys` mirror for maps: `MatchAllKeys(Keys{...})` and `MatchKeys(options, Keys{...})`.

```go
actual := map[string]string{"A": "correct", "B": "incorrect"}

// MatchAllKeys requires every key be matched (this would fail without B):
Expect(actual).To(MatchAllKeys(Keys{
	"A": Equal("correct"),
	"B": Equal("incorrect"),
}))

// IgnoreMissing tolerates matchers for absent keys:
Expect(actual).To(MatchKeys(IgnoreMissing, Keys{
	"A": Equal("correct"),
	"B": Equal("incorrect"),
	"C": Equal("whatever"), // ignored — actual has no key C
}))
```

## Pointers — `PointTo`

`PointTo(matcher)` dereferences a pointer and applies `matcher` to the pointed-to value. It fails if the pointer is `nil`.

```go
foo := 5
Expect(&foo).To(PointTo(Equal(5)))
var bar *int
Expect(bar).NotTo(PointTo(BeNil())) // nil pointer fails PointTo
```

## `Ignore()` and `Reject()`

`Ignore()` always succeeds, `Reject()` always fails — use them as entries to skip a field/element or to assert one must never appear.

## Putting it all together

The matchers nest arbitrarily, mixing struct/slice/map/pointer matchers with the core catalog:

```go
coreID := func(element any) string { return strconv.Itoa(element.(CoreStats).Index) }

Expect(actual).To(MatchAllFields(Fields{
	"Name":      Ignore(),
	"StartTime": BeTemporally(">=", time.Now().Add(-100*time.Hour)),
	"CPU": PointTo(MatchAllFields(Fields{
		"Time":                 BeTemporally(">=", time.Now().Add(-time.Hour)),
		"UsageNanoCores":       BeNumerically("~", 1e9, 1e8),
		"UsageCoreNanoSeconds": BeNumerically(">", 1e6),
		"Cores": MatchElements(coreID, IgnoreExtras, Elements{
			"0": MatchAllFields(Fields{
				"Index":                Ignore(),
				"UsageNanoCores":       BeNumerically("<", 1e9),
				"UsageCoreNanoSeconds": BeNumerically(">", 1e5),
			}),
		}),
	})),
	"Memory": PointTo(MatchAllFields(Fields{
		"Time":            BeTemporally(">=", time.Now().Add(-time.Hour)),
		"AvailableBytes":  BeZero(),
		"UsageBytes":      BeNumerically(">", 5e6),
		"WorkingSetBytes": BeNumerically(">", 5e6),
	})),
	"Rootfs": Ignore(),
	"Logs":   Ignore(),
}))
```

## Gotchas

- **`MatchAllFields`/`MatchAllElements`/`MatchAllKeys` fail on missing OR extra entries.** They demand an exact 1:1 mapping. The instant you want a partial match, switch to `MatchFields`/`MatchElements`/`MatchKeys` and pass `IgnoreExtras`, `IgnoreMissing`, or both (`IgnoreExtras|IgnoreMissing`).
- **The id function must produce unique, stable keys.** Two elements mapping to the same key collide and fail unless you pass `AllowDuplicates`. Don't derive keys from data that changes between runs.
- **`Elements` keys are strings.** The id function returns a `string`, so numeric ids must be stringified (e.g. `strconv.Itoa(i)`), and the keys in your `Elements{}` literal must match those strings exactly.
- **`PointTo` rejects `nil` pointers** — a `nil` actual fails the match outright, before the inner matcher ever runs.
- Field/element/key matcher values are ordinary matchers, so compose freely with `gomega:matchers` and `gomega:composing-matchers`.

Versions

The database has no other skills named gstruct.

Database snapshot: 13.11.2026 · package version 9b77f5d15203 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

No similar skills in the database.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.