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.

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 Gomega callbacks, 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 GomegaMatcher interface and gcustom → 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:gstruct
• ghttp — a test server for asserting on and stubbing HTTP clients → gomega:ghttp
• gexec — build, run, signal, and assert on external processes → gomega:gexec
• gbytes — assert on streaming io buffers with the Say matcher → gomega:gbytes
• gleak — detect leaked goroutines → gomega:gleak
• gmeasure — benchmark and measure code → gomega:gmeasure