gleak

gleak: detecting leaked goroutines

gleak discovers all running goroutines and fails a test if any "leaked" — i.e. are still running after the test that aren't well-known framework/runtime goroutines and aren't on your ignore list. Docs: https://onsi.github.io/gomega/#gleak-finding-leaked-goroutines. Cross-refs: gomega:async, gomega:matchers.

gleak is an experimental Gomega package.

Import

import (
	. "github.com/onsi/gomega"
	"github.com/onsi/gomega/gleak" // often dot-imported too, for HaveLeaked/Goroutines/Ignoring*
)

The canonical pattern

Capture a baseline snapshot before the test; assert no leak after. The cleanup runs Eventually(Goroutines).ShouldNot(HaveLeaked(snapshot)):

BeforeEach(func() {
	goods := gleak.Goroutines()          // snapshot of "good" goroutines, taken now
	DeferCleanup(func() {
		Eventually(gleak.Goroutines).ShouldNot(gleak.HaveLeaked(goods))
	})
})

Equivalent BeforeEach/AfterEach form (carry the snapshot in a closure variable):

var goods []gleak.Goroutine
BeforeEach(func() { goods = gleak.Goroutines() })
AfterEach(func()  { Eventually(gleak.Goroutines).ShouldNot(gleak.HaveLeaked(goods)) })

Simplest possible form — no snapshot, relies only on the built-in well-known list:

AfterEach(func() {
	Eventually(gleak.Goroutines).ShouldNot(gleak.HaveLeaked())
})

Gotchas

ALWAYS use Eventually, never Expect. Goroutines wind down asynchronously; a synchronous Expect races their shutdown and produces false positives. Eventually re-polls until they terminate or it times out (default 1s / 10ms poll — see gomega:async to tune).

Pass Goroutines, not Goroutines(). Note the missing (). Eventually must call it repeatedly on each poll. Writing Eventually(gleak.Goroutines()) snapshots once and defeats the retry. (Calling gleak.Goroutines() with parens is correct only when taking a baseline snapshot to pass into HaveLeaked.)

Capture the baseline at the right time — in BeforeEach, before the test spins anything up, so genuinely pre-existing goroutines are filtered out.