env

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: GPL-3.0 Imports: 13 Imported by: 1

Documentation

Overview

Package env is what a suite run against a live server in a container is handed: the environment its test script exports, the record/replay proxy the server's calls to the internet go through, the checks that the container can reach it, the report at the end of a run on what the proxy saw, and files laid out where the container reads them.

Every variable carries the app's prefix: New("APP") reads APP_SERVER, APP_TOKEN, APP_TEST_RECORD and the rest. A suite that drives the tools over MCP and one that drives a generated SDK share the same containers and recordings, so both read them through here.

Index

Constants

View Source
const DefaultProxyPort = 18080

DefaultProxyPort is the port the proxy listens on when the environment names none.

Variables

This section is empty.

Functions

func CopyTree

func CopyTree(t *testing.T, root, src, dst string)

CopyTree copies a folder under the tree at root, and everything under it, to a new place.

func FilesUnder

func FilesUnder(t *testing.T, dirs ...string) map[string][]byte

FilesUnder reads every file under the folders, to hold them to later (StillOnDisk); folders with nothing under them fail the test.

func Mkdir

func Mkdir(t *testing.T, root, dir string)

Mkdir makes a directory under the bind-mounted tree at root that the server's own user can write in, and WriteFile writes a file there. The mode asked of MkdirAll and WriteFile is filtered by the process umask, which on Linux leaves a directory nobody but the test can write to - so a server running as another user in its container cannot delete a file the test laid out, and a tool that asks it to fails. chmod is not filtered by the umask, so the mode asked for is the mode applied. Docker Desktop hides this by mapping every file to the container's user, which is why it only bites in CI.

func SameTree

func SameTree(t *testing.T, root string, before, after map[string][]byte)

SameTree fails for every path that changed, went or appeared between two reads of a tree (TreeOf), named without root.

func StillOnDisk

func StillOnDisk(t *testing.T, root string, files map[string][]byte, after string)

StillOnDisk checks every file read by FilesUnder is where it was, as it was, after what the test did (after), naming a file without root.

func TreeOf

func TreeOf(t *testing.T, root string, skip ...string) map[string][]byte

TreeOf reads every folder and file under root, a folder ending in "/", so a test can hold the disk to what it was. skip leaves those paths, and whatever is under them, out.

func WriteFile

func WriteFile(t *testing.T, path string, data []byte)

WriteFile writes a file the server's own user can write over or remove (see Mkdir).

Types

type Env

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

Env reads one app's test environment.

func New

func New(prefix string) Env

New is the environment under prefix, without its underscore: "APP" for APP_SERVER.

func (Env) CheckProxyReachable

func (e Env) CheckProxyReachable(ctx context.Context, port int) (network string, err error)

CheckProxyReachable proves, from inside the container, that the server can reach the proxy, and says what the container sees of the network: its hosts entry for the gateway and its proxy setting. A server that cannot reach the proxy fails every lookup with a timeout of its own, which reads as dozens of unrelated assertion failures rather than the one plumbing problem it is - so say it plainly, once, before the suite runs. With no container named there is nothing to check.

func (Env) Configured

func (e Env) Configured(also ...string) bool

Configured reports whether the container environment is present: a server and a token, and each of the other variables a suite cannot run without.

func (Env) Container

func (e Env) Container() string

Container is the name of the container the test script started (APP_TEST_CONTAINER), "" when the server under test is not one of ours.

func (Env) ContainerAddresses

func (e Env) ContainerAddresses(ctx context.Context) []string

ContainerAddresses are the addresses the server reaches itself on: its container's addresses and hostname. A server that pings its own address at startup sends that through the proxy, because NO_PROXY is set before docker hands the container an address. It is nil when the environment names no container, or docker cannot say.

func (Env) DataDir

func (e Env) DataDir(elem ...string) string

DataDir is the host path the container's data is bind-mounted from (APP_TEST_DATA), with elem joined onto it, so a test can add or remove files and have the server see them. It is "" when the variable is not set, which every test that lays files out must skip on: joined onto nothing, the path would be a relative one, and the test would write into the checkout.

func (Env) Get

func (e Env) Get(name string) string

Get is the value of one of the app's variables, "" when it is not set.

func (Env) Mode

func (e Env) Mode() replayproxy.Mode

Mode is how the environment asks the proxy to run: replaying unless told to record or to verify, and recording when told both.

func (Env) ProxyPort

func (e Env) ProxyPort() (int, error)

ProxyPort is the port the proxy listens on, APP_TEST_PROXY_PORT or DefaultProxyPort, which the container's HTTPS_PROXY already names.

func (Env) Recording

func (e Env) Recording() bool

Recording reports whether this run may call the real services. APP_TEST_RECORD=1 fills in only the answers a cassette lacks, replaying the rest as recorded; APP_TEST_RECORD=all fetches every answer afresh.

func (Env) Server

func (e Env) Server() string

Server is the address of the server under test (APP_SERVER).

func (Env) StartProxy

func (e Env) StartProxy(ctx context.Context, opts replayproxy.Options) (*Proxy, error)

StartProxy brings up the record/replay proxy the container's HTTPS_PROXY already points at, and proves the container can reach it, saying on stderr what the container sees of the network.

The environment decides how it runs and where it listens: opts.Mode is Env.Mode whatever it was set to; an empty opts.Addr is every interface on ProxyPort; and with no authority named, the files ca.pem and ca.key under APP_TEST_PROXY_CA are used when that is set, the directory the test script minted one in and mounted into the container. The addresses the server reaches itself on (ContainerAddresses) are added to opts.IgnoreHosts. The rest - the cassettes, what to redact, what else to ignore - is the suite's.

func (Env) Token

func (e Env) Token() string

Token is the credential for it (APP_TOKEN).

func (Env) Var

func (e Env) Var(name string) string

Var is the full name of one of the app's variables: Var("TEST_DATA") is APP_TEST_DATA.

func (Env) Verifying

func (e Env) Verifying() bool

Verifying reports whether to check the cassettes against the live services without rewriting them (APP_TEST_VERIFY).

type Proxy

type Proxy struct {

	// Misses are the requests replay had no recording for, and Drifts the
	// answers that changed shape since recording (when verifying); both are
	// read when the proxy is stopped
	Misses []string
	Drifts []replayproxy.Drift
	// contains filtered or unexported fields
}

Proxy is the record/replay proxy a suite runs for the length of its run, and what it saw once stopped.

func (*Proxy) Addr

func (p *Proxy) Addr() string

Addr is the address the proxy listens on.

func (*Proxy) Report

func (p *Proxy) Report() string

Report says what a stopped proxy saw that fails a run, "" for nothing: a replay miss means a test ran against a 502 rather than a recording, so it is said loudly even when the assertions happened to survive it, and a drift (collected when verifying alone) means a service still answers, but no longer in the shape that was recorded.

func (*Proxy) Serve

func (p *Proxy) Serve(host string, h http.Handler) (stop func())

Serve answers every request for host with h rather than a recording, until the returned func is called (replayproxy.Proxy.Serve).

func (*Proxy) Stop

func (p *Proxy) Stop() error

Stop closes the proxy and keeps what it saw, returning what closing it failed with. Stopping twice, or stopping what never started, is harmless.

func (*Proxy) Transport

func (p *Proxy) Transport() *http.Transport

Transport is for a client in the test's own process that should go through the proxy too, such as a tool that asks a service itself: it trusts the proxy's certificates (replayproxy.Proxy.Transport).

Jump to

Keyboard shortcuts

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