# Overview

The Ginkgo mental model for writing Go tests, the one idea that explains everything...

- 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 overview -g -a claude-code -y`
Codex: `npx skills add onsi/ginkgo --skill overview -g -a codex -y`
Cursor: `npx skills add onsi/ginkgo --skill overview -g -a cursor -y`
Gemini CLI: `npx skills add onsi/ginkgo --skill overview -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add onsi/ginkgo`

## Description

The Ginkgo mental model for writing Go tests, the one idea that explains everything (Ginkgo builds a spec tree at construction time, then runs it) and its consequences for how you write specs, plus spec independence and the node taxonomy. Use this first when you start working with Ginkgo in a project, or to decide how to approach a Ginkgo task. Routes to the other ginkgo:* skills.

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

# Ginkgo: the mental model

Ginkgo is an expressive BDD-style testing framework for Go, paired with the [Gomega](https://onsi.github.io/gomega/) matcher library. You build suites out of nested **container** nodes (`Describe`/`Context`/`When`) and **subject** nodes (`It`), with **setup** nodes (`BeforeEach`/`AfterEach`/…) supplying state. You drive it with the `ginkgo` CLI.  Strongly prefer `ginkgo` over `go test`.

Read the canonical narrative docs at <https://onsi.github.io/ginkgo/>, they are the source of truth. This skill is the orientation; the other skills go deep.

## The one idea: tree construction, then running

**Ginkgo runs your suite in two distinct phases.** Internalizing this explains nearly every Ginkgo gotcha:

1. **Tree-construction phase.** Ginkgo invokes *every container body exactly once* to discover the structure of your suite. It collects, but does **not** run, the closures you pass to setup and subject nodes. The result is a tree it flattens into a list of specs.
2. **Run phase.** Ginkgo walks the flattened spec list (randomized, possibly in parallel) and, for each spec, runs its setup closures, then its one subject closure, then its cleanup closures.

**Container bodies run at construction time. Setup/subject closures run later, at run time.** The consequences you must internalize:

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