overview

Gomega: the mental model

Gomega is a matcher/assertion library for Go. It pairs best with the Ginkgo test framework but works with any Go test. The canonical narrative docs at https://onsi.github.io/gomega/ are the source of truth; this skill is the orientation and the other skills go deep.

Conventionally you dot-import Gomega so Expect, Equal, Eventually, etc. are unqualified:

import (
	. "github.com/onsi/gomega"
	. "github.com/onsi/ginkgo/v2" // if using Ginkgo
)

The shape of every assertion

Expect(ACTUAL).To(MATCHER)        //  Expect(x).To(Equal(3))
Expect(ACTUAL).NotTo(MATCHER)

• ACTUAL (left) is anything — the value under test.
• MATCHER (right) must satisfy the GomegaMatcher interface. Gomega's matchers (Equal(3), HaveLen(2), …) are just functions that return a matcher value — so you can store, pass, and compose them. → gomega:matchers, gomega:composing-matchers.
• Ω(ACTUAL).Should(MATCHER) / .ShouldNot(...) is the exact equivalent in the Ω notation (⌥z on macOS). To/Should and NotTo/ToNot/ShouldNot are interchangeable syntactic sugar — pick one notation and stay consistent.

Three things to internalize

1. The multi-return error idiom. Expect/Ω accept multiple arguments; the match runs against the first, and fails unless all later arguments are nil/zero. This collapses Go's (value, error) pattern:

Expect(DoSomethingHard()).To(Equal("foo"))   // passes only if return is ("foo", nil)
Expect(DoSomethingSimple()).To(Succeed())     // for funcs returning only error

Use .Error() to assert on the trailing error of a multi-return func while ignoring the rest. → gomega:assertions.

2. Failures go through a fail handler. Gomega calls a registered handler on failure. With Ginkgo, RegisterFailHandler(Fail) (auto-generated by ginkgo bootstrap). With plain testing, use g := NewWithT(t) and call g.Expect(...). → gomega:assertions.