uber-go/goleak

When using goleak.VerifyTestMain, leaks are only reported once after all tests have finished, making it difficult to identify the specific failing test. You can use the following bash script to run each test individually and identify which one causes the leak:

1. Compile the tests into a binary.
2. Iterate through all tests (including Examples) and run them one by one using the binary, printing a . for success and the test name for failure.

# Create a test binary which will be used to run each test individually
$ go test -c -o tests

# Run each test individually, printing "." for successful tests, or the test name
# for failing tests.
$ for test in $(go test -list . | grep -E "^(Test|Example)"); do ./tests -test.run "^$test$" &>/dev/null && echo -n "." || echo -e "\n$test failed"; done

Install the latest version of goleak using go get. Note that goleak only supports the two most recent minor versions of Go.

go get -u go.uber.org/goleak

To check for leaks at the end of every test in a package rather than per test, implement a TestMain function and call goleak.VerifyTestMain(m). This is the recommended approach for packages that use t.Parallel().

func TestMain(m *testing.M) {
	goleak.VerifyTestMain(m)
}

To check for unexpected goroutines at the end of an individual test, use goleak.VerifyNone(t) within a defer statement.

Warning: goleak cannot distinguish between a leaky goroutine and a test that is still running when using t.Parallel(). If your tests use t.Parallel(), use goleak.VerifyTestMain instead.

func TestA(t *testing.T) {
	defer goleak.VerifyNone(t)

	// test logic here.
}

Use IgnoreTopFunction to ignore any goroutines where a specific function is at the top of the stack. The function name must be fully qualified.

Example: go.uber.org/goleak.IgnoreTopFunction

Use Cleanup to provide a function that executes at the end of the leak check.

• When passed to VerifyTestMain, the exitCode passed to the cleanup function will be the exit code of TestMain.
• When passed to VerifyNone, the exitCode will be 0.
• Note: This option cannot be passed to Find.

The Find function searches for unexpected goroutines. If any extra goroutines are found, it returns a descriptive error containing the stack traces of the leaked goroutines. You can pass optional Option arguments to customize the search behavior.

Note: Certain options like Cleanup and RunOnFailure are restricted and cannot be used with Find (they are intended for VerifyNone or VerifyTestMain respectively).

Use VerifyTestMain within a TestMain function to ensure that no goroutine leaks occur across your entire package's test suite.

VerifyTestMain executes all tests in the package via m.Run(). If the tests pass, it then checks for goroutine leaks. If leaks are detected, it will report the error to stderr and fail the test run (by exiting with a non-zero code).

To use it, implement a TestMain function in your test files that calls goleak.VerifyTestMain(m).

func TestMain(m *testing.M) {
	goleak.VerifyTestMain(m)
}

The VerifyNone function is a helper designed for easy integration into Go tests. It marks the provided TestingT (typically *testing.T) as failed if any extra goroutines are detected.

Common usage pattern:

defer goleak.VerifyNone(t)

Limitations: VerifyNone is incompatible with t.Parallel(). Because it cannot associate specific goroutines with specific tests, goroutines leaked by other tests running in parallel may cause this check to fail. If you need to run tests in parallel, use VerifyTestMain instead to verify that no leaking goroutines exist after all tests have finished.

func VerifyNone(t TestingT, options ...Option)

Use IgnoreCreatedBy to ignore any goroutines that were spawned from the specified function. The function name must be fully qualified.

Example: go.uber.org/goleak.IgnoreCreatedBy

Use IgnoreAnyFunction to ignore goroutines where a specific function is present anywhere in the stack. The function name must be fully qualified.

For methods, use the format: go.uber.org/goleak.(*MyType).MyMethod