Documentation
¶
Overview ¶
Package containers is the shared lifecycle for unison's container-backed tests: the gate that keeps a bare `go test` from needing a Docker daemon, the retry policies that absorb a cold start, and one Run that owns a container so a test body only has to say what to do with a live database.
It exists because unison generates argument order, and an argument-order bug is invisible to everything else the suite does. Generated code that binds sixteen MySQL placeholders from eight fields in the wrong order compiles, regenerates byte-identically, and matches its golden file. Only executing it against a real server disagrees.
The shape here follows platform-go's testutils/containers, deliberately: an engineer who knows that harness should recognize this one. It is much smaller — unison has no per-test schema isolation, no template cloning, and no database client abstraction to bridge — but the parts that are here mean what they mean there.
Index ¶
- Constants
- Variables
- func PingUntilReady(tb testing.TB, ctx context.Context, ping func(context.Context) error)
- func Run[C Terminable](tb testing.TB, start func(ctx context.Context) (C, error), ...)
- func SkipIfNotRunning(tb testing.TB)
- func StartWithRetry[C any](ctx context.Context, start func(context.Context) (C, error)) (C, error)
- type Terminable
Constants ¶
const EnvVar = "RUN_CONTAINER_TESTS"
EnvVar names the variable that opens the gate.
It is spelled the way platform-go spells it so that one export in a shell governs both repositories, which is the whole ergonomic benefit of matching somebody else's convention.
const ( // ShutdownTimeout bounds termination. It runs on a context detached from // the test's, so a test that has already blown its own deadline still gets // its container reaped. ShutdownTimeout = 30 * time.Second )
Variables ¶
Running reports whether container-backed tests were asked for. It is read once, at package init, so every test in a run agrees.
Functions ¶
func PingUntilReady ¶
PingUntilReady calls ping until it succeeds, failing tb if it never does.
A container's readiness log is not the same event as its server accepting connections. Both the Postgres and MySQL images run an init pass against a temporary server and then restart, so a wait strategy matching log lines can release the test against a socket that is about to close. Downstream that looks like "bad connection" or "unexpected EOF" from the very first statement, on a container that is perfectly healthy a second later.
Retrying the first ping is the fix that does not depend on reading logs: no pool is handed to a test until a query has actually round-tripped.
func Run ¶
func Run[C Terminable](tb testing.TB, start func(ctx context.Context) (C, error), fn func(ctx context.Context, container C))
Run starts a container, hands it to fn, and terminates it afterwards.
Termination is registered with tb.Cleanup rather than deferred until fn returns, and the distinction is load-bearing: a closure that registers parallel subtests returns before those subtests execute, and a deferred Terminate would pull the container out from under them.
The flip side is that the container lives until the end of tb rather than the end of fn, so call Run from the narrowest test that needs it.
func SkipIfNotRunning ¶
SkipIfNotRunning skips unless containers were asked for.
-short skips even when the variable is set, and deliberately: -short is the caller saying they want a fast answer, and standing up two databases is the slowest thing this repository does.
Types ¶
type Terminable ¶
type Terminable interface {
Terminate(ctx context.Context, opts ...testcontainers.TerminateOption) error
}
Terminable is the teardown half of the testcontainers API — the only part Run needs in order to own a container's life.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package mysqltest runs a test body against a real MySQL server.
|
Package mysqltest runs a test body against a real MySQL server. |
|
Package pgtest runs a test body against a real PostgreSQL server.
|
Package pgtest runs a test body against a real PostgreSQL server. |