testenv

Documentation

Overview

Package testenv contains helper functions for skipping tests based on which tools are present in the environment.

Index

• Variables
• func Command(t testing.TB, name string, args ...string) *exec.Cmd
• func CommandContext(t testing.TB, ctx context.Context, name string, args ...string) *exec.Cmd
• func Deadline(t testing.TB) (time.Time, bool)
• func ExitIfSmallMachine()
• func GOROOT(t testing.TB) string
• func Go1Point() int
• func HasExec() bool
• func HasTool(tool string) error
• func NeedsExec(t testing.TB)
• func NeedsGo1Point(t testing.TB, x int)
• func NeedsGoBuild(t testing.TB)
• func NeedsGoExperiment(t testing.TB, flag string)
• func NeedsGoPackages(t testing.TB)
• func NeedsGoPackagesEnv(t testing.TB, env []string)
• func NeedsLocalXTools(t testing.TB)
• func NeedsLocalhostNet(t testing.TB)
• func NeedsTool(t testing.TB, tool string)
• func SkipAfterGo1Point(t testing.TB, x int)
• func WriteImportcfg(t testing.TB, dstPath string, additionalPackageFiles map[string]string)

Variables

var Sigquit = syscall.SIGQUIT

Sigquit is the signal to send to kill a hanging subprocess. Send SIGQUIT to get a stack trace.

Functions

func Command

func Command(t testing.TB, name string, args ...string) *exec.Cmd

Command is like exec.Command, but applies the same changes as testenv.CommandContext (with a default Context).

func CommandContext

func CommandContext(t testing.TB, ctx context.Context, name string, args ...string) *exec.Cmd

CommandContext is like exec.CommandContext, but:

• skips t if the platform does not support os/exec,
• if supported, sends SIGQUIT instead of SIGKILL in its Cancel function
• if the test has a deadline, adds a Context timeout and (if supported) WaitDelay for an arbitrary grace period before the test's deadline expires,
• if Cmd has the Cancel field, fails the test if the command is canceled due to the test's deadline, and
• sets a Cleanup function that verifies that the test did not leak a subprocess.

func Deadline

func Deadline(t testing.TB) (time.Time, bool)

Deadline returns the deadline of t, if known, using the Deadline method added in Go 1.15.

func ExitIfSmallMachine

func ExitIfSmallMachine()

ExitIfSmallMachine emits a helpful diagnostic and calls os.Exit(0) if the current machine is a builder known to have scarce resources.

It should be called from within a TestMain function.

func GOROOT

func GOROOT(t testing.TB) string

GOROOT reports the path to the directory containing the root of the Go project source tree. This is normally equivalent to runtime.GOROOT, but works even if the test binary was built with -trimpath.

If GOROOT cannot be found, GOROOT skips t if t is non-nil, or panics otherwise.

func Go1Point

func Go1Point() int

Go1Point returns the x in Go 1.x.

func HasExec

func HasExec() bool

HasExec reports whether the current system can start new processes using os.StartProcess or (more commonly) exec.Command.

func HasTool

func HasTool(tool string) error

HasTool reports an error if the required tool is not available in PATH.

For certain tools, it checks that the tool executable is correct.

func NeedsExec

func NeedsExec(t testing.TB)

NeedsExec checks that the current system can start new processes using os.StartProcess or (more commonly) exec.Command. If not, NeedsExec calls t.Skip with an explanation.

func NeedsGo1Point

func NeedsGo1Point(t testing.TB, x int)

NeedsGo1Point skips t if the Go version used to run the test is older than 1.x.

func NeedsGoBuild

func NeedsGoBuild(t testing.TB)

NeedsGoBuild skips t if the current system can't build programs with “go build” and then run them with os.StartProcess or exec.Command. Android doesn't have the userspace go build needs to run, and js/wasm doesn't support running subprocesses.

func NeedsGoExperiment

func NeedsGoExperiment(t testing.TB, flag string)

NeedsGoExperiment skips t if the current process environment does not have a GOEXPERIMENT flag set.

func NeedsGoPackages

func NeedsGoPackages(t testing.TB)

NeedsGoPackages skips t if the go/packages driver (or 'go' tool) implied by the current process environment is not present in the path.

func NeedsGoPackagesEnv

func NeedsGoPackagesEnv(t testing.TB, env []string)

NeedsGoPackagesEnv skips t if the go/packages driver (or 'go' tool) implied by env is not present in the path.

func NeedsLocalXTools

func NeedsLocalXTools(t testing.TB)

NeedsLocalXTools skips t if the golang.org/x/tools module is replaced and its replacement directory does not exist (or does not contain the module).

func NeedsLocalhostNet

func NeedsLocalhostNet(t testing.TB)

NeedsLocalhostNet skips t if networking does not work for ports opened with "localhost".

func NeedsTool

func NeedsTool(t testing.TB, tool string)

NeedsTool skips t if the named tool is not present in the path. As a special case, "cgo" means "go" is present and can compile cgo programs.

func SkipAfterGo1Point

func SkipAfterGo1Point(t testing.TB, x int)

SkipAfterGo1Point skips t if the Go version used to run the test is newer than 1.x.

func WriteImportcfg

func WriteImportcfg(t testing.TB, dstPath string, additionalPackageFiles map[string]string)

WriteImportcfg writes an importcfg file used by the compiler or linker to dstPath containing entries for the packages in std and cmd in addition to the package to package file mappings in additionalPackageFiles.