goleak

README

goleak

Goroutine leak detector to help avoid Goroutine leaks.

Installation

You can use go get to get the latest version:

go get -u github.com/tarunKoyalwar/goleak

goleak also supports semver releases.

Note that go-leak only supports the two most recent minor versions of Go.

Quick Start

To verify that there are no unexpected goroutines running at the end of a test:

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

	// test logic here.
}

Instead of checking for leaks at the end of every test, goleak can also be run at the end of every test package by creating a TestMain function for your package:

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

Determine Source of Package Leaks

When verifying leaks using TestMain, the leak test is only run once after all tests have been run. This is typically enough to ensure there's no goroutines leaked from tests, but when there are leaks, it's hard to determine which test is causing them.

You can use the following bash script to determine the source of the failing test:

# 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

This will only print names of failing tests which can be investigated individually. E.g.,

.....
TestLeakyTest failed
.......

Stability

goleak is v1 and follows SemVer strictly.

No breaking changes will be made to exported APIs before 2.0.

Documentation

Overview

Package goleak is a Goroutine leak detector.

Index

• func Find(options ...Option) error
• func FindAndPrettyPrint(options ...Option) error
• func VerifyNone(t TestingT, options ...Option)
• func VerifyTestMain(m TestingM, options ...Option)
• type Option
  • func Cleanup(cleanupFunc func(exitCode int)) Option
  • func IgnoreAnyContainingPkg(pkg string) Option
  • func IgnoreAnyContainingStruct(str string) Option
  • func IgnoreAnyFunction(f string) Option
  • func IgnoreCurrent() Option
  • func IgnoreTopFunction(f string) Option
  • func IncludeAllContainingPkg(pkg string) Option
  • func Pretty() Option
• type TestingM
• type TestingT

Functions

func Find

func Find(options ...Option) error

Find looks for extra goroutines, and returns a descriptive error if any are found.

func FindAndPrettyPrint

func FindAndPrettyPrint(options ...Option) error

FindAndPrettyPrint looks for extra goroutines, and returns a descriptive error if any are found. It will also print a pretty graph of the goroutines.

func VerifyNone

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

VerifyNone marks the given TestingT as failed if any extra goroutines are found by Find. This is a helper method to make it easier to integrate in tests by doing:

defer VerifyNone(t)

VerifyNone is currently incompatible with t.Parallel because it cannot associate specific goroutines with specific tests. Thus, non-leaking goroutines from other tests running in parallel could fail this check. If you need to run tests in parallel, use VerifyTestMain instead, which will verify that no leaking goroutines exist after ALL tests finish.

func VerifyTestMain

func VerifyTestMain(m TestingM, options ...Option)

VerifyTestMain can be used in a TestMain function for package tests to verify that there were no goroutine leaks. To use it, your TestMain function should look like:

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

See https://golang.org/pkg/testing/#hdr-Main for more details.

This will run all tests as per normal, and if they were successful, look for any goroutine leaks and fail the tests if any leaks were found.

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option lets users specify custom verifications.

func Cleanup

func Cleanup(cleanupFunc func(exitCode int)) Option

Cleanup sets up a cleanup function that will be executed at the end of the leak check. When passed to VerifyTestMain, the exit code passed to cleanupFunc will be set to the exit code of TestMain. When passed to VerifyNone, the exit code will be set to 0. This cannot be passed to Find.

func IgnoreAnyContainingPkg

func IgnoreAnyContainingPkg(pkg string) Option

IgnoreAnyContainingPkg creates an option that filters out goroutines if any function in their stack trace includes the specified package name. The package name must be fully qualified, such as "github.com/tarunKoyalwar/goleak". Note: The package name does not require escaping in this context.

func IgnoreAnyContainingStruct

func IgnoreAnyContainingStruct(str string) Option

IgnoreAnyContainingStruct provides an option to filter out goroutines based on the presence of a specified struct in any function within their stack trace. The struct name must be fully qualified, such as "github.com/tarunKoyalwar/goleak.(*MyType)". Note: The struct name should be used as is without any need for escaping special characters.

func IgnoreAnyFunction

func IgnoreAnyFunction(f string) Option

IgnoreAnyFunction ignores goroutines where the specified function is present anywhere in the stack.

The function name must be fully qualified, e.g.,

github.com/tarunKoyalwar/goleak.IgnoreAnyFunction

For methods, the fully qualified form looks like:

github.com/tarunKoyalwar/goleak.(*MyType).MyMethod

func IgnoreCurrent

func IgnoreCurrent() Option

IgnoreCurrent records all current goroutines when the option is created, and ignores them in any future Find/Verify calls.

func IgnoreTopFunction

func IgnoreTopFunction(f string) Option

IgnoreTopFunction ignores any goroutines where the specified function is at the top of the stack. The function name should be fully qualified, e.g., github.com/tarunKoyalwar/goleak.IgnoreTopFunction

func IncludeAllContainingPkg

func IncludeAllContainingPkg(pkg string) Option

IncludeAllContainingPkg filters goroutines to only include those where any function contains the specified package name. This is useful for focusing on goroutines originating from specific packages, particularly in unit tests.

The package name must be fully qualified, e.g., "github.com/tarunKoyalwar/goleak".

Example use case: This function can be used to focus on goroutines that are relevant to the user's own packages, excluding those from third-party packages.

func Pretty

func Pretty() Option

Pretty sets the output of the leak check to be more human-readable.

type TestingM

type TestingM interface {
	Run() int
}

TestingM is the minimal subset of testing.M that we use.

type TestingT

type TestingT interface {
	Error(...interface{})
}

TestingT is the minimal subset of testing.TB that we use.