testenv

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 32 Imported by: 0

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

View Source
const EnvironHelper = "PIG_TEST_ENVIRON_HELPER"

EnvironHelper is the environment variable that makes a test binary whose TestMain calls ReportEnvironIfRequested report its environment.

View Source
const TimingReportOnlyEnv = "PIG_PERF_TIMING_REPORT_ONLY"

TimingReportOnlyEnv names the environment variable that turns every TimingGate and TimingGateFatal into a report. Pull-request CI sets it to 1 on its shared runners; the dedicated release perf run (make test-timing) leaves it unset.

Variables

This section is empty.

Functions

func Bash

func Bash(t testing.TB) string

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

func BashExecutionStringProbe(t testing.TB) (probe, stderr string)

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

func BashStderr(t testing.TB, stderr string) string

BashStderr returns what the last bash that sourced a BashExecutionStringProbe script wrote to stderr.

func CombinedOutput

func CombinedOutput(t testing.TB, cmd *exec.Cmd) ([]byte, error)

CombinedOutput is exec.Cmd.CombinedOutput with the containment of Start.

func CopyFromFIFO

func CopyFromFIFO(t testing.TB, read func(fifo string) error, during func()) (payload []byte, err error)

CopyFromFIFO runs read, which copies the named pipe it is given to a file it has open for writing, and calls during while the copy is open and waiting for more data. It then ends the pipe, waits for read, and returns what read returned and the bytes it was fed. A test checks in during that the process starts no child while the destination is open (RequireForkLocked).

The pipe holds less than the payload, so the write to it returns only after the copy has read most of the payload; the copy is then inside its read, with its destination open.

func DeletedWorkingDirectory

func DeletedWorkingDirectory(t *testing.T)

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 DisableGoTelemetry

func DisableGoTelemetry(t testing.TB, home string)

DisableGoTelemetry turns the go command's telemetry off in the configuration directory of a test whose HOME is now home. Call it after setting HOME and before the test's first go command.

A fresh configuration directory has no telemetry mode, so the first go command in it finds telemetry on, claims the upload token, and forks a detached sidecar ("** telemetry **", working directory in that configuration directory). The sidecar outlives the command and creates counter and report files there. A test whose cleanup removes home then fails with "directory not empty" when the sidecar writes during RemoveAll, or leaves a recreated tree behind when it writes after. In mode off a go command opens no counters and forks nothing.

It writes only when the configuration directory lies inside home. Where XDG_CONFIG_HOME or APPDATA keeps it elsewhere the sidecar cannot write into home, and the mode of the user running `go test` must not change.

func ExpectCompiles

func ExpectCompiles(t testing.TB, name string, imports map[string]string, body string)

ExpectCompiles fails the test when the snippet has a type error.

func ExpectTypeError

func ExpectTypeError(t testing.TB, name string, imports map[string]string, body string)

ExpectTypeError fails the test when the snippet compiles: upstream's @ts-expect-error.

func GrantOthersRead

func GrantOthersRead(t testing.TB, path string)

GrantOthersRead lets principals other than the owner read the file at path (mode 0644), so an owner-only check must refuse it.

func InOwnProcess

func InOwnProcess(t *testing.T) bool

InOwnProcess reports whether the calling top-level test runs in a process of its own. Called in the package's test process, it runs the test again in a child (the same test binary, only that test, within the parent's deadline), fails if the child fails or does not run it, skips if the child skipped, and returns false.

A test that reads a process-wide runtime counter (runtime/metrics, runtime/trace) calls it first: in the package's process, goroutines that earlier tests left running create goroutines, wake up, allocate and collect during the measurement.

func InheritOthersRead

func InheritOthersRead(testing.TB, string)

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 IsolateAgentEnv

func IsolateAgentEnv(root string) error

IsolateAgentEnv points PIG_CODING_AGENT_DIR, PI_CODING_AGENT_DIR, PIG_HOME and PI_HOME at fresh directories under root and clears the session-directory overrides. A test binary calls it from TestMain through ScopeTempDir, before any test or child process reads the environment; a test that needs an unset variable clears it itself. Each directory is created empty. HOME stays unchanged: the Go, Node and Rust toolchains resolve their caches and shims from it.

func IsolateGit

func IsolateGit(t testing.TB)

IsolateGit points git at an empty configuration with a fixed identity and no prompts, for the test and the processes it starts.

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 LeakedGoroutines

func LeakedGoroutines() (int, string, error)

LeakedGoroutines runs Go's goroutineleak detection and returns the number of goroutines blocked forever on a channel, mutex or other primitive that no live goroutine can reach, with the profile text that names their stacks. The detection runs only while the profile is written: pprof.Profile.Count alone reports the result of the last write, so a check that reads Count without writing first passes whatever leaked.

