portpicker

Documentation

Overview

Package portpicker allows Go programs and tests to receive the best guess of an unused port that may be used for ad hoc purposes.

Index

• func PickUnusedPort() (port int, err error)
• func PickUnusedPortTB(tb TB) int
• func RecycleUnusedPort(port int) error
• type TB

Functions

func PickUnusedPort

func PickUnusedPort() (port int, err error)

PickUnusedPort returns a port number that is not currently bound. There is an inherent race condition between this function being called and any other process on the same computer, so the caller should bind to the port as soon as possible.

func PickUnusedPortTB

func PickUnusedPortTB(tb TB) int

PickUnusedPortTB is a package testing-aware variant of PickUnusedPort that treats provisioning errors as fatal and handles port releasing for the user.

func TestSmoke(t *testing.T) {
  backend := startTestBackendOnPort(portpicker.PickUnusedPortTB(t))

  // test backend
}

The returned port should NOT be manually returned with RecycleUnusedPort.

Caution

Port release failures do not result in test failures but leave error message in test logs. Investigate logs to ensure that your servers under test (SUT) terminate when the test is done.

func RecycleUnusedPort

func RecycleUnusedPort(port int) error

RecycleUnusedPort recycles a port obtained by PickUnusedPort after it is no longer needed.

Types

type TB

type TB interface {
	// Helper corresponds to (testing.TB).Helper.
	Helper()
	// Helper corresponds to (testing.TB).Cleanup.
	Cleanup(func())
	// Helper corresponds to (testing.TB).Fatalf.
	Fatalf(string, ...interface{})
	// Helper corresponds to (testing.TB).Logf.
	Logf(string, ...interface{})
}

TB is the minimal viable interface that captures testing.TB. It accepts implementations of

*testing.B
*testing.T

This interface is introduced for the sole reason that portpicker is not a testonly library, and we want to avoid having non-testing code suddenly depend on package testing. In short, per https://go-proverbs.github.io "A little bit of copying is better than a little dependency."