Documentation
¶
Index ¶
- Variables
- func BuilderName(t testing.TB, base string) string
- func ComposeStandalonePath(t testing.TB) string
- func ContainerdImageStore(t testing.TB, c *CLI) string
- func CopyFile(t testing.TB, sourceFile string, destinationFile string)
- func HTTPGetWithRetry(t testing.TB, endpoint string, expectedStatus int, retryDelay time.Duration, ...) string
- func IsHealthy(service string) func(res *icmd.Result) bool
- func Lines(output string) []string
- func RequireEventuallyServiceState(t testing.TB, cli *CLI, service string, state string)
- func RequireServiceState(t testing.TB, cli *CLI, service string, state string)
- type Action
- type CLI
- func (c *CLI) BaseEnvironment() []string
- func (c *CLI) MetricsSocket() string
- func (c *CLI) NewCmd(command string, args ...string) icmd.Cmd
- func (c *CLI) NewCmdWithEnv(envvars []string, command string, args ...string) icmd.Cmd
- func (c *CLI) NewDockerCmd(t testing.TB, args ...string) icmd.Cmd
- func (c *CLI) NewDockerComposeCmd(t testing.TB, args ...string) icmd.Cmd
- func (c *CLI) RunCmd(t testing.TB, args ...string) *icmd.Result
- func (c *CLI) RunCmdInDir(t testing.TB, dir string, args ...string) *icmd.Result
- func (c *CLI) RunDockerCmd(t testing.TB, args ...string) *icmd.Result
- func (c *CLI) RunDockerComposeCmd(t testing.TB, args ...string) *icmd.Result
- func (c *CLI) RunDockerComposeCmdNoCheck(t testing.TB, args ...string) *icmd.Result
- func (c *CLI) RunDockerOrExitError(t testing.TB, args ...string) *icmd.Result
- func (c *CLI) ServicePublishedPort(t testing.TB, project, service string, targetPort int) int
- func (c *CLI) WaitForCmdResult(t testing.TB, command icmd.Cmd, predicate func(*icmd.Result) bool, ...)
- func (c *CLI) WaitForCondition(t testing.TB, predicate func() (bool, string), timeout time.Duration, ...)
- type CLIOption
- type Check
- func BindMountSource(service, target, wantSource string) Check
- func ContainerEnv(service, name, value string) Check
- func Eventually(check Check, timeout time.Duration) Check
- func ExecOutputContains(service, command, sub string) Check
- func ExitCode(code int) Check
- func FileAbsent(path string) Check
- func FileContains(path, sub string) Check
- func FileExists(path string) Check
- func ImageAbsent(ref string) Check
- func ImageExists(ref string) Check
- func LabelSet(service, key string) Check
- func LabelUnchanged(service, key string) Check
- func LabelsDistinct(key string, services ...string) Check
- func NotRecreated(services ...string) Check
- func OneOffState(service, state string) Check
- func OneOffsRemoved(service string) Check
- func OneOffsUntouched(service string) Check
- func OutputContains(sub string) Check
- func OutputMatches(pattern string) Check
- func OutputMatchesCount(pattern string, n int) Check
- func OutputNotContains(sub string) Check
- func Recreated(services ...string) Check
- func ReplicaNumbers(service string, numbers ...int) Check
- func RunsOnPlatform(service, platform string) Check
- func ServiceHealthy(service string) Check
- func ServiceNotCreated(service string) Check
- func ServiceScale(service string, n int) Check
- func ServiceState(service, state string) Check
- func StderrContains(sub string) Check
- func StdoutContains(sub string) Check
- func StdoutEmpty() Check
- func VolumeAbsent(name string) Check
- func VolumeExists(name string) Check
- type CheckContext
- type Requirement
- type Scenario
- func (s *Scenario) CLI() *CLI
- func (s *Scenario) Defer(actions ...Action) *Scenario
- func (s *Scenario) Dir() string
- func (s *Scenario) Env(kv ...string) *Scenario
- func (s *Scenario) FromFile(name string) *Scenario
- func (s *Scenario) FromRemote(source string, rootFlags ...string) *Scenario
- func (s *Scenario) NonNativePlatform() string
- func (s *Scenario) Project() string
- func (s *Scenario) Requires(reqs ...Requirement) *Scenario
- func (s *Scenario) Step(name string, action Action, checks ...Check) *Scenario
- type ScenarioOption
Constants ¶
This section is empty.
Variables ¶
var ( // DockerExecutableName is the OS dependent Docker CLI binary name DockerExecutableName = "docker" // DockerComposeExecutableName is the OS dependent Docker CLI binary name DockerComposeExecutableName = "docker-" + compose.PluginName // DockerScanExecutableName is the OS dependent Docker Scan plugin binary name DockerScanExecutableName = "docker-scan" // DockerBuildxExecutableName is the Os dependent Buildx plugin binary name DockerBuildxExecutableName = "docker-buildx" // DockerModelExecutableName is the Os dependent Docker-Model plugin binary name DockerModelExecutableName = "docker-model" // WindowsExecutableSuffix is the Windows executable suffix WindowsExecutableSuffix = ".exe" )
Functions ¶
func BuilderName ¶
BuilderName returns a buildx builder name that is unique to the test, preventing container-name collisions when tests run in parallel on the same Docker daemon.
func ComposeStandalonePath ¶
ComposeStandalonePath returns the path to the locally-built Compose standalone binary from the repo.
This function will fail the test immediately if invoked when not running in standalone test mode.
func ContainerdImageStore ¶
ContainerdImageStore requires the daemon to use the containerd image store.
func CopyFile ¶
CopyFile copies a file from a sourceFile to a destinationFile setting permissions to 0755
func HTTPGetWithRetry ¶
func HTTPGetWithRetry( t testing.TB, endpoint string, expectedStatus int, retryDelay time.Duration, timeout time.Duration, ) string
HTTPGetWithRetry performs an HTTP GET on an `endpoint`, using retryDelay also as a request timeout. In the case of an error or the response status is not the expected one, it retries the same request, returning the response body as a string (empty if we could not reach it)
func RequireEventuallyServiceState ¶
RequireEventuallyServiceState polls `compose ps` until the service reaches the expected state, instead of checking once.
`compose ps` makes a fresh ContainerList call to the daemon, an entirely different channel than a container's log stream: an application log line already relayed to a caller is no guarantee the daemon-reported state has caught up yet by the time that caller turns around and calls `ps` in a new process. Callers observing readiness through a log line (or any signal other than this same `ps` state) must poll here rather than check once.
func RequireServiceState ¶
RequireServiceState ensures that the container reaches the expected state (running or exited). The daemon reports state transitions asynchronously from everything else a test can observe (a container whose logs already flowed may still be listed under its previous state for a moment), so the check polls `compose ps` until the state converges instead of asserting on a single snapshot.
Types ¶
type Action ¶
type Action struct {
// contains filtered or unexported fields
}
Action is a command a step executes: a compose command run against the scenario's project, a raw docker command, or a completion request.
func CompleteCmd ¶
CompleteCmd runs the shell-completion entry point of the compose CLI, in plugin or standalone form, for the command line `compose -f <file> <args>`: the last argument is the word being completed, empty to list every candidate. Only the scenario's compose source (its file, or its remote after FromRemote) is passed along, not its root arguments or project name.
func ComposeCmd ¶
ComposeCmd runs `docker compose <args>` against the scenario's compose file and project name.
func (Action) MayFail ¶
MayFail marks the action as best-effort: a non-zero exit does not fail the scenario (e.g. removing an image that may not exist).
func (Action) WithStdin ¶
WithStdin feeds the command's standard input, e.g. to answer an interactive prompt ("n\n").
type CLI ¶
type CLI struct {
// ConfigDir for Docker configuration (set as DOCKER_CONFIG)
ConfigDir string
// HomeDir for tools that look for user files (set as HOME)
HomeDir string
// contains filtered or unexported fields
}
CLI is used to wrap the CLI for end to end testing
func NewParallelCLI ¶
NewParallelCLI marks the parent test as parallel and returns a CLI instance suitable for usage across child tests.
func (*CLI) BaseEnvironment ¶
BaseEnvironment provides the minimal environment variables used across all Docker / Compose commands.
func (*CLI) MetricsSocket ¶
MetricsSocket get the path where test metrics will be sent
func (*CLI) NewCmdWithEnv ¶
NewCmdWithEnv creates a cmd object configured with the test environment set with additional env vars
func (*CLI) NewDockerCmd ¶
NewDockerCmd creates a docker cmd without running it
func (*CLI) NewDockerComposeCmd ¶
NewDockerComposeCmd creates a command object for Compose, either in plugin or standalone mode (based on build tags).
func (*CLI) RunCmdInDir ¶
RunCmdInDir runs a command in a given dir, expects no error and returns a result
func (*CLI) RunDockerCmd ¶
RunDockerCmd runs a docker command, expects no error and returns a result
func (*CLI) RunDockerComposeCmd ¶
RunDockerComposeCmd runs a docker compose command, expects no error and returns a result
func (*CLI) RunDockerComposeCmdNoCheck ¶
RunDockerComposeCmdNoCheck runs a docker compose command, don't presume of any expectation and returns a result
func (*CLI) RunDockerOrExitError ¶
RunDockerOrExitError runs a docker command and returns a result
func (*CLI) ServicePublishedPort ¶
ServicePublishedPort returns the ephemeral host port mapped to targetPort on the named service in the given compose project. It requires the service to be already running. The test fails immediately if the mapping cannot be resolved.
type CLIOption ¶
type CLIOption func(c *CLI)
CLIOption to customize behavior for all commands for a CLI instance.
type Check ¶
type Check struct {
// contains filtered or unexported fields
}
Check is a named observable expected to hold after a step.
func BindMountSource ¶
BindMountSource expects the service's bind mount at target to resolve to exactly wantSource (which must be absolute — this check pins down which working directory a relative volume path was resolved against, e.g. an explicit --project-directory, so a relative wantSource here would silently compare against the wrong base: the test process's own cwd, not any project directory).
func ContainerEnv ¶
ContainerEnv expects every container of the service to carry the given environment variable with the exact value, as recorded in the container config — the observable effect of `environment`, `env_file` or provider injection, whatever the source of the model.
func Eventually ¶
Eventually retries a state-based check until it holds or the timeout expires, re-observing the project state between attempts. Output-based checks are not meaningful here: the step's output never changes. Polling is delegated to gotest.tools/v3/poll, the same engine the rest of the e2e framework uses.
func ExecOutputContains ¶
ExecOutputContains expects `docker exec` of the command in the service's first container to succeed and print a string — a state probe for effects only visible from inside the container (files written by hooks, mounted volumes), where no host-side observable exists.
func ExitCode ¶
ExitCode expects the step's command to have exited with the given code. Only meaningful on a MayFail action: without MayFail, any non-zero exit already fails the step before checks run.
func FileAbsent ¶
FileAbsent expects no file or directory to exist at the given host path, e.g. content a previous step wiped.
func FileContains ¶
FileContains expects the host file at the given path to contain a string, e.g. a file copied out of a container.
func FileExists ¶
FileExists expects a non-empty file at the given host path, e.g. the output of an export command.
func ImageAbsent ¶
ImageAbsent expects no image with the given reference in the local store — the observable proof that a dry-run left the engine untouched.
func ImageExists ¶
ImageExists expects an image with the given reference to be present in the local store.
func LabelUnchanged ¶
LabelUnchanged expects a service's label to have the same value as before the step.
func LabelsDistinct ¶
LabelsDistinct expects the given services to carry pairwise-distinct values for a label.
func NotRecreated ¶
NotRecreated expects the services' containers to be exactly the ones that existed before the step (same container IDs).
func OneOffState ¶
OneOffState expects every one-off (run) container of the service to be in the given state.
func OneOffsRemoved ¶
OneOffsRemoved expects the one-off containers the service had before the step to be gone; it errors if the service had none, rather than pass vacuously.
func OneOffsUntouched ¶
OneOffsUntouched expects the service's one-off containers to be exactly the ones from before the step, neither restarted nor removed: same container IDs, same state, same start time.
func OutputContains ¶
OutputContains expects the command output to contain a string. Prefer state-based checks; use this when the CLI's reported decision is itself the observable.
func OutputMatches ¶
OutputMatches expects the regular expression to match the command's stdout, for expectations OutputContains cannot express (e.g. ordering).
func OutputMatchesCount ¶
OutputMatchesCount expects the regular expression to match the command's stdout exactly n times, e.g. counting how many times a service was built.
func OutputNotContains ¶
OutputNotContains expects the command output not to contain a string.
func Recreated ¶
Recreated expects the services' containers to have been replaced by the step: none of the containers that existed before survived it.
func ReplicaNumbers ¶
ReplicaNumbers expects the service's containers to carry exactly the given replica numbers (the com.docker.compose.container-number label), locking which replicas survive a scale up or down.
func RunsOnPlatform ¶
RunsOnPlatform expects the service's container to have been created for the given platform (from its image manifest descriptor).
func ServiceHealthy ¶
ServiceHealthy expects every container of the service to report a healthy state from its healthcheck.
func ServiceNotCreated ¶
ServiceNotCreated expects the service to have no container at all — one-off containers included — e.g. after an action that must leave unrelated services untouched.
func ServiceScale ¶
ServiceScale expects the service to have exactly n long-lived containers.
func ServiceState ¶
ServiceState expects every long-lived container of the service to be in the given state (running, exited, restarting, …). One-off (run) containers are not considered; see OneOffState.
func StderrContains ¶
StderrContains expects the command's stderr to contain a string, e.g. a container's stderr stream relayed by up.
func StdoutContains ¶
StdoutContains expects the command's stdout to contain a string. Use it instead of OutputContains when the expected text could collide with progress noise on stderr (e.g. asserting a container's printed output).
func StdoutEmpty ¶
func StdoutEmpty() Check
StdoutEmpty expects the command to have written nothing to stdout, for commands that must stay silent on a no-op (progress goes to stderr).
func VolumeAbsent ¶
VolumeAbsent expects no volume with the given name on the engine, e.g. one a command must have removed.
func VolumeExists ¶
VolumeExists expects a volume with the given name to be present on the engine, e.g. one a command must have left untouched.
type CheckContext ¶
type CheckContext struct {
// contains filtered or unexported fields
}
CheckContext gives a check access to the step's result and to the project state captured before and after the step.
type Requirement ¶
Requirement checks an environment prerequisite; it returns a non-empty skip reason when the requirement is not met.
func EngineAPIVersionAtLeast ¶
func EngineAPIVersionAtLeast(minimum string) Requirement
EngineAPIVersionAtLeast requires a minimum Engine API version (for example "1.56"), the unit in which the daemon's features are versioned.
func EngineVersionAtLeast ¶
func EngineVersionAtLeast(major int) Requirement
EngineVersionAtLeast requires a minimum daemon major version.
type Scenario ¶
type Scenario struct {
// contains filtered or unexported fields
}
Scenario is a thin declarative layer over the e2e CLI helpers: a test reads as a compose.yaml, a sequence of steps (command + expected observables) and nothing else. Project naming, cleanup and failure diagnostics (transcript, project state, engine events, container logs) are handled by the framework.
Steps execute eagerly: each Step call runs its command, snapshots the project containers and evaluates the checks, failing the test with a full scenario report on the first unmet expectation.
func NewScenario ¶
func NewScenario(t *testing.T, intent string, opts ...ScenarioOption) *Scenario
NewScenario creates a scenario named after the test, with a unique project name, an isolated CLI instance and automatic `down` cleanup registered. The intent is a one-line statement of the behavior being locked, displayed in logs and failure reports.
func (*Scenario) CLI ¶
CLI exposes the underlying CLI instance for the rare setup logic the declarative layer doesn't cover.
func (*Scenario) Defer ¶
Defer registers a best-effort cleanup action executed after the project is taken down, e.g. removing images the scenario pulled.
func (*Scenario) Dir ¶
Dir returns the project directory the scenario runs from — the temporary copy of testdata/<TestName>/ — for actions that exchange files with the host (e.g. cp). It is only valid for a scenario anchored to testdata.
func (*Scenario) Env ¶
Env sets environment variables applied to every subsequent step command (and interpolated in the compose model).
func (*Scenario) FromFile ¶
FromFile switches the scenario's compose file to another file of the anchored project directory — for scenarios whose intent is a model migration: steps before the switch ran the initial model, steps after it run the migrated one, against the same project.
func (*Scenario) FromRemote ¶
FromRemote switches the scenario's compose source to a remote reference handled by compose's remote loaders — a git URL or an oci:// artifact — with optional extra root flags (e.g. --insecure-registry) inserted before the subcommand on every subsequent step. Steps executed before the switch still run against the anchored testdata copy, which remains available through Dir() as the local content the remote was built from (a repository to commit, a project to publish).
func (*Scenario) NonNativePlatform ¶
NonNativePlatform returns a linux platform different from the daemon's, for scenarios exercising platform-pinned services without emulation.
func (*Scenario) Project ¶
Project returns the compose project name the scenario runs under, e.g. to Defer the removal of an image the project built.
func (*Scenario) Requires ¶
func (s *Scenario) Requires(reqs ...Requirement) *Scenario
Requires skips the scenario unless every requirement is met by the target environment.
type ScenarioOption ¶
type ScenarioOption func(*Scenario)
ScenarioOption customizes a Scenario at creation time.
func Serial ¶
func Serial() ScenarioOption
Serial disables the default parallel execution, for scenarios that mutate shared daemon state (e.g. removing images other tests may pull).