# Setup

Wire Ginkgo into a Go package, install the ginkgo CLI and Ginkgo+Gomega, ginkgo...

- Repository: https://github.com/onsi/ginkgo (9071 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-09
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add onsi/ginkgo --skill setup -g -a claude-code -y`
Codex: `npx skills add onsi/ginkgo --skill setup -g -a codex -y`
Cursor: `npx skills add onsi/ginkgo --skill setup -g -a cursor -y`
Gemini CLI: `npx skills add onsi/ginkgo --skill setup -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add onsi/ginkgo`

## Description

Wire Ginkgo into a Go package, install the ginkgo CLI and Ginkgo+Gomega, ginkgo bootstrap to generate the suite_test.go (TestXxx/RegisterFailHandler(Fail)/RunSpecs), the package xxx_test convention, dot-import alternatives (aliased import, dsl/* subpackages, --nodot), ginkgo generate, and *testing.T interop via GinkgoT()/GinkgoTB() for testify/gomock. Use when first adding Ginkgo to a repo, bootstrapping a suite, or integrating a *testing.T-based library.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

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

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

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

The rest: https://github.com/onsi/ginkgo/blob/HEAD/plugins/ginkgo/skills/setup/SKILL.md