# Ginkgo — BDD Testing Framework for Go

> An expressive BDD-style testing framework for Go with support for spec nesting, lifecycle hooks, parallel execution, and structured test output. Pairs with the Gomega matcher library.

## Install

Save in your project root:

# Ginkgo — BDD Testing Framework for Go

## Quick Use
```bash
go install github.com/onsi/ginkgo/v2/ginkgo@latest
cd mypackage
ginkgo bootstrap   # create suite file
ginkgo generate    # create spec file
ginkgo             # run tests
```

## Introduction
Ginkgo is a testing framework for Go that uses Describe/Context/It blocks to organize tests in a behavior-driven style. It integrates with Go's native testing infrastructure while adding features like ordered and parallel specs, lifecycle hooks, and rich reporting. Gomega, its companion matcher library, provides fluent assertions.

## What Ginkgo Does
- Structures tests using nested Describe, Context, and It blocks
- Runs specs in parallel across multiple processes with automatic output isolation
- Provides BeforeEach, AfterEach, BeforeSuite, and AfterSuite lifecycle hooks
- Generates JUnit, JSON, and custom-format test reports
- Integrates with `go test` so CI pipelines need no special tooling

## Architecture Overview
Ginkgo builds a spec tree at init time by executing the closure-based DSL. The runner then walks the tree, executing each leaf It node with its accumulated BeforeEach chain. Parallel mode forks multiple `go test` processes, each running a subset of specs, with a central process collecting results. Gomega assertions hook into Ginkgo's failure reporting to produce clear output on mismatch.

## Setup & Configuration
- Install the CLI with `go install github.com/onsi/ginkgo/v2/ginkgo@latest`
- Bootstrap a suite with `ginkgo bootstrap` in any package directory
- Generate spec files with `ginkgo generate <name>`
- Configure parallelism with `ginkgo -p` or `ginkgo --procs=N`
- Add labels and decorators for filtering: `It("works", Label("integration"), func() { ... })`

## Key Features
- Spec decorators: Serial, Ordered, FlakeAttempts, and custom Labels
- Built-in support for table-driven specs via DescribeTable and Entry
- Progress reporting shows which spec is currently running in long suites
- Interruption handling cleans up resources on timeout or SIGINT
- Watch mode re-runs affected specs when source files change

## Comparison with Similar Tools
- **testing (stdlib)** — simpler, no dependencies, but lacks nesting, lifecycle hooks, and parallel isolation
- **Testify** — adds assertions and mocks to stdlib tests; less structured than BDD-style specs
- **GoConvey** — BDD with a browser UI; Ginkgo offers stronger parallel execution and reporting
- **go-check** — older BDD-like framework; Ginkgo has a more active community and richer feature set

## FAQ
**Q: Does Ginkgo work with go test?**
A: Yes. Ginkgo specs compile as standard Go tests. Running `go test` works, though the `ginkgo` CLI adds parallelism and reporting features.

**Q: How do I run only specific specs?**
A: Use `ginkgo --focus="pattern"` to match spec text, or `ginkgo --label-filter="integration"` to filter by label.

**Q: Can I mix Ginkgo specs with regular Go tests?**
A: Yes. Standard Test functions coexist in the same package and run alongside Ginkgo specs.

**Q: Is Gomega required?**
A: No. You can use any assertion library or bare `t.Fatal` calls, but Gomega's matchers integrate tightly with Ginkgo's failure reporting.

## Sources
- https://github.com/onsi/ginkgo
- https://onsi.github.io/ginkgo/

---
Source: https://tokrepo.com/en/workflows/asset-f82958bc
Author: AI Open Source