Ginkgo — BDD Testing Framework for Go

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/