testenv

Documentation

Overview

Package testenv gives a package's tests a home of their own, on every OS: HOME, USERPROFILE (Windows' home), the XDG folders and Windows' APPDATA and LOCALAPPDATA all point into one new temporary folder, the agents' own variables (agentenv.Vars) are cleared, and the keychain tools and agent CLIs on PATH are failing stand-ins, so that no test reads or writes the files of the user running it. Setting HOME alone isn't that: on Windows Go reads the home from USERPROFILE, and a test then meets the real ~/.claude. A package uses it from its TestMain:

func TestMain(m *testing.M) { testenv.Main(m) }

and a test that wants a home of its own sets it with SetHome, never HOME alone. Only tests import it.

Index

• Constants
• func Bun(t testing.TB) string
• func ClearProxy()
• func Isolate() (string, error)
• func Main(m *testing.M)
• func Offline()
• func Program[S ~string | ~[]byte](t testing.TB, path string, script S)
• func RemovePrograms()
• func Run(m *testing.M) int
• func RunIn(m *testing.M, setup func(home string)) int
• func SetHome(t testing.TB, dir string)
• func StandIns(bin string, names []string) error
• func WriteProgram[S ~string | ~[]byte](path string, script S) error
• func Zone(t testing.TB, loc *time.Location)

Constants

const (

	// Marker holds the temporary home in the environment. A test binary
	// started again by one of its own tests inherits it, and keeps the
	// environment that test gave it (its fixtures) instead of isolating
	// again; a test that hands such a child an environment of its own
	// passes Marker along.
	Marker = "MAGPIE_TEST_SANDBOX"
)

const MinBun = "1.4.2"

MinBun is the oldest Bun magpie runs plugins on: plugin.BunVersion, which internal/plugin's TestMinBunIsBunVersion keeps it equal to (testenv can't import internal/plugin, whose own tests use it).

Functions

func Bun

func Bun(t testing.TB) string

Bun is the bun on PATH for a test that runs plugins with it (as MAGPIE_BUN), run once before the test opens its deadline; a machine without one skips the test. A bun just installed or upgraded hasn't run on this machine yet, and macOS checks a program before its first exec, which can take tens of seconds on a busy machine: that check must not eat the minute a test gives its plugin calls (ggbdpq, #1306).

A bun older than MinBun skips the test too, saying so: magpie never runs plugins on one (it downloads MinBun or newer), and an older one fails these tests for its own differences, not magpie's. Bun 1.3 names the default port in a proxy's request line (GET http://models.invalid:80/list) and its node:http2 answers status 0, which failed the plugin proxy tests on a developer's machine (#1600).

func ClearProxy

func ClearProxy()

ClearProxy unsets the machine's proxy variables. Isolate calls it before the tests run; a package that isolates itself in its own TestMain calls it too, before the first request any test makes.

func Isolate

func Isolate() (string, error)

Isolate points the home and the config, cache and data folders into a new temporary folder, clears the agents' variables, puts the stand-ins first on PATH and gives the folder. It fails when Go would still resolve any of them, or a stand-in's tool, outside that folder.

func Main

func Main(m *testing.M)

Main runs the package's tests in a home of their own and exits with their code.

func Offline

func Offline()

Offline keeps the package's tests off the network: http.DefaultTransport (and so http.DefaultClient, and every transport cloned from it after the call) dials this computer only — localhost, a name under .localhost, a loopback or unspecified address — and refuses anything else before it is looked up, saying so on stderr once per address. A test that wants a vendor serves it on loopback and points the request there (an httptest.Server, a Transport rewriting the host). Without it the tests of internal/gateway and internal/provider asked the real models.dev (its catalog, fetched as each plugin host started), api.github.com, chatgpt.com and Devin's server.codeium.com with made-up accounts, and a plan key with a vendor's real base URL would have its windows read for routing (#1016). A package calls it from its TestMain, before m.Run.

func Program

func Program[S ~string | ~[]byte](t testing.TB, path string, script S)

Program writes script, a `#!` script, at path as a program a test runs, where os.WriteFile(path, script, 0o755) would. On macOS the file is one the system has already let run: macOS checks a newly written executable before its first exec, a quarter of a second alone and several seconds while other new programs start (a go test ./... starting its test binaries), which ate the wait of every test that times a fake's answer (TestDevinSignedInOnlyInMagpie, TestClaudeRunEndsWhenTheClientLeaves). The check is made once a file: one already run keeps its pass when it is renamed or written over in place. So Program takes a file that has run from a pool, renames it to path and writes the script into it; when the test ends, the file goes back to the pool for the next test.

func RemovePrograms

func RemovePrograms()

RemovePrograms deletes the pool, after the tests: Run does it, and a TestMain of its own calls it.

func Run

func Run(m *testing.M) int

Run is Main for a TestMain with more to set up: it isolates, runs the tests and removes the temporary home, and gives the code to exit with. It runs no test when the home can't be made safe.

func RunIn

func RunIn(m *testing.M, setup func(home string)) int

RunIn is Run with setup called on the temporary home before the tests, for fixtures that live in it.

func SetHome

func SetHome(t testing.TB, dir string)

SetHome makes dir the home for one test, on every OS: HOME, and USERPROFILE, which Go reads on Windows.

func StandIns

func StandIns(bin string, names []string) error

StandIns writes a failing program for each name in bin. On macOS each is run once now, in the background, so that the check macOS makes of a new program's first run (Program) is made while the tests start rather than in the first test to reach it, and without holding them up. Windows finds a program by PATHEXT and passes over a file with no extension, so there each also gets a .bat, which comes before the user's own codex.cmd further down PATH: without it the gateway's tests, which make their stand-ins here, read the installed Codex's version (#1827, EdwinDigital: TestCodexPoolSaysTheClientsVersion saw 0.162.0).

func WriteProgram

func WriteProgram[S ~string | ~[]byte](path string, script S) error

WriteProgram is Program for a fake that lasts the whole test binary, made from TestMain, or written by a stand-in for the code under test: it is not taken back when a test ends.

func Zone

func Zone(t testing.TB, loc *time.Location)

Zone sets time.Local for the test, and puts it back after. It first waits out the stand-ins' first runs: they os.Stat what ran, which reads time.Local, so a test that swaps it while they are under way races them.