Wiring Ginkgo into a suite

The one-time setup. For the mental model see ginkgo:overview; to start authoring see ginkgo:writing-specs. Docs: https://onsi.github.io/ginkgo/#getting-started.

1. Install the CLI and the libraries

go install github.com/onsi/ginkgo/v2/ginkgo   # the `ginkgo` CLI binary → $GOBIN (put it on $PATH)
go get github.com/onsi/gomega/...             # the Gomega matcher library

ginkgo version confirms the install. The CLI version must match the github.com/onsi/ginkgo/v2 version in your go.mod, re-run go install ... from the package to sync them. The current major version is v2; everything here assumes it. In CI, sidestep version drift by invoking the CLI via go run github.com/onsi/ginkgo/v2/ginkgo (→ ginkgo:ci).

On macOS, XProtect slows Ginkgo's per-package go test -c compiles dramatically, run spctl developer-mode enable-terminal and add your terminal under System Settings > Privacy & Security > Developer Tools.

2. Bootstrap the suite

From inside the package you want to test:

cd path/to/books
ginkgo bootstrap        # generates books_suite_test.go

package books_test

import (
	"testing"

	. "github.com/onsi/ginkgo/v2"
	. "github.com/onsi/gomega"
)

func TestBooks(t *testing.T) {
	RegisterFailHandler(Fail)
	RunSpecs(t, "Books Suite")
}

What each line buys you:

• func TestBooks(t *testing.T) is the single go test entry point. Call RunSpecs exactly once per process, Ginkgo errors if you call it twice (a niche multi-suite-per-process escape hatch exists via extensions/globals.Reset(), see ginkgo:running).
• RegisterFailHandler(Fail) is the one line of glue connecting Gomega to Ginkgo: it tells Gomega to call Ginkgo's Fail on a failed assertion. Without dot-imports this reads gomega.RegisterFailHandler(ginkgo.Fail).
• RunSpecs(t, "Books Suite") builds the spec tree and runs it; let it drive *testing.T for you.