Skip to content
Skills Library
Programming · Testing

assertions

/assertions

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 synchronou

Author
onsi ↗
Repository
gomega ↗
Licence
MIT
Last repository change
09.10.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 09.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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 synchronou

Original author description

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 synchronou

How it works

  1. The two notations are identical
  2. The multi-return error idiom
  3. Succeed and HaveOccurred
  4. The .Error() chaining form
  5. Annotating assertions
  6. Adjusting failure output
  7. Making assertions inside helper functions
Original SKILL.md headings · 167 lines, 927 words
SKILL.md preview
---
name: assertions
description: 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.
---

# 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

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

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

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

For an `error` value you already hold, use `HaveOccurred`:

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

## The .Error() chaining form

To assert on the trailing error of a **multi-return** function while ignoring the other returns, chain `.Error()`:

```go
Expect(MultipleReturnValuesFunc()).Error().To(HaveOccurred())
Expect(MultipleReturnValuesFunc()).Error().NotTo(HaveOccurred())
```

`.Error()` retargets the assertion at the **last** return value (the error). The `To(HaveOccurred())` form *additionally* asserts that all the *other* returns are zero-valued; the `NotTo(HaveOccurred())` form lets the other returns be anything. The plain alternative is to capture and assert manually:

```go
_, _, _, err := MultipleReturnValuesFunc()
Expect(err).To(HaveOccurred())
```

## Annotating assertions

Pass a format string (with `fmt.Sprintf` args) or a `func() string` **after** the matcher. It's printed alongside the failure message to add context:

```go
Expect(ACTUAL).To(Equal(EXPECTED), "my annotation %d", foo)
Expect(ACTUAL).To(Equal(EXPECTED), func() string { return expensive() })
```

The `func() string` form is **lazily evaluated** — only called if the assertion fails — so use it for any annotation that's expensive to build.

## Adjusting failure output

On failure Gomega prints a recursive rendering of the objects involved, produced by the `format` subpackage. Tune it via package-level globals (set once, e.g. in a test helper or `TestMain`):

```go
import "github.com/onsi/gomega/format"

format.MaxLength = 4000   // truncate rendered output to N chars; 0 disables truncation
format.MaxDepth = 10      // max recursion depth into nested structures
format.TruncatedDiff = true   // for long strings, show only where they differ (false = full strings)
format.UseStringerRepresentation = false  // true => call String()/GoString() on Stringer/GoStringer types
format.PrintContextObjects = false        // true => print contents of context.Context objects
```

`UseStringerRepresentation` defaults to `false` on purpose: a `String()` method often hides fields you need to diagnose a failure. Leave it off unless you know the stringer is complete.

**`GomegaStringer` interface.** Implement `GomegaString() string` on a type and Gomega always uses it for that type's rendering, regardless of `UseStringerRepresentation`. Best practice: define it in a `_test.go` helper file so you don't leak it into your package's exported API.

```go
func (w Widget) GomegaString() string { return fmt.Sprintf("Widget<%s>", w.id) }
```

**Custom formatters.** Register a `format.CustomFormatter` (`func(value any) (string, bool)`) — return `(rendered, true)` to handle a value, or `("", false)` to pass. Custom formatters take precedence over `GomegaStringer` and `UseStringerRepresentation`, and their output is not truncated:

```go
key := format.RegisterCustomFormatter(myFormatter)
defer format.UnregisterCustomFormatter(key)
```

**`format.Object`.** Reuse Gomega's renderer directly (the int is indentation depth):

```go
fmt.Println(format.Object(theThing, 1))
```

## Making assertions inside helper functions

Factoring assertions into a helper reduces boilerplate, but a naive helper reports failures at the line *inside the helper*, not the caller. Fix the reported line number with one of these.

**With Ginkgo — `GinkgoHelper()` (recommended).** Call it first thing in the helper; Ginkgo then attributes failures to the call site. It nests cleanly across multiple helper layers:

```go
func expectComponents(te TurboEncabulator, components ...string) {
    GinkgoHelper()
    got, err := te.GetComponents()
    Expect(err).NotTo(HaveOccurred())
    Expect(got).To(ConsistOf(components))
}
```

**Without Ginkgo — `WithOffset` / `ExpectWithOffset`.** The offset is how many stack frames to skip; `1` points at the helper's caller. These are equivalent:

```go
Expect(err).WithOffset(1).NotTo(HaveOccurred())
ExpectWithOffset(1, err).NotTo(HaveOccurred())
```

(`Eventually`/`Consistently` have the same `WithOffset` / `…WithOffset` forms — see `gomega:async`.)

**Plain `testing` — `NewWithT(t)`.** Wrap a `*testing.T` to get a `*WithT` carrying `Expect`, `Eventually`, and `Consistently`. Create a fresh one per test (no global fail handler needed):

```go
func TestFarmHasCow(t *testing.T) {
    g := NewWithT(t)
    f := farm.New([]string{"Cow", "Horse"})
    g.Expect(f.HasCow()).To(BeTrue(), "farm should have a cow")
}
```

**The `g Gomega` callback pattern.** A helper can accept a `Gomega` and assert through it, decoupling the helper from how failures are reported:

```go
func expectValidWidget(g Gomega, w Widget) {
    g.Expect(w.ID).NotTo(BeEmpty())
    g.Expect(w.Size).To(BeNumerically(">", 0))
}

g := NewWithT(t)        // or the g passed into an Eventually callback
expectValidWidget(g, w)
```

This is the **same `g Gomega`** that `Eventually(func(g Gomega) {...})` passes into polled callbacks (`gomega:async`) — so a `g Gomega` helper works in both synchronous and polled contexts. To build a `Gomega` wired to your own fail handler, use `NewGomega(failHandler)`.

**Don't** call the global `Expect`/`Ω` inside an `Eventually`/`Consistently` callback — those failures won't be intercepted by the poller. Always assert through the passed-in `g Gomega` there. See `gomega:async`.

For richer, reusable assertions consider a real matcher instead of a helper — see `gomega:custom-matchers`.

Versions

The database has no other skills named assertions.

Database snapshot: 13.11.2026 · package version f0e1a39a1762 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100overview
    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…
  • 100async
    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…
  • 100dart-migrate-to-checks-package
    Use when migrating test assertions from legacy package:matcher expect() syntax to package:checks fluent assertions.
  • 95postman-test-script-generator
    Write Postman test scripts (JavaScript) for pre-request logic and post-response assertions, and embed them directly into a Postman collection. Use this skill whenever the user wants to add tests to Postman requests, asks about "pm.test", "pm.expect", "Postman assertions", "test…
  • 100test-assertions
    Write test assertions as complete, strict deep-equality checks, and rewrite existing tests to the same standard. Use when writing new tests, adding assertions, reviewing test quality, strengthening weak tests, or replacing fragmented assertions in a file, directory, diff, or repository.
  • 100testing-api-assertions
    Verify API requests in tests. Use when testing that correct API calls are made for create, update, or delete operations. Use when testing mutations, form submissions, or actions with backend side effects.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.