overview

---
name: overview
description: The Gomega mental model for writing assertions in Go — the Expect/Ω notation, matchers-are-values, the multi-return error idiom, synchronous vs asynchronous (Eventually/Consistently) assertions, and a map of the whole library including the gstruct/ghttp/gexec/gbytes/gleak/gmeasure sub-libraries. Use this first when you start writing or reviewing Gomega assertions, or to decide which gomega:* skill to reach for. Routes to every other gomega:* skill.
---

# Gomega: the mental model

Gomega is a matcher/assertion library for Go. It pairs best with the [Ginkgo](https://github.com/onsi/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:

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

## The shape of every assertion

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

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