func ModuleRoot

func ModuleRoot(t testing.TB) string

ModuleRoot is ModuleRootPath for a test; it fails the test on error.

func ModuleRootPath

func ModuleRootPath() (string, error)

ModuleRootPath returns the root of the module that contains the running test's package: the nearest directory at or above the package directory that holds a go.mod file.

func Output

func Output(t testing.TB, cmd *exec.Cmd) ([]byte, error)

Output is exec.Cmd.Output with the containment of Start.

func PackageDir

func PackageDir(t testing.TB) string

PackageDir is PackageDirPath for a test; it fails the test on error.

func PackageDirPath

func PackageDirPath() (string, error)

PackageDirPath returns the source directory of the package whose test binary is running. It does not use runtime.Caller: under -trimpath the file names it reports are module-relative import paths, not directories, and the build cache is only shared between checkouts when every build uses -trimpath.

func PhysicalPath

func PhysicalPath(path string) string

PhysicalPath resolves symlinks in path, or in its parent directory when path does not exist yet, so a path the test built and the working directory a process reports compare equal (macOS /var is /private/var).

func ReadOnlyDir

func ReadOnlyDir(t testing.TB, dir string)

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(t testing.TB, oldname, newname string)

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 RequireForkLocked

func RequireForkLocked(t testing.TB)

RequireForkLocked fails the test unless this process cannot start a child right now. Go forks under the write side of syscall.ForkLock, so a fork waits while any goroutine holds the lock for reading. Call it where a file is open for writing and this process will execute that file afterwards: a child forked then holds a copy of the descriptor until it calls exec, and the later exec fails with ETXTBSY. The test goroutine must be the only one forking, or a fork in progress satisfies the check.

func RequireIsolatedAgentEnv

func RequireIsolatedAgentEnv(t testing.TB)

RequireIsolatedAgentEnv fails the test unless every variable IsolateAgentEnv sets points under the process temporary directory this package's TestMain scoped. It guards the TestMain wiring: without it, a test that builds a default path (a session directory, trust file or credential store) writes the agent directory the user's shell exported.

func RequireLiveEnv

func RequireLiveEnv(t testing.TB, names ...string) string

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 RequireQualifiedNode

func RequireQualifiedNode(t testing.TB) string

RequireQualifiedNode returns the node on PATH once it is the release .node-version names. WHATWG URL parsing (ada) and ICU data change between Node releases, so an oracle that compares a Go port with Node's answers describes one release only: Node 22.19 and 24.19 reject an ASCII host with an "xn--" label that Node 24.22 and 26 accept. A different release fails the test with that explanation, where a comparison would report differences that are not port bugs.

func RequireScopedTempDir

func RequireScopedTempDir(t testing.TB, prefix string)

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(t testing.TB, oldname, newname string)

RequireSymlink creates a required fixture link. Missing privileges fail the test instead of removing its parity obligation.

func RerunWithoutAsyncPreemption

func RerunWithoutAsyncPreemption(t *testing.T) bool

RerunWithoutAsyncPreemption makes a test whose two ends of a FIFO are both blocking opens immune to macOS's signal-interrupted FIFO open. Call it first in such a test and return when it reports true.

