Documentation
¶
Overview ¶
Package testenv contains helpers used by tests to assert hermeticity preconditions. The headline helper is RequireContainer, which fast-fails any test that ought to run inside the agentsync hermetic container but is somehow being run on the host.
Importing the package also scrubs the ambient environment: a package-level init runs ScrubAmbient before any TestMain or test body, so a test's result can never depend on what the developer's shell happens to export (issue #270). Every FS-touching package already imports testenv for its guard; a host-safe package with an env-sensitive decision (internal/ui's colour resolution) imports it for the side effect alone.
Index ¶
Constants ¶
const EnvVar = "AGENTSYNC_TEST_IN_CONTAINER"
EnvVar is the explicit signal the agentsync test container sets at runtime. The hermetic entrypoint exports it; production environments never do.
Variables ¶
This section is empty.
Functions ¶
func InContainer ¶
func InContainer() bool
InContainer reports whether this process is plausibly running inside a Linux container. It is intentionally permissive — any one of the following signals is enough:
- the agentsync entrypoint's AGENTSYNC_TEST_IN_CONTAINER=1 export
- /.dockerenv (docker convention)
- /run/.containerenv (podman convention)
- /proc/1/cgroup mentions docker / podman / containerd / kubepods
We do not require ALL signals — engineers running ad-hoc shells inside the test image (e.g. `scripts/test-in-container.sh shell`) inherit the env var but might not have /.dockerenv mounted on every runtime. One signal is enough to honour the "running in a container" intent.
func MustRunInContainer ¶
func MustRunInContainer()
MustRunInContainer is the TestMain-friendly counterpart to RequireContainer. It writes a clear message to stderr and exits non-zero when invoked outside a container, before any test in the package runs. Use from TestMain like:
func TestMain(m *testing.M) {
testenv.MustRunInContainer()
os.Exit(m.Run())
}
func RequireContainer ¶
RequireContainer is the canonical guard for FS-touching tests (integration / e2e / bdd). It must be called as the first line of TestMain (or each TestXxx) in any package whose tests use t.TempDir(), AGENTSYNC_TARGET_ROOT, or otherwise write to disk.
On host execution it calls t.Fatalf with a clear remediation message, which surfaces in `go test` output and short-circuits the rest of the test. Inside the container it is a fast no-op.
func ScrubAmbient ¶ added in v0.16.0
func ScrubAmbient() []string
ScrubAmbient removes from the process environment every variable that could move a test's result but that no test asked for: every AGENTSYNC_* override (AGENTSYNC_HOME, AGENTSYNC_TARGET_ROOT, the AGENTSYNC_ALLOW_* hatches, …) except the harness's own AGENTSYNC_TEST_* / AGENTSYNC_LIVE_* signals, plus the variables in ambientVars. It returns the names it cleared, in environment order.
It runs automatically from this package's init (see above) and is idempotent, so calling it again is harmless. It is process-wide and deliberately does NOT restore: an ambient value is never something a test wants back, and a test that needs a variable sets it itself with t.Setenv (whose cleanup restores "unset", consistent with the scrubbed baseline).
Why this exists: `go test ./...` used to pass ONLY in an environment where none of our variables were set. CI is exactly that environment, so the suite had never been validated against a machine that actually uses agentsync — and an exported AGENTSYNC_HOME redded out 535 tests in internal/cli, the secret-leak guard among them (issue #270).
Types ¶
This section is empty.
Source Files