parallelism

Running Ginkgo in parallel

Parallelism is where Ginkgo's "every spec is independent" assumption (ginkgo:overview) earns its keep. If your specs are independent, going parallel is one flag. If they aren't, parallelism is how you find out. Docs: https://onsi.github.io/ginkgo/#spec-parallelization, https://onsi.github.io/ginkgo/#patterns-for-parallel-integration-specs.

The flag

ginkgo -p            # auto-detect optimal process count from CPU cores
ginkgo --procs=4     # pin the count explicitly
ginkgo watch -p      # re-run in parallel on every file change

-p/--procs require the ginkgo CLI — go test cannot parallelize a Ginkgo suite (it has no server to coordinate processes). Most other features work under go test; parallelism is the headline exception. → ginkgo:running.

The mental model: separate processes, not goroutines

This is the one thing to internalize. Ginkgo compiles the suite once (go test -c), then launches N copies of the test binary as separate OS processes. Each process runs the full tree-construction phase independently (so all N build the identical spec list), then pulls specs to run from the CLI, which acts as a server and merges everything into one coherent output stream.

• Separate processes means separate memory. Each process has its own copy of every package-level var and closure variable. There is no shared memory, so shared-closure specs like var book don't race across processes — they each get their own book. (Within a process specs still run one at a time.)
• The flip side: a BeforeSuite runs on every process, so anything it creates is created N times.
• You usually don't care which process runs a spec — except for the integration patterns below, which deliberately shard shared external resources by process index.

What the N processes cost

Going parallel is cheap, but not free — and the cost is rarely where people look for it.

• Compilation is once per suite, not once per process. Ginkgo builds the test binary a single time and runs N copies of it; under -r the CLI also overlaps compiling the next suite with running the current one. It is usually not the bottleneck it's assumed to be.
• Teardown is once per process — but they overlap, so a suite pays roughly one process teardown, not N.
• Under --race that one teardown is ~1s. ThreadSanitizer sleeps for a second at process exit (atexit_sleep_ms, its default) so races reported by goroutines still running at exit aren't lost. Every process pays it however trivial the suite: a 2-spec package pays exactly what a 2000-spec package pays.