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
- func CopyTree(t *testing.T, root, src, dst string)
- func FilesUnder(t *testing.T, dirs ...string) map[string][]byte
- func Mkdir(t *testing.T, root, dir string)
- func SameTree(t *testing.T, root string, before, after map[string][]byte)
- func StillOnDisk(t *testing.T, root string, files map[string][]byte, after string)
- func TreeOf(t *testing.T, root string, skip ...string) map[string][]byte
- func WriteFile(t *testing.T, path string, data []byte)
- type Env
- func (e Env) CheckProxyReachable(ctx context.Context, port int) (network string, err error)
- func (e Env) Configured(also ...string) bool
- func (e Env) Container() string
- func (e Env) ContainerAddresses(ctx context.Context) []string
- func (e Env) DataDir(elem ...string) string
- func (e Env) Get(name string) string
- func (e Env) Mode() replayproxy.Mode
- func (e Env) ProxyPort() (int, error)
- func (e Env) Recording() bool
- func (e Env) Server() string
- func (e Env) StartProxy(ctx context.Context, opts replayproxy.Options) (*Proxy, error)
- func (e Env) Token() string
- func (e Env) Var(name string) string
- func (e Env) Verifying() bool
- type Proxy
Constants ¶
const DefaultProxyPort = 18080
DefaultProxyPort is the port the proxy listens on when the environment names none.
Variables ¶
This section is empty.
Functions ¶
func CopyTree ¶
CopyTree copies a folder under the tree at root, and everything under it, to a new place.
func FilesUnder ¶
FilesUnder reads every file under the folders, to hold them to later (StillOnDisk); folders with nothing under them fail the test.
func Mkdir ¶
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 ¶
SameTree fails for every path that changed, went or appeared between two reads of a tree (TreeOf), named without root.
func StillOnDisk ¶
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.
Types ¶
type Env ¶
type Env struct {
// contains filtered or unexported fields
}
Env reads one app's test environment.
func (Env) CheckProxyReachable ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) 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 ¶
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 ¶
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) StartProxy ¶
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.
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) Report ¶
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 ¶
Serve answers every request for host with h rather than a recording, until the returned func is called (replayproxy.Proxy.Serve).