composing-matchers

Composing and transforming matchers

Gomega matchers are values, so you can wrap and nest them to express several requirements in a single Expect/Eventually. Start with gomega:matchers for the catalog; reach here when one assertion needs to do more. Docs: https://onsi.github.io/gomega/#composing-matchers.

Logical combinators

Expect(n).To(And(BeNumerically(">", 0), BeNumerically("<", 10)))   // all must pass
Expect(msg).To(Or(Equal("Success"), MatchRegexp(`^Error .+$`)))    // any may pass
Expect(s).To(Not(BeEmpty()))                                        // negate

• And(ms ...GomegaMatcher) / SatisfyAll(...) — identical; succeeds only if every matcher passes. Short-circuits on the first failure.
• Or(ms ...GomegaMatcher) / SatisfyAny(...) — identical; succeeds if any matcher passes. Short-circuits on the first success.
• Not(matcher GomegaMatcher) — logical negation; usually clearer than the .NotTo(...) form when nested.

These are the building blocks for lightweight named matchers:

func BeBetween(min, max int) GomegaMatcher {
    return SatisfyAll(BeNumerically(">", min), BeNumerically("<", max))
}
Expect(n).To(BeBetween(0, 10))

WithTransform — map the actual, then match

WithTransform(transform any, matcher GomegaMatcher) applies transform to ACTUAL and matches the result.

Expect(element).To(WithTransform(func(e Element) Color { return e.Color }, Equal(BLUE)))

Transform-function rules: it must take exactly one argument (the actual) and return either one value, or (value, error). Returning an error fails the assertion gracefully instead of panicking — useful for transforms that accept several input types:

func HaveSprocketName(name string) GomegaMatcher {
    return WithTransform(func(actual any) (string, error) {
        switch s := actual.(type) {
        case *Sprocket: return s.Name, nil
        case Sprocket:  return s.Name, nil
        default:        return "", fmt.Errorf("expected a Sprocket, got %T", actual)
        }
    }, Equal(name))
}