Documentation
¶
Overview ¶
Package processtest is the integration toolkit for a program built on the process package. It runs the program as the binary and drives it only through the interfaces a terminal or an orchestrator uses: its captured output, the signals process.SignalContext answers, and its exit code. Nothing in the runtime exists for the tests' sake.
The package exports:
- Main, a suite's TestMain, which builds the program once per run
- Launch, which starts the built program as a Process
- Run, which runs the built program once as a Cmd says, with its arguments, standard input, and environment, and returns its Result, the stdout, stderr, and exit code
- Process, one running program, which a test waits on with Process.Await and Process.Wait, reads with Process.Output and Process.Exited, and interrupts with Process.Stop
- Forward, which starts a Forwarder, a loopback relay to a backing service that Forwarder.Sever cuts and Forwarder.Restore reopens at Forwarder.Addr
- WaitFor, which polls a condition no single process owns
- FreePort, which reserves a loopback port for the process to bind
- Failsafe, the bound on every wait
Index ¶
Constants ¶
const Failsafe = 15 * time.Second
Failsafe bounds every wait for an event that should occur, so a broken composition fails a test instead of hanging the run.
Variables ¶
This section is empty.
Functions ¶
func FreePort ¶
FreePort reserves an ephemeral loopback port and releases it for the process to bind. The window between release and bind is the usual one of a port-based harness; a lost race fails the bind, and Await reports the exit with the output.
func Main ¶
Main is the suite's TestMain: it builds the main package pkg once, with the race detector so the program runs under it too, runs the tests, and removes the build. pkg is a package path relative to the module root, such as ./cmd/server. A build failure ends the run before any test starts.
Types ¶
type Cmd ¶ added in v0.6.0
type Cmd struct {
// Args are the program's arguments, without the program name.
Args []string
// Stdin is the program's standard input; nil is empty.
Stdin io.Reader
// Env holds KEY=VALUE overrides added to the parent's environment.
Env []string
}
Cmd is one invocation of the program for Run. Its zero value runs the program with no arguments, an empty standard input, and the parent's environment.
type Forwarder ¶
type Forwarder struct {
// contains filtered or unexported fields
}
Forwarder is a loopback TCP relay between the process and a backing service, the connection a test severs to inject an outage.
func Forward ¶
Forward starts relaying to target, host:port, on an ephemeral loopback port; the relay is severed at test cleanup.
func (*Forwarder) Addr ¶
Addr is the address the process connects to, host:port. It is stable across Sever and Restore.
type Process ¶
type Process struct {
// contains filtered or unexported fields
}
Process is one running program: its captured output and its exit.
func Launch ¶
Launch starts the binary Main built in the module root, with the parent's environment plus env's KEY=VALUE overrides, and returns without waiting. At test cleanup, a process still running is interrupted, then killed after Failsafe.
func (*Process) Await ¶
Await polls cond until it holds, failing the test with the captured output if the process exits or Failsafe elapses first. A harness waits for readiness this way: on the condition a client observes, never on the output.
func (*Process) Output ¶
Output is everything the process has written so far, stdout and stderr interleaved as they arrived.
type Result ¶ added in v0.6.0
type Result struct {
// Stdout and Stderr are the program's two output streams, each
// captured whole and apart from the other.
Stdout, Stderr string
// Code is the program's exit code.
Code int
}
Result is what one run of the program produced.
func Run ¶ added in v0.6.0
Run executes the program Main built, once, in the module root, with the environment Launch gives it plus cmd.Env; it waits for the program to exit and returns its output and exit code. A nonzero code is a result, not a failure. A run still going after Failsafe is a stall: it is interrupted, killed if it has not exited within Failsafe more, and fails the test with its output. Run logs the run through t.Log as a shell line a reader can paste, with the output after it.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
testprog
command
Command testprog is the program the processtest package's own tests run: it answers on a loopback address, waits for the interrupt, and exits with the code its environment names, so the runner is proved against a real subprocess without a service behind it.
|
Command testprog is the program the processtest package's own tests run: it answers on a loopback address, waits for the interrupt, and exits with the code its environment names, so the runner is proved against a real subprocess without a service behind it. |