gomega

Write correct synchronous Gomega assertions — Expect/Ω notation, the To/NotTo/ToNot/Should/ShouldNot equivalences, the multi-return error idiom, Succeed vs HaveOccurred, the .Error() chaining form, annotating assertions (format-string and func()string), tuning failure output via the format subpackage (MaxLength/MaxDepth/UseStringerRepresentation/GomegaStringer/TruncatedDiff/RegisterCustomFormatter/format.Object), and asserting inside helper functions with GinkgoHelper/WithOffset/ExpectWithOffset, NewWithT(t) for plain testing, and the g Gomega callback. Use when writing or reviewing synchronous (non-polling) Gomega assertions.

Polling assertions in Gomega — Eventually (poll until it passes) and Consistently (must keep passing), the func(g Gomega) callback idiom, WithTimeout/WithPolling/Within/ProbeEvery, WithContext and Ginkgo SpecContext, StopTrying/TryAgainAfter bail-outs, MustPassRepeatedly, and default-interval tuning. Use when an assertion can't be true synchronously — anything involving goroutines, channels, network calls, eventual consistency, or "wait until / stays true".

Build compound Gomega assertions by combining matchers — And/SatisfyAll (all pass), Or/SatisfyAny (any pass), Not (negate), WithTransform to map the actual before matching, Satisfy for an ad-hoc predicate, HaveValue to dereference pointers/interfaces, HaveField for struct fields and method results, HaveEach for every element, plus the matchers-as-arguments idiom that lets you nest matchers inside ContainElement/ConsistOf/HaveKeyWithValue/Receive. Use when one Expect needs several requirements at once, or you want to assert deep into a value without writing a custom matcher.

Writing your own Gomega matchers — the GomegaMatcher interface (Match/FailureMessage/NegatedFailureMessage), gcustom.MakeMatcher with message templates and template data, the format package helpers (format.Message/format.Object), MatchMayChangeInTheFuture and StopTrying for Eventually/Consistently, and how to test and package custom matchers. Use when a built-in or composed matcher can't express your domain assertion and you need to build one.

Testing streaming io buffers with gbytes — gbytes.NewBuffer() (an io.Writer also returned by gexec sessions), the Say(regexp) matcher that forward-scans from a moving read cursor, the canonical Eventually(buffer).Should(Say(...)) streaming pattern, sequential cursor-advancing Say calls, Contents(), BufferWithBytes/BufferReader, buffer.Detect for branching, and TimeoutReader/Writer/Closer for testing blocking io.Reader/Writer/Closer. Use when asserting on streaming or incremental output (process stdout/stderr, API streams, io.Readers) rather than a complete value.

Testing external processes with gexec — compile binaries with Build/BuildWithEnvironment/BuildIn and CleanupBuildArtifacts, start them with Start returning a *Session, await exit with the Exit matcher (Eventually(session).Should(Exit(0))), Wait/ExitCode, signal via Kill/Terminate/Interrupt/Signal and package-level KillAndWait/TerminateAndWait, and assert on session.Out/Err which are gbytes buffers (Say, Contents). Use when building, running, signaling, or asserting on subprocesses in Go tests.

The ghttp test HTTP server for testing HTTP clients — NewServer/NewTLSServer, AppendHandlers, the Verify* assertions (VerifyRequest/VerifyHeader/VerifyHeaderKV/VerifyJSON/VerifyForm/VerifyBasicAuth/VerifyContentType/VerifyBody), RespondWith/RespondWithJSONEncoded(Ptr), CombineHandlers, RouteToHandler for unordered MUXed routes, AllowUnhandledRequests, RoundTripper, and TLS. Use when testing code that makes outbound HTTP requests.

gleak goroutine leak detection — capture a Goroutines() snapshot before a test, then Eventually(Goroutines).ShouldNot(HaveLeaked(snapshot)) to assert none leaked, with the BeforeEach/AfterEach/DeferCleanup pattern, ignoring matchers IgnoringTopFunction/IgnoringInBacktrace/IgnoringGoroutines/IgnoringCreator, well-known non-leaky goroutines, goroutine IDs, ReportFilenameWithPath, and the Ginkgo -p IgnoreGinkgoParallelClient gotcha. Use when a test must verify goroutines started during the test have all wound down and nothing leaked.

Benchmark and measure Go code with gmeasure — an Experiment groups named Measurements, recorded via RecordValue/RecordDuration/MeasureDuration or repeated Sample/SampleValue/SampleDuration with SamplingConfig, timed inline with a Stopwatch, summarized through GetStats/Stats (StatMin/Max/Mean/Median/StdDev, ValueFor/DurationFor) and compared with RankStats; decorate output with Units/Precision/Style/Annotation, render in Ginkgo via AddReportEntry, and persist with ExperimentCache. Use when you need human-readable benchmarks, performance reports, or regression baselines (not pass/fail assertions on their own).

Deep, partial matching of nested structs, slices, maps, and pointers with gstruct — MatchAllFields/MatchFields/Fields, MatchAllElements/MatchElements/Elements (idFn), MatchAllKeys/MatchKeys/Keys, PointTo, and the IgnoreExtras/IgnoreMissing/IgnoreUnexportedExtras/AllowDuplicates options, plus Ignore()/Reject(). Use when asserting against large or deeply nested data structures where you want to apply a different matcher to each field, element, or key.

The complete catalog of Gomega's built-in matchers, grouped by category — equivalence (Equal/BeEquivalentTo/BeComparableTo/BeIdenticalTo/BeAssignableToTypeOf), presence (BeNil/BeZero/BeEmpty), truthiness (BeTrue/BeFalse/BeTrueBecause), errors (HaveOccurred/Succeed/MatchError), channels (Receive/BeClosed/BeSent), files, strings/JSON/XML/YAML, collections (ContainElement/ConsistOf/HaveExactElements/HaveKey), structs (HaveField), numbers/times (BeNumerically/BeTemporally), values (HaveValue), HTTP responses, and panics. Use when you need to find or choose the right matcher for an assertion instead of defaulting to Equal.

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.