testenv.go

     1  // Copyright 2015 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package testenv provides information about what functionality
     6  // is available in different testing environments run by the Go team.
     7  //
     8  // It is an internal package because these details are specific
     9  // to the Go team's test setup (on build.golang.org) and not
    10  // fundamental to tests in general.
    11  package testenv
    12  
    13  import (
    14  	"bytes"
    15  	"errors"
    16  	"flag"
    17  	"fmt"
    18  	"internal/cfg"
    19  	"internal/goarch"
    20  	"internal/platform"
    21  	"os"
    22  	"os/exec"
    23  	"path/filepath"
    24  	"runtime"
    25  	"strconv"
    26  	"strings"
    27  	"sync"
    28  	"testing"
    29  )
    30  
    31  // Save the original environment during init for use in checks. A test
    32  // binary may modify its environment before calling HasExec to change its
    33  // behavior (such as mimicking a command-line tool), and that modified
    34  // environment might cause environment checks to behave erratically.
    35  var origEnv = os.Environ()
    36  
    37  // Builder reports the name of the builder running this test
    38  // (for example, "linux-amd64" or "windows-386-gce").
    39  // If the test is not running on the build infrastructure,
    40  // Builder returns the empty string.
    41  func Builder() string {
    42  	return os.Getenv("GO_BUILDER_NAME")
    43  }
    44  
    45  // HasGoBuild reports whether the current system can build programs with “go build”
    46  // and then run them with os.StartProcess or exec.Command.
    47  func HasGoBuild() bool {
    48  	if os.Getenv("GO_GCFLAGS") != "" {
    49  		// It's too much work to require every caller of the go command
    50  		// to pass along "-gcflags="+os.Getenv("GO_GCFLAGS").
    51  		// For now, if $GO_GCFLAGS is set, report that we simply can't
    52  		// run go build.
    53  		return false
    54  	}
    55  
    56  	return tryGoBuild() == nil
    57  }
    58  
    59  var tryGoBuild = sync.OnceValue(func() error {
    60  	// To run 'go build', we need to be able to exec a 'go' command.
    61  	// We somewhat arbitrarily choose to exec 'go tool -n compile' because that
    62  	// also confirms that cmd/go can find the compiler. (Before CL 472096,
    63  	// we sometimes ended up with cmd/go installed in the test environment
    64  	// without a cmd/compile it could use to actually build things.)
    65  	goTool, err := goTool()
    66  	if err != nil {
    67  		return err
    68  	}
    69  	cmd := exec.Command(goTool, "tool", "-n", "compile")
    70  	cmd.Env = origEnv
    71  	out, err := cmd.Output()
    72  	if err != nil {
    73  		return fmt.Errorf("%v: %w", cmd, err)
    74  	}
    75  	out = bytes.TrimSpace(out)
    76  	if len(out) == 0 {
    77  		return fmt.Errorf("%v: no tool reported", cmd)
    78  	}
    79  	if _, err := exec.LookPath(string(out)); err != nil {
    80  		return err
    81  	}
    82  
    83  	if platform.MustLinkExternal(runtime.GOOS, runtime.GOARCH, false) {
    84  		// We can assume that we always have a complete Go toolchain available.
    85  		// However, this platform requires a C linker to build even pure Go
    86  		// programs, including tests. Do we have one in the test environment?
    87  		// (On Android, for example, the device running the test might not have a
    88  		// C toolchain installed.)
    89  		//
    90  		// If CC is set explicitly, assume that we do. Otherwise, use 'go env CC'
    91  		// to determine which toolchain it would use by default.
    92  		if os.Getenv("CC") == "" {
    93  			cmd := exec.Command(goTool, "env", "CC")
    94  			cmd.Env = origEnv
    95  			out, err := cmd.Output()
    96  			if err != nil {
    97  				return fmt.Errorf("%v: %w", cmd, err)
    98  			}
    99  			out = bytes.TrimSpace(out)
   100  			if len(out) == 0 {
   101  				return fmt.Errorf("%v: no CC reported", cmd)
   102  			}
   103  			_, err = exec.LookPath(string(out))
   104  			return err
   105  		}
   106  	}
   107  	return nil
   108  })
   109  
   110  // MustHaveGoBuild checks that the current system can build programs with “go build”
   111  // and then run them with os.StartProcess or exec.Command.
   112  // If not, MustHaveGoBuild calls t.Skip with an explanation.
   113  func MustHaveGoBuild(t testing.TB) {
   114  	if os.Getenv("GO_GCFLAGS") != "" {
   115  		t.Helper()
   116  		t.Skipf("skipping test: 'go build' not compatible with setting $GO_GCFLAGS")
   117  	}
   118  	if !HasGoBuild() {
   119  		t.Helper()
   120  		t.Skipf("skipping test: 'go build' unavailable: %v", tryGoBuild())
   121  	}
   122  }
   123  
   124  // HasGoRun reports whether the current system can run programs with “go run”.
   125  func HasGoRun() bool {
   126  	// For now, having go run and having go build are the same.
   127  	return HasGoBuild()
   128  }
   129  
   130  // MustHaveGoRun checks that the current system can run programs with “go run”.
   131  // If not, MustHaveGoRun calls t.Skip with an explanation.
   132  func MustHaveGoRun(t testing.TB) {
   133  	if !HasGoRun() {
   134  		t.Helper()
   135  		t.Skipf("skipping test: 'go run' not available on %s/%s", runtime.GOOS, runtime.GOARCH)
   136  	}
   137  }
   138  
   139  // HasParallelism reports whether the current system can execute multiple
   140  // threads in parallel.
   141  // There is a copy of this function in cmd/dist/test.go.
   142  func HasParallelism() bool {
   143  	switch runtime.GOOS {
   144  	case "js", "wasip1":
   145  		return false
   146  	}
   147  	return true
   148  }
   149  
   150  // MustHaveParallelism checks that the current system can execute multiple
   151  // threads in parallel. If not, MustHaveParallelism calls t.Skip with an explanation.
   152  func MustHaveParallelism(t testing.TB) {
   153  	if !HasParallelism() {
   154  		t.Helper()
   155  		t.Skipf("skipping test: no parallelism available on %s/%s", runtime.GOOS, runtime.GOARCH)
   156  	}
   157  }
   158  
   159  // GoToolPath reports the path to the Go tool.
   160  // It is a convenience wrapper around GoTool.
   161  // If the tool is unavailable GoToolPath calls t.Skip.
   162  // If the tool should be available and isn't, GoToolPath calls t.Fatal.
   163  func GoToolPath(t testing.TB) string {
   164  	MustHaveGoBuild(t)
   165  	path, err := GoTool()
   166  	if err != nil {
   167  		t.Fatal(err)
   168  	}
   169  	// Add all environment variables that affect the Go command to test metadata.
   170  	// Cached test results will be invalidate when these variables change.
   171  	// See golang.org/issue/32285.
   172  	for _, envVar := range strings.Fields(cfg.KnownEnv) {
   173  		os.Getenv(envVar)
   174  	}
   175  	return path
   176  }
   177  
   178  var findGOROOT = sync.OnceValues(func() (path string, err error) {
   179  	if path := runtime.GOROOT(); path != "" {
   180  		// If runtime.GOROOT() is non-empty, assume that it is valid.
   181  		//
   182  		// (It might not be: for example, the user may have explicitly set GOROOT
   183  		// to the wrong directory. But this case is
   184  		// rare, and if that happens the user can fix what they broke.)
   185  		return path, nil
   186  	}
   187  
   188  	// runtime.GOROOT doesn't know where GOROOT is (perhaps because the test
   189  	// binary was built with -trimpath).
   190  	//
   191  	// Since this is internal/testenv, we can cheat and assume that the caller
   192  	// is a test of some package in a subdirectory of GOROOT/src. ('go test'
   193  	// runs the test in the directory containing the packaged under test.) That
   194  	// means that if we start walking up the tree, we should eventually find
   195  	// GOROOT/src/go.mod, and we can report the parent directory of that.
   196  	//
   197  	// Notably, this works even if we can't run 'go env GOROOT' as a
   198  	// subprocess.
   199  
   200  	cwd, err := os.Getwd()
   201  	if err != nil {
   202  		return "", fmt.Errorf("finding GOROOT: %w", err)
   203  	}
   204  
   205  	dir := cwd
   206  	for {
   207  		parent := filepath.Dir(dir)
   208  		if parent == dir {
   209  			// dir is either "." or only a volume name.
   210  			return "", fmt.Errorf("failed to locate GOROOT/src in any parent directory")
   211  		}
   212  
   213  		if base := filepath.Base(dir); base != "src" {
   214  			dir = parent
   215  			continue // dir cannot be GOROOT/src if it doesn't end in "src".
   216  		}
   217  
   218  		b, err := os.ReadFile(filepath.Join(dir, "go.mod"))
   219  		if err != nil {
   220  			if os.IsNotExist(err) {
   221  				dir = parent
   222  				continue
   223  			}
   224  			return "", fmt.Errorf("finding GOROOT: %w", err)
   225  		}
   226  		goMod := string(b)
   227  
   228  		for goMod != "" {
   229  			var line string
   230  			line, goMod, _ = strings.Cut(goMod, "\n")
   231  			fields := strings.Fields(line)
   232  			if len(fields) >= 2 && fields[0] == "module" && fields[1] == "std" {
   233  				// Found "module std", which is the module declaration in GOROOT/src!
   234  				return parent, nil
   235  			}
   236  		}
   237  	}
   238  })
   239  
   240  // GOROOT reports the path to the directory containing the root of the Go
   241  // project source tree. This is normally equivalent to runtime.GOROOT, but
   242  // works even if the test binary was built with -trimpath and cannot exec
   243  // 'go env GOROOT'.
   244  //
   245  // If GOROOT cannot be found, GOROOT skips t if t is non-nil,
   246  // or panics otherwise.
   247  func GOROOT(t testing.TB) string {
   248  	path, err := findGOROOT()
   249  	if err != nil {
   250  		if t == nil {
   251  			panic(err)
   252  		}
   253  		t.Helper()
   254  		t.Skip(err)
   255  	}
   256  	return path
   257  }
   258  
   259  // GoTool reports the path to the Go tool.
   260  func GoTool() (string, error) {
   261  	if !HasGoBuild() {
   262  		return "", errors.New("platform cannot run go tool")
   263  	}
   264  	return goTool()
   265  }
   266  
   267  var goTool = sync.OnceValues(func() (string, error) {
   268  	return exec.LookPath("go")
   269  })
   270  
   271  // MustHaveSource checks that the entire source tree is available under GOROOT.
   272  // If not, it calls t.Skip with an explanation.
   273  func MustHaveSource(t testing.TB) {
   274  	switch runtime.GOOS {
   275  	case "ios":
   276  		t.Helper()
   277  		t.Skip("skipping test: no source tree on " + runtime.GOOS)
   278  	}
   279  }
   280  
   281  // HasExternalNetwork reports whether the current system can use
   282  // external (non-localhost) networks.
   283  func HasExternalNetwork() bool {
   284  	return !testing.Short() && runtime.GOOS != "js" && runtime.GOOS != "wasip1"
   285  }
   286  
   287  // MustHaveExternalNetwork checks that the current system can use
   288  // external (non-localhost) networks.
   289  // If not, MustHaveExternalNetwork calls t.Skip with an explanation.
   290  func MustHaveExternalNetwork(t testing.TB) {
   291  	if runtime.GOOS == "js" || runtime.GOOS == "wasip1" {
   292  		t.Helper()
   293  		t.Skipf("skipping test: no external network on %s", runtime.GOOS)
   294  	}
   295  	if testing.Short() {
   296  		t.Helper()
   297  		t.Skipf("skipping test: no external network in -short mode")
   298  	}
   299  }
   300  
   301  // HasCGO reports whether the current system can use cgo.
   302  func HasCGO() bool {
   303  	return hasCgo()
   304  }
   305  
   306  var hasCgo = sync.OnceValue(func() bool {
   307  	goTool, err := goTool()
   308  	if err != nil {
   309  		return false
   310  	}
   311  	cmd := exec.Command(goTool, "env", "CGO_ENABLED")
   312  	cmd.Env = origEnv
   313  	out, err := cmd.Output()
   314  	if err != nil {
   315  		panic(fmt.Sprintf("%v: %v", cmd, out))
   316  	}
   317  	ok, err := strconv.ParseBool(string(bytes.TrimSpace(out)))
   318  	if err != nil {
   319  		panic(fmt.Sprintf("%v: non-boolean output %q", cmd, out))
   320  	}
   321  	return ok
   322  })
   323  
   324  // MustHaveCGO calls t.Skip if cgo is not available.
   325  func MustHaveCGO(t testing.TB) {
   326  	if !HasCGO() {
   327  		t.Helper()
   328  		t.Skipf("skipping test: no cgo")
   329  	}
   330  }
   331  
   332  // CanInternalLink reports whether the current system can link programs with
   333  // internal linking.
   334  func CanInternalLink(withCgo bool) bool {
   335  	return !platform.MustLinkExternal(runtime.GOOS, runtime.GOARCH, withCgo)
   336  }
   337  
   338  // MustInternalLink checks that the current system can link programs with internal
   339  // linking.
   340  // If not, MustInternalLink calls t.Skip with an explanation.
   341  func MustInternalLink(t testing.TB, withCgo bool) {
   342  	if !CanInternalLink(withCgo) {
   343  		t.Helper()
   344  		if withCgo && CanInternalLink(false) {
   345  			t.Skipf("skipping test: internal linking on %s/%s is not supported with cgo", runtime.GOOS, runtime.GOARCH)
   346  		}
   347  		t.Skipf("skipping test: internal linking on %s/%s is not supported", runtime.GOOS, runtime.GOARCH)
   348  	}
   349  }
   350  
   351  // MustInternalLinkPIE checks whether the current system can link PIE binary using
   352  // internal linking.
   353  // If not, MustInternalLinkPIE calls t.Skip with an explanation.
   354  func MustInternalLinkPIE(t testing.TB) {
   355  	if !platform.InternalLinkPIESupported(runtime.GOOS, runtime.GOARCH) {
   356  		t.Helper()
   357  		t.Skipf("skipping test: internal linking for buildmode=pie on %s/%s is not supported", runtime.GOOS, runtime.GOARCH)
   358  	}
   359  }
   360  
   361  // MustHaveBuildMode reports whether the current system can build programs in
   362  // the given build mode.
   363  // If not, MustHaveBuildMode calls t.Skip with an explanation.
   364  func MustHaveBuildMode(t testing.TB, buildmode string) {
   365  	if !platform.BuildModeSupported(runtime.Compiler, buildmode, runtime.GOOS, runtime.GOARCH) {
   366  		t.Helper()
   367  		t.Skipf("skipping test: build mode %s on %s/%s is not supported by the %s compiler", buildmode, runtime.GOOS, runtime.GOARCH, runtime.Compiler)
   368  	}
   369  }
   370  
   371  // HasSymlink reports whether the current system can use os.Symlink.
   372  func HasSymlink() bool {
   373  	ok, _ := hasSymlink()
   374  	return ok
   375  }
   376  
   377  // MustHaveSymlink reports whether the current system can use os.Symlink.
   378  // If not, MustHaveSymlink calls t.Skip with an explanation.
   379  func MustHaveSymlink(t testing.TB) {
   380  	ok, reason := hasSymlink()
   381  	if !ok {
   382  		t.Helper()
   383  		t.Skipf("skipping test: cannot make symlinks on %s/%s: %s", runtime.GOOS, runtime.GOARCH, reason)
   384  	}
   385  }
   386  
   387  // HasLink reports whether the current system can use os.Link.
   388  func HasLink() bool {
   389  	// From Android release M (Marshmallow), hard linking files is blocked
   390  	// and an attempt to call link() on a file will return EACCES.
   391  	// - https://code.google.com/p/android-developer-preview/issues/detail?id=3150
   392  	return runtime.GOOS != "plan9" && runtime.GOOS != "android"
   393  }
   394  
   395  // MustHaveLink reports whether the current system can use os.Link.
   396  // If not, MustHaveLink calls t.Skip with an explanation.
   397  func MustHaveLink(t testing.TB) {
   398  	if !HasLink() {
   399  		t.Helper()
   400  		t.Skipf("skipping test: hardlinks are not supported on %s/%s", runtime.GOOS, runtime.GOARCH)
   401  	}
   402  }
   403  
   404  var flaky = flag.Bool("flaky", false, "run known-flaky tests too")
   405  
   406  func SkipFlaky(t testing.TB, issue int) {
   407  	if !*flaky {
   408  		t.Helper()
   409  		t.Skipf("skipping known flaky test without the -flaky flag; see golang.org/issue/%d", issue)
   410  	}
   411  }
   412  
   413  func SkipFlakyNet(t testing.TB) {
   414  	if v, _ := strconv.ParseBool(os.Getenv("GO_BUILDER_FLAKY_NET")); v {
   415  		t.Helper()
   416  		t.Skip("skipping test on builder known to have frequent network failures")
   417  	}
   418  }
   419  
   420  // CPUIsSlow reports whether the CPU running the test is suspected to be slow.
   421  func CPUIsSlow() bool {
   422  	switch runtime.GOARCH {
   423  	case "arm", "mips", "mipsle", "mips64", "mips64le", "wasm":
   424  		return true
   425  	}
   426  	return false
   427  }
   428  
   429  // SkipIfShortAndSlow skips t if -short is set and the CPU running the test is
   430  // suspected to be slow.
   431  //
   432  // (This is useful for CPU-intensive tests that otherwise complete quickly.)
   433  func SkipIfShortAndSlow(t testing.TB) {
   434  	if testing.Short() && CPUIsSlow() {
   435  		t.Helper()
   436  		t.Skipf("skipping test in -short mode on %s", runtime.GOARCH)
   437  	}
   438  }
   439  
   440  // SkipIfOptimizationOff skips t if optimization is disabled.
   441  func SkipIfOptimizationOff(t testing.TB) {
   442  	if OptimizationOff() {
   443  		t.Helper()
   444  		t.Skip("skipping test with optimization disabled")
   445  	}
   446  }
   447  
   448  // WriteImportcfg writes an importcfg file used by the compiler or linker to
   449  // dstPath containing entries for the file mappings in packageFiles, as well
   450  // as for the packages transitively imported by the package(s) in pkgs.
   451  //
   452  // pkgs may include any package pattern that is valid to pass to 'go list',
   453  // so it may also be a list of Go source files all in the same directory.
   454  func WriteImportcfg(t testing.TB, dstPath string, packageFiles map[string]string, pkgs ...string) {
   455  	t.Helper()
   456  
   457  	icfg := new(bytes.Buffer)
   458  	icfg.WriteString("# import config\n")
   459  	for k, v := range packageFiles {
   460  		fmt.Fprintf(icfg, "packagefile %s=%s\n", k, v)
   461  	}
   462  
   463  	if len(pkgs) > 0 {
   464  		// Use 'go list' to resolve any missing packages and rewrite the import map.
   465  		cmd := Command(t, GoToolPath(t), "list", "-export", "-deps", "-f", `{{if ne .ImportPath "command-line-arguments"}}{{if .Export}}{{.ImportPath}}={{.Export}}{{end}}{{end}}`)
   466  		cmd.Args = append(cmd.Args, pkgs...)
   467  		cmd.Stderr = new(strings.Builder)
   468  		out, err := cmd.Output()
   469  		if err != nil {
   470  			t.Fatalf("%v: %v\n%s", cmd, err, cmd.Stderr)
   471  		}
   472  
   473  		for _, line := range strings.Split(string(out), "\n") {
   474  			if line == "" {
   475  				continue
   476  			}
   477  			importPath, export, ok := strings.Cut(line, "=")
   478  			if !ok {
   479  				t.Fatalf("invalid line in output from %v:\n%s", cmd, line)
   480  			}
   481  			if packageFiles[importPath] == "" {
   482  				fmt.Fprintf(icfg, "packagefile %s=%s\n", importPath, export)
   483  			}
   484  		}
   485  	}
   486  
   487  	if err := os.WriteFile(dstPath, icfg.Bytes(), 0666); err != nil {
   488  		t.Fatal(err)
   489  	}
   490  }
   491  
   492  // SyscallIsNotSupported reports whether err may indicate that a system call is
   493  // not supported by the current platform or execution environment.
   494  func SyscallIsNotSupported(err error) bool {
   495  	return syscallIsNotSupported(err)
   496  }
   497  
   498  // ParallelOn64Bit calls t.Parallel() unless there is a case that cannot be parallel.
   499  // This function should be used when it is necessary to avoid t.Parallel on
   500  // 32-bit machines, typically because the test uses lots of memory.
   501  func ParallelOn64Bit(t *testing.T) {
   502  	if goarch.PtrSize == 4 {
   503  		return
   504  	}
   505  	t.Parallel()
   506  }
   507
View as plain text