README

goleak GoDoc Build Status Coverage Status

Goroutine leak detector to help avoid Goroutine leaks.

Installation

You can use go get to get the latest version:

go get -u go.uber.org/goleak

goleak also supports semver releases. It is compatible with Go 1.5+.

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 "\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

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func Find

    func Find(options ...Option) error

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

      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)
        

        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 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., go.uber.org/goleak.IgnoreTopFunction

                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.

                    Directories

                    Path Synopsis
                    internal