From gomega
Explains the Gomega matcher/assertion library for Go: Expect/Ω notation, matchers-as-values, multi-return error idiom, sync vs async assertions, and sub-library overview. Routes to specialized Gomega skills.
How this skill is triggered — by the user, by Claude, or both
Slash command
/gomega:overviewThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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
)
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.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.
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.
Core mechanics
Expect/Ω, error handling, Succeed/HaveOccurred, negation, annotations, output tuning, asserting inside helpers → gomega:assertionsEventually/Consistently, polling functions & g Gomega callbacks, contexts, timeouts, StopTrying/TryAgainAfter → gomega:asyncMatchers
gomega:matchersAnd/Or/Not, SatisfyAll/SatisfyAny, WithTransform, HaveField, HaveValue → gomega:composing-matchersGomegaMatcher interface and gcustom → gomega:custom-matchersSub-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 streaming io buffers with the Say matcher → gomega:gbytesgleak — detect leaked goroutines → gomega:gleakgmeasure — benchmark and measure code → gomega:gmeasurenpx claudepluginhub onsi/gomega --plugin gomegaExplains the Ginkgo mental model for writing Go tests: tree construction then running, spec independence, and node taxonomy. Use this first when working with Ginkgo.
Writes correct synchronous Gomega assertions in Go tests: dual notation, multi-return error idiom, Succeed vs. HaveOccurred, .Error() chaining, annotation helpers, and failure-output tuning.
Provides guidance on testify for Go testing: assert vs require, core assertions, mocks, and suites. Activates when code imports github.com/stretchr/testify.