On macOS a signal that ends a blocking open of a FIFO makes the kernel (fifo_open in XNU's bsd/miscfs/fifofs/fifo_vnops.c) leave through fifo_close_internal, which counts the opener out and shuts the FIFO's send (or receive) side while the other end, whose open completed because it saw the opener, goes on: its write fails with EPIPE (the bytes are lost) or its read returns end of file at once while the retried open waits for a counterpart that is gone. The Go runtime's SIGURG preemption signals reach such opens in a process whose goroutines are busy. The runtime sends none with GODEBUG=asyncpreemptoff=1, so on macOS this runs the test again in a child test binary with it set and reports the child's verdict: true means the child ran the test and the caller must return, false means the caller is the child, or the host is not macOS (no other kernel has the race) and the test runs where it is. A subtest is selected by its whole name. SIGCHLD from a child that exits while an open sleeps is not covered, so a test that starts a child must wait for it to exit before its next FIFO open (readFIFO in env does).

func Run

func Run(t testing.TB, cmd *exec.Cmd) error

Run starts cmd and waits for it.

func RunGit

func RunGit(t testing.TB, dir string, args ...string) string

RunGit runs git in dir and returns its trimmed output; a failure fails the test.

func RunScoped

func RunScoped(m *testing.M, prefix string) int

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

func RunUnprivileged(t *testing.T) bool

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 RunWithHardLinksRefused

func RunWithHardLinksRefused(t *testing.T) bool

RunWithHardLinksRefused reruns the calling top-level test in a child process whose kernel refuses every hard link with EACCES, as Android's SELinux policy refuses them in Termux's data directory. It returns true in the child, where the test body runs, and false in the parent once the child passed. The seccomp filter cannot be removed, so it never applies to the parent test process.

func RunWithoutGoroutineLeaks

func RunWithoutGoroutineLeaks(m *testing.M, afterTests ...func()) int

RunWithoutGoroutineLeaks runs the package's tests and then fails the test binary when goroutines leaked: TestMain calls os.Exit(testenv.RunWithoutGoroutineLeaks(m)). A failing test run returns its own code unchanged. Each afterTests function runs after the tests and before the check; a package uses one to end goroutines that deliberately model a crashed process, whose pending work Pi's runtime simply drops.

func ScopeTempDir

func ScopeTempDir(root string) error

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 moves every agent-directory variable under root (IsolateAgentEnv), so a test that reaches the agent directory through the environment cannot write the credentials, settings, trust file or sessions of the user running `go test`.

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

func ScriptCommand(t testing.TB, path string, args ...string) *exec.Cmd

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 Sh

func Sh(t testing.TB) string

Sh returns the POSIX sh that runs repository scripts, found as Bash is.

func SharedCargoTargetDir

func SharedCargoTargetDir(pkg string, lockInputs ...string) (string, error)

SharedCargoTargetDir returns a persistent Cargo target directory for one test package, so the Rust SDK's dependencies compile once per machine instead of once per package run. The directory lives under $PIG_TEST_CARGO_CACHE, else the user cache directory (pig-dev/cargo-target), and is named for the package and a hash of the given lockfiles and manifests (their contents and absolute paths), so a dependency change selects a fresh directory and an output built from another lock can never be reused. The absolute path is part of the key because rustc bakes `env!("CARGO_MANIFEST_DIR")` into a test binary and Cargo's fingerprint does not follow a moved or deleted checkout: a binary cached by another tree would open that tree's fixtures.

Cargo takes its own lock on a target directory, so concurrent builds of it wait for each other. Each test package gets its own directory because a cell's binary is copied out of release/<name> after its build: two packages building different cells of the same package name must not overwrite each other's output between build and copy. Within a package the directory was already shared by every test in the run.

func ShebangInterpreter

func ShebangInterpreter(t testing.TB, path string) string

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

func ShortTempDir(t testing.TB, prefix string) string

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(t testing.TB, oldname, newname string)

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 TimingGate

func TimingGate(t testing.TB, failed bool, format string, args ...any)

TimingGate is the one mechanism for a test that fails on a measured duration, a CPU time, an ns/op or a ratio of two timings compared to a bar. Pass the comparison's outcome as failed and the failure message as format and args; the call fails the test with t.Errorf semantics when failed is true, and the test goes on.

A timing depends on the machine's speed and load, so the owner's ruling (2026-10-15) splits the performance gates: a gate on a count (allocations, bytes, binary size, descriptors, goroutines, processes, temp entries) stays blocking everywhere and never calls this function, while a gate on a timing is blocking only on the quiet pinned hardware of the release perf run and report-only in pull-request CI. When TimingReportOnlyEnv is 1, a true failed does not fail the test: it logs the message and prints the GitHub Actions workflow command "::warning title=timing gate::<test name>: <message>" on stdout, and appends the same line to the file named by GITHUB_STEP_SUMMARY when that is set, because go test hides the stdout of a passing package without -v. The test still measures and still checks; only the verdict differs. With the variable unset or any other value the gate is blocking.

Every test that calls TimingGate or TimingGateFatal is listed in automation/perf/timing-gates.txt, which make test-timing runs with the variable unset; TestTimingGatesAreListed keeps that list complete.

func TimingGateFatal

func TimingGateFatal(t testing.TB, failed bool, format string, args ...any)

TimingGateFatal is TimingGate with t.Fatalf semantics: when the gate blocks, a true failed stops the test at once. Report-only, it returns and the test goes on, so code after the call must not rely on the bar having held.

func TypeErrors

func TypeErrors(t testing.TB, imports map[string]string, body string) []string

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

func VerbatimArgs(*exec.Cmd)

VerbatimArgs is a no-op: a POSIX exec passes argv without a command line.

Types

type Child

type Child struct {
	// contains filtered or unexported fields
}

Child is a started test child with its containment.

func Start

func Start(t testing.TB, cmd *exec.Cmd) (*Child, error)

Start starts cmd in its own process group or job and registers its cleanup on t. The caller waits with Child.Wait.

func (*Child) Cmd

func (c *Child) Cmd() *exec.Cmd

Cmd returns the started command.

func (*Child) Wait

func (c *Child) Wait() error

Wait waits for the child, then stops any descendant it left behind and fails the test for each such group. Wait is bounded by the command's WaitDelay. Call it instead of cmd.Wait.

type GitGate

type GitGate struct {
	// contains filtered or unexported fields
}

GitGate observes every git process the code under test starts and lets the test hold chosen ones before they run. The processes are real git: the gate puts a git on PATH that reports to the gate and then runs the git it replaced.

The gate counts processes per checkout and records each one that starts while another one is still inside the same checkout. Git takes .git/index.lock for the same span, so such an overlap is the race a concurrent update loses.

func NewGitGate

func NewGitGate(t testing.TB, hold func(GitOp) <-chan struct{}, exited func(GitOp)) *GitGate

NewGitGate installs the gate for the test. hold runs when a git process starts and returns a channel the process waits on before it runs, or nil to let it run at once. exited runs after a process has finished. Either may be nil. They run on the gate's server goroutines, concurrently.

It needs node, as the repository's other package-manager fixtures do. Call IsolateGit first so the real git ignores the host's configuration.

func (*GitGate) Ops

func (g *GitGate) Ops(checkout string) []GitOp

Ops returns the git processes that started in checkout, in start order.

func (*GitGate) Overlaps

func (g *GitGate) Overlaps() []GitOp

Overlaps returns every git process that started while another one was still inside its checkout.

func (*GitGate) ServeHTTP

func (g *GitGate) ServeHTTP(w http.ResponseWriter, r *http.Request)

type GitOp

type GitOp struct {
	// Dir is the checkout the process works in: its working directory, or the target directory of a clone. It is a physical path (PhysicalPath).
	Dir  string
	Args []string
}

GitOp is one git process the code under test starts.

func (GitOp) String

func (op GitOp) String() string

type GoroutineBaseline

type GoroutineBaseline struct {
	// contains filtered or unexported fields
}

GoroutineBaseline is the set of goroutines alive when it was taken. A test takes one, runs an owner (a host, a daemon, a client, a harness) through its work and its Close, and then calls GoroutineBaseline.RequireEnded: any goroutine the owner started that is still alive fails the test. It complements LeakedGoroutines, which only sees goroutines blocked on a primitive that nothing can reach: a goroutine that outlives its owner and still waits on a reachable channel, a timer, a socket or a child process is invisible to that profile.

func BaselineGoroutines

func BaselineGoroutines() GoroutineBaseline

BaselineGoroutines records the goroutines alive now.

func (GoroutineBaseline) Outliving

func (b GoroutineBaseline) Outliving() []string

Outliving returns the stack of each goroutine that was started after the baseline and is still alive, in goroutine-id order, without the test framework's and the runtime's own goroutines.

func (GoroutineBaseline) RequireAtMost

func (b GoroutineBaseline) RequireAtMost(t testing.TB, limit int, grace time.Duration)

RequireAtMost fails t when more than limit goroutines started after the baseline are alive once grace has passed. A test that replaces an owner's instance (a reload) takes the live count of the first instance as the limit: the replacement must not add goroutines of its own on top of the first instance's.

func (GoroutineBaseline) RequireEnded

func (b GoroutineBaseline) RequireEnded(t testing.TB, grace time.Duration)

RequireEnded fails t when a goroutine started after the baseline is still alive once grace has passed. A goroutine leaves the runtime's table a moment after it returns, so the check polls until the set is empty or grace ends; the failure names every survivor's stack.

type SubdirectoryOrigin

type SubdirectoryOrigin struct {
	// URL is the repository as a Git Package source spells it after "git:" (file://localhost/<path>).
	URL     string
	Commits [3]string
}

SubdirectoryOrigin is a bare repository of three commits. Every commit holds the directories a and b; Commits[1] is tagged v1 and Commits[2] is tagged v2, so a Package that selects a subdirectory at v1 and another at v2 resolve to one repository and two commits.

func NewSubdirectoryOrigin

func NewSubdirectoryOrigin(t testing.TB, name string) SubdirectoryOrigin

NewSubdirectoryOrigin creates the repository under a new directory named name. The directory is short: a managed checkout's path repeats the origin's path below the agent directory (git/localhost/<path>), and a test directory named for a long test twice in one path passes the 260 characters Windows allows a process's working directory.

func (SubdirectoryOrigin) CloneAt

func (o SubdirectoryOrigin) CloneAt(t testing.TB, dest, commit string)

CloneAt clones the origin to dest and detaches it at commit, as a managed checkout that an update has to move.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL