Documentation
¶
Overview ¶
Package testrun owns the Docker objects a test process creates on a shared daemon. Every object carries the label of the run that created it, every run holds a lease while it is alive, and every run that starts sweeps the objects of the runs whose leases are dead, whichever suite started them.
Index ¶
Constants ¶
const ( // RunLabel names the run an object belongs to. RunLabel = "io.shellhub.e2e.run" // LeaseLabel marks the containers that keep a run alive. LeaseLabel = "io.shellhub.e2e.lease" // KindLabel says how a lease container keeps its run alive: KindProcess or KindStack. KindLabel = "io.shellhub.e2e.kind" // ExpiresLabel holds, in RFC 3339, the time a stack run's leases stop keeping it alive. ExpiresLabel = "io.shellhub.e2e.expires" // CheckoutLabel holds the absolute path of the repository checkout that started a stack run. CheckoutLabel = "io.shellhub.e2e.checkout" // KindProcess is the kind of a lease a process holds open for as long as it lives. KindProcess = "process" // KindStack is the kind of a lease a kept compose stack's containers carry. KindStack = "stack" )
Variables ¶
This section is empty.
Functions ¶
func Labelled ¶
func Labelled() testcontainers.CustomizeRequestOption
Labelled joins the container a request starts to a run, so the next run on the daemon sweeps it when the process dies without removing it. It labels the container only, not an image the request builds. On the first request it customizes, it starts a run for the calling process, once per process, which the process never closes. That start ignores the request's context, which testcontainers does not pass to the option. The request fails with the error Start returns when that run cannot start, and so does every later request in the process.
Types ¶
type Run ¶
type Run struct {
// contains filtered or unexported fields
}
Run owns the objects one test process or one kept stack creates on a shared daemon: the images it builds and the containers and networks it starts, each labelled with the run's ID.
A run is alive while any of its leases is. A process lease is a container whose stdin the process holds open; it is alive while it runs and for a grace period after its creation, which covers the moment between creating and starting it. A stack lease is one of a kept stack's own containers; it is alive while it exists and its expiry is in the future. A lease with no kind counts as a stack lease, alive for 24 hours after its creation, when its container belongs to a compose project, and as a process lease otherwise.
func Start ¶
Start starts a run for the calling process. Its lease is a container whose stdin the process holds open, so the daemon releases the lease however the process ends. It sweeps the dead runs on the daemon once the lease exists, logging what it cannot remove. It returns an error when the package was built with -trimpath, versions.env cannot be read, has a line that is not KEY=VALUE or does not pin ALPINE_VERSION, the daemon cannot be reached, or the lease cannot be created. The lease outlives ctx; Run.Close releases it.
func StartStack ¶
StartStack starts the run of a kept compose stack, identified by its project name. The stack's containers carry the lease, so the run stays alive after the calling process exits, for as long as any of them exists and opts.TTL has not passed. The calling process holds a process lease of its own until it exits or calls Run.Close, covering the objects it creates before the first stack container. It returns an error when project is not a valid image tag and project name, when opts.TTL is not positive, and in the cases Start does.
func (*Run) Close ¶
Close removes every object labelled with the run, then releases the lease the process holds and closes the run's Docker client. It is best-effort: it returns every listing or removal that failed, which the next sweep retries once the run is dead, joined with any error closing the client. ctx bounds the removals; the lease is released whatever ctx's state.
type StackOptions ¶
type StackOptions struct {
// TTL is how long after the run starts its stack stays alive.
TTL time.Duration
// Checkout is the absolute path of the repository checkout that started the stack.
Checkout string
}
StackOptions sets how long a kept stack lives and which checkout it belongs to. A later run sweeps the stack once it expires.