Documentation
¶
Overview ¶
Package testenv checks host capabilities a test needs, so a test runs wherever the host provides them and says why it skipped where the host does not. Only test code imports this package.
Index ¶
- Constants
- func Bash(t testing.TB) string
- func BashExecutionStringProbe(t testing.TB) (probe, stderr string)
- func BashStderr(t testing.TB, stderr string) string
- func DeletedWorkingDirectory(t *testing.T)
- func ExpectCompiles(t testing.TB, name string, imports map[string]string, body string)
- func ExpectTypeError(t testing.TB, name string, imports map[string]string, body string)
- func GrantOthersRead(t testing.TB, path string)
- func InheritOthersRead(testing.TB, string)
- func KeepGoBuildCaches() error
- func ReadOnlyDir(t testing.TB, dir string)
- func ReportEnvironIfRequested()
- func ReportStartupIfRequested()
- func RequireDirectoryLink(t testing.TB, oldname, newname string)
- func RequireLiveEnv(t testing.TB, names ...string) string
- func RequireScopedTempDir(t testing.TB, prefix string)
- func RequireSymlink(t testing.TB, oldname, newname string)
- func RunScoped(m *testing.M, prefix string) int
- func RunUnprivileged(t *testing.T) bool
- func ScopeTempDir(root string) error
- func ScriptCommand(t testing.TB, path string, args ...string) *exec.Cmd
- func Sh(t testing.TB) string
- func ShebangInterpreter(t testing.TB, path string) string
- func ShortTempDir(t testing.TB, prefix string) string
- func Symlink(t testing.TB, oldname, newname string)
- func TypeErrors(t testing.TB, imports map[string]string, body string) []string
- func VerbatimArgs(*exec.Cmd)
Constants ¶
const EnvironHelper = "PIG_TEST_ENVIRON_HELPER"
EnvironHelper is the environment variable that makes a test binary whose TestMain calls ReportEnvironIfRequested report its environment.
Variables ¶
This section is empty.
Functions ¶
func Bash ¶
Bash returns the bash that runs repository scripts, and skips the test when the host has none. On Windows it is Git for Windows' bash: bash.exe on PATH is usually the WSL launcher, which runs the script inside a Linux distribution without the host's toolchains or files.
func BashExecutionStringProbe ¶
BashExecutionStringProbe writes a BASH_ENV script for a test that compares the -c command bash receives from Pi and from PiG. The script sends bash's stderr to the returned file, then prints BASH_EXECUTION_STRING, the -c argument as bash received it, as "<%s>\n". Pi and PiG merge a child's stdout and stderr pipes into one stream whose interleaving differs from run to run; with stderr in the file, that stream holds stdout in the order bash wrote it, and BashStderr reads stderr after each command.
func BashStderr ¶
BashStderr returns what the last bash that sourced a BashExecutionStringProbe script wrote to stderr.
func DeletedWorkingDirectory ¶
DeletedWorkingDirectory makes the process working directory unreadable, as libuv reports for a removed directory: os.Getwd fails with a not-exist error and Node's process.cwd() throws ENOENT. It restores the previous directory when the test ends. The test must not run in parallel.
func ExpectCompiles ¶
ExpectCompiles fails the test when the snippet has a type error.
func ExpectTypeError ¶
ExpectTypeError fails the test when the snippet compiles: upstream's @ts-expect-error.
func GrantOthersRead ¶
GrantOthersRead lets principals other than the owner read the file at path (mode 0644), so an owner-only check must refuse it.
func InheritOthersRead ¶
InheritOthersRead is a no-op on POSIX: a new file's mode is set when it is created, so the directory cannot grant access to it beforehand.
func KeepGoBuildCaches ¶
func KeepGoBuildCaches() error
KeepGoBuildCaches sets GOCACHE and GOMODCACHE to the directories the go command resolves for the current environment unless the caller already set them. The go command derives both from HOME, so a test that later replaces HOME would otherwise make every child `go build` start from empty caches: the whole module graph recompiles, and that costs minutes of CPU per build. A package's TestMain reaches it through ScopeTempDir, before any test changes HOME. A package without a go command on PATH keeps its environment unchanged.
func ReadOnlyDir ¶
ReadOnlyDir lets the current user list and traverse dir but not add or remove its entries (mode 0555) until the test ends. The test must start with RunUnprivileged, because root ignores permission bits.
func ReportEnvironIfRequested ¶
func ReportEnvironIfRequested()
ReportEnvironIfRequested writes os.Environ, in the order of the process's environment block, to stdout as a JSON array and exits when EnvironHelper is "1". A TestMain calls it first, so the test binary can stand in for a spawned program.
func ReportStartupIfRequested ¶
func ReportStartupIfRequested()
ReportStartupIfRequested does nothing outside Windows, where a process has no STARTUPINFO to report.
func RequireDirectoryLink ¶
RequireDirectoryLink creates newname as a required link to the directory oldname. On Windows it creates a privilege-free drive-target junction, which Node and this module report as a symbolic link; a volume-GUID target creates a volume mount point instead. Elsewhere it creates a symbolic link. Any failure fails the test.
func RequireLiveEnv ¶
RequireLiveEnv skips a live test when any named variable is unset or empty. It reports only missing names, never values, and returns the first value when every requirement is present. With no names it returns an empty string.
func RequireScopedTempDir ¶
RequireScopedTempDir fails the test unless the process temporary directory is the one this package's TestMain scoped, named prefix+random. It guards the TestMain wiring: without it, extension hosts and helpers write pig-ext-*.log and pig-packed-*.log files, and other scratch directories, straight into the shared temporary directory, where nothing removes them.
func RequireSymlink ¶
RequireSymlink creates a required fixture link. Missing privileges fail the test instead of removing its parity obligation.
func RunScoped ¶
RunScoped runs m with the process temporary directory scoped to a fresh directory named prefix+random under the real one, removes that directory afterwards, and returns the exit code for os.Exit. Removal failure turns a passing run into exit code 2 so a leak fails the package.
func RunUnprivileged ¶
RunUnprivileged makes the calling test run without root's permission bypass. When the process is root, it reruns only the calling test in a child process as the unprivileged "nobody" user, fails with the child's output unless the child passed, and returns true; the caller then returns without repeating the test. Otherwise it returns false and the test continues in this process. Call it before any other setup. The rerun has a fresh HOME and TMPDIR and cannot read package-relative files.
func ScopeTempDir ¶
ScopeTempDir makes root the process temporary directory for a test binary and every process it starts: TMPDIR on Unix, TMP and TEMP on Windows. A package's TestMain calls it with the directory it removes after m.Run, so a temporary file or directory created through os.TempDir, os.CreateTemp("", ...), or a child's tmpdir() stays inside that root and is removed with it, whichever test or helper created it and whatever it forgot to remove. Extension hosts create their stderr logs this way (pig-ext-*.log and pig-packed-*.log) and keep the log of a crashed extension by design.
It also pins GOCACHE and GOMODCACHE (KeepGoBuildCaches), so a test that points HOME at a temporary directory and then runs `go build` links from the compiled packages a user's builds share instead of recompiling PiG and its dependencies in an empty cache.
func ScriptCommand ¶
ScriptCommand returns a command that runs the repository script at path with args. A POSIX host runs the script directly. Windows cannot run a script by its #! line, so there the command names the interpreter that line selects: bash or sh through Bash or Sh, and python3 or node as found on PATH. A script with any other interpreter skips the test on Windows.
func ShebangInterpreter ¶
ShebangInterpreter is the program a script's #! line runs, with /usr/bin/env and the directory removed: "#!/usr/bin/env python3" is python3.
func ShortTempDir ¶
ShortTempDir creates a directory for the test whose path leaves room for Unix-domain socket names below it: sun_path holds 104 bytes on macOS and 108 on Linux and Windows, and t.TempDir's name holds the test's name. It is in /tmp outside Windows, since macOS's TMPDIR is long. On Windows it is in os.TempDir, or in %LOCALAPPDATA%\pig\s, the directory the extension Host falls back to, when os.TempDir is too long to leave that room. Its name starts with prefix. Cleanup removes it. On Windows the removal retries for two seconds while another process still holds a file, as t.TempDir's cleanup does.
func Symlink ¶
Symlink creates newname as a symbolic link to oldname. When the host does not let this process create symbolic links (Windows without Developer Mode or elevation), the test is skipped; any other error fails it. Use it for file links, and RequireDirectoryLink for a directory link.
func TypeErrors ¶
TypeErrors type-checks body, the statements of a function, in a file that imports each package of imports (alias to import path) as built, and returns the type errors. Go reports a variable no statement reads and an import no statement uses as errors; a snippet declares values to test their types, so those errors are dropped.
func VerbatimArgs ¶
VerbatimArgs is a no-op: a POSIX exec passes argv without a command line.
Types ¶
This section is empty.