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 theGomegaMatcherinterface. 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 (⌥zon macOS).To/ShouldandNotTo/ToNot/ShouldNotare 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.
3. Synchronous vs asynchronous. Expect asserts now. Eventually/Consistently poll a value, function, or g Gomega callback until a matcher passes (or keeps passing). Async is its own world with timeouts, contexts, and bail-out signals. → gomega:async.
Pick the most specific matcher
The single biggest quality lever: prefer the matcher that says what you mean. Expect(err).To(MatchError(...)) over Expect(err.Error()).To(Equal(...)); Expect(xs).To(ConsistOf(...)) over Expect(len(xs)).To(Equal(3)). Specific matchers produce far better failure messages. Browse the full catalog before reaching for Equal — Gomega has a deep, expressive matcher library. → gomega:matchers.
Where to go next
Core mechanics
- Synchronous assertions —
Expect/Ω, error handling,Succeed/HaveOccurred, negation, annotations, output tuning, asserting inside helpers →gomega:assertions - Asynchronous assertions —
Eventually/Consistently, polling functions &g Gomegacallbacks, contexts, timeouts,StopTrying/TryAgainAfter→gomega:async
Matchers
- The full catalog (terse, grouped — start here to discover matchers) →
gomega:matchers - Composing —
And/Or/Not,SatisfyAll/SatisfyAny,WithTransform,HaveField,HaveValue→gomega:composing-matchers - Writing your own — the
GomegaMatcherinterface andgcustom→gomega:custom-matchers
Sub-libraries (each its own import; reach for them by task)
gstruct— deep, partial matching of nested structs, slices, and maps →gomega:gstructghttp— a test server for asserting on and stubbing HTTP clients →gomega:ghttpgexec— build, run, signal, and assert on external processes →gomega:gexecgbytes— assert on streamingiobuffers with theSaymatcher →gomega:gbytesgleak— detect leaked goroutines →gomega:gleakgmeasure— benchmark and measure code →gomega:gmeasure