assertions

Synchronous assertions

The core mechanics of asserting now (vs. polling — see gomega:async). Assumes a dot-import (. "github.com/onsi/gomega"). Narrative docs: https://onsi.github.io/gomega/#making-assertions. For the big picture and skill map see gomega:overview.

The two notations are identical

Expect(ACTUAL).To(Equal(EXPECTED))      // Expect notation
Expect(ACTUAL).NotTo(Equal(EXPECTED))
Expect(ACTUAL).ToNot(Equal(EXPECTED))   // ToNot == NotTo

Ω(ACTUAL).Should(Equal(EXPECTED))       // Ω notation (⌥z on macOS)
Ω(ACTUAL).ShouldNot(Equal(EXPECTED))

To == Should, and NotTo == ToNot == ShouldNot — pure syntactic sugar. ACTUAL (left) is anything; the matcher (right) must satisfy GomegaMatcher. Pick one notation per codebase and stay consistent. Matchers are values — see gomega:matchers.

The multi-return error idiom

Expect/Ω accept multiple arguments. The matcher runs against the first; the assertion fails unless every trailing argument is nil or zero-valued. This collapses Go's (value, error) pattern:

// instead of:
result, err := DoSomethingHard()
Expect(err).NotTo(HaveOccurred())
Expect(result).To(Equal("foo"))

// write:
Expect(DoSomethingHard()).To(Equal("foo"))   // passes only if return is ("foo", nil)

Succeed and HaveOccurred

For a function returning only error, use Succeed:

Expect(DoSomethingSimple()).To(Succeed())     // func() error
Expect(DoSomethingSimple()).NotTo(Succeed())

For an error value you already hold, use HaveOccurred:

err := DoSomethingSimple()
Expect(err).NotTo(HaveOccurred())
Expect(err).To(HaveOccurred())

Use Succeed when calling the function inline; use HaveOccurred when you have an err variable. To assert on the error's content (not just its presence), reach for MatchError and friends in gomega:matchers.

Don't use Succeed with a multi-return function. The matcher only sees the first return value; the rest are consumed by the multi-return idiom above. Expect(DoSomethingHard()).To(Succeed()) matches against the string, not the error, and Expect(DoSomethingHard()).NotTo(Succeed()) can never pass.