e2e

package
v5.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 3, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
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 added in v5.5.1 

func BuilderName(t testing.TB, base string) string

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 

func ComposeStandalonePath(t testing.TB) string

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 added in v5.5.1 

func ContainerdImageStore(t testing.TB, c *CLI) string

ContainerdImageStore requires the daemon to use the containerd image store.

func CopyFile 

func CopyFile(t testing.TB, sourceFile string, destinationFile string)

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 IsHealthy 

func IsHealthy(service string) func(res *icmd.Result) bool

func Lines 

func Lines(output string) []string

Lines split output into lines

func RequireServiceState 

func RequireServiceState(t testing.TB, cli *CLI, service string, state string)

RequireServiceState ensures that the container is in the expected state (running or exited).

Types

type Action added in v5.5.1 

type Action struct {
	// contains filtered or unexported fields
}

Action is a command a step executes: a compose command run against the scenario's project, or a raw docker command.

func ComposeCmd added in v5.5.1 

func ComposeCmd(args ...string) Action

ComposeCmd runs `docker compose <args>` against the scenario's compose file and project name.

func DockerCmd added in v5.5.1 

func DockerCmd(args ...string) Action

DockerCmd runs a raw `docker <args>` command.

func (Action) MayFail added in v5.5.1 

func (a Action) MayFail() Action

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) WithEnv added in v5.5.1 

func (a Action) WithEnv(kv ...string) Action

WithEnv adds environment variables to this action only.

func (Action) WithStdin added in v5.5.1 

func (a Action) WithStdin(input string) Action

WithStdin feeds the command's standard input, e.g. to answer an interactive prompt ("n\n").

func (Action) Within added in v5.5.1 

func (a Action) Within(timeout time.Duration) Action

Within bounds the command's execution time, for blocking commands whose termination is itself the expectation (e.g. `up --wait` on a service that must become healthy). Exceeding the timeout kills the command and fails the step.

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 NewCLI 

func NewCLI(t testing.TB, opts ...CLIOption) *CLI

NewCLI creates a CLI instance for running E2E tests.

func NewParallelCLI 

func NewParallelCLI(t *testing.T, opts ...CLIOption) *CLI

NewParallelCLI marks the parent test as parallel and returns a CLI instance suitable for usage across child tests.

func (*CLI) BaseEnvironment 

func (c *CLI) BaseEnvironment() []string

BaseEnvironment provides the minimal environment variables used across all Docker / Compose commands.

func (*CLI) MetricsSocket 

func (c *CLI) MetricsSocket() string

MetricsSocket get the path where test metrics will be sent

func (*CLI) NewCmd 

func (c *CLI) NewCmd(command string, args ...string) icmd.Cmd

NewCmd creates a cmd object configured with the test environment set

func (*CLI) NewCmdWithEnv 

func (c *CLI) NewCmdWithEnv(envvars []string, command string, args ...string) icmd.Cmd

NewCmdWithEnv creates a cmd object configured with the test environment set with additional env vars

func (*CLI) NewDockerCmd 

func (c *CLI) NewDockerCmd(t testing.TB, args ...string) icmd.Cmd

NewDockerCmd creates a docker cmd without running it

func (*CLI) NewDockerComposeCmd 

func (c *CLI) NewDockerComposeCmd(t testing.TB, args ...string) icmd.Cmd

NewDockerComposeCmd creates a command object for Compose, either in plugin or standalone mode (based on build tags).

func (*CLI) RunCmd 

func (c *CLI) RunCmd(t testing.TB, args ...string) *icmd.Result

RunCmd runs a command, expects no error and returns a result

func (*CLI) RunCmdInDir 

func (c *CLI) RunCmdInDir(t testing.TB, dir string, args ...string) *icmd.Result

RunCmdInDir runs a command in a given dir, expects no error and returns a result

func (*CLI) RunDockerCmd 

func (c *CLI) RunDockerCmd(t testing.TB, args ...string) *icmd.Result

RunDockerCmd runs a docker command, expects no error and returns a result

func (*CLI) RunDockerComposeCmd 

func (c *CLI) RunDockerComposeCmd(t testing.TB, args ...string) *icmd.Result

RunDockerComposeCmd runs a docker compose command, expects no error and returns a result

func (*CLI) RunDockerComposeCmdNoCheck 

func (c *CLI) RunDockerComposeCmdNoCheck(t testing.TB, args ...string) *icmd.Result

RunDockerComposeCmdNoCheck runs a docker compose command, don't presume of any expectation and returns a result

func (*CLI) RunDockerOrExitError 

func (c *CLI) RunDockerOrExitError(t testing.TB, args ...string) *icmd.Result

RunDockerOrExitError runs a docker command and returns a result

func (*CLI) ServicePublishedPort added in v5.5.1 

func (c *CLI) ServicePublishedPort(t testing.TB, project, service string, targetPort int) int

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.

func (*CLI) WaitForCmdResult 

func (c *CLI) WaitForCmdResult(
	t testing.TB,
	command icmd.Cmd,
	predicate func(*icmd.Result) bool,
	timeout time.Duration,
	delay time.Duration,
)

WaitForCmdResult try to execute a cmd until resulting output matches given predicate

func (*CLI) WaitForCondition 

func (c *CLI) WaitForCondition(
	t testing.TB,
	predicate func() (bool, string),
	timeout time.Duration,
	delay time.Duration,
)

WaitForCondition wait for predicate to execute to true

type CLIOption 

type CLIOption func(c *CLI)

CLIOption to customize behavior for all commands for a CLI instance.

func WithEnv 

func WithEnv(env ...string) CLIOption

WithEnv sets environment variables that will be passed to commands.

type Check added in v5.5.1 

type Check struct {
	// contains filtered or unexported fields
}

Check is a named observable expected to hold after a step.

func Eventually added in v5.5.1 

func Eventually(check Check, timeout time.Duration) Check

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 ExitCode added in v5.5.1 

func ExitCode(code int) Check

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 added in v5.5.1 

func FileAbsent(path string) Check

FileAbsent expects no file or directory to exist at the given host path, e.g. content a previous step wiped.

func FileContains added in v5.5.1 

func FileContains(path, sub string) Check

FileContains expects the host file at the given path to contain a string, e.g. a file copied out of a container.

func FileExists added in v5.5.1 

func FileExists(path string) Check

FileExists expects a non-empty file at the given host path, e.g. the output of an export command.

func ImageExists added in v5.5.1 

func ImageExists(ref string) Check

ImageExists expects an image with the given reference to be present in the local store.

func LabelSet added in v5.5.1 

func LabelSet(service, key string) Check

LabelSet expects every container of the service to carry a non-empty label.

func LabelUnchanged added in v5.5.1 

func LabelUnchanged(service, key string) Check

LabelUnchanged expects a service's label to have the same value as before the step.

func LabelsDistinct added in v5.5.1 

func LabelsDistinct(key string, services ...string) Check

LabelsDistinct expects the given services to carry pairwise-distinct values for a label.

func NotRecreated added in v5.5.1 

func NotRecreated(services ...string) Check

NotRecreated expects the services' containers to be exactly the ones that existed before the step (same container IDs).

func OneOffState added in v5.5.1 

func OneOffState(service, state string) Check

OneOffState expects every one-off (run) container of the service to be in the given state.

func OneOffsRemoved added in v5.5.1 

func OneOffsRemoved(service string) Check

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 added in v5.5.1 

func OneOffsUntouched(service string) Check

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 added in v5.5.1 

func OutputContains(sub string) Check

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 added in v5.5.1 

func OutputMatches(pattern string) Check

OutputMatches expects the regular expression to match the command's stdout, for expectations OutputContains cannot express (e.g. ordering).

func OutputMatchesCount added in v5.5.1 

func OutputMatchesCount(pattern string, n int) Check

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 added in v5.5.1 

func OutputNotContains(sub string) Check

OutputNotContains expects the command output not to contain a string.

func Recreated added in v5.5.1 

func Recreated(services ...string) Check

Recreated expects the services' containers to have been replaced by the step: none of the containers that existed before survived it.

func ReplicaNumbers added in v5.5.1 

func ReplicaNumbers(service string, numbers ...int) Check

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 added in v5.5.1 

func RunsOnPlatform(service, platform string) Check

RunsOnPlatform expects the service's container to have been created for the given platform (from its image manifest descriptor).

func ServiceHealthy added in v5.5.1 

func ServiceHealthy(service string) Check

ServiceHealthy expects every container of the service to report a healthy state from its healthcheck.

func ServiceNotCreated added in v5.5.1 

func ServiceNotCreated(service string) Check

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 added in v5.5.1 

func ServiceScale(service string, n int) Check

ServiceScale expects the service to have exactly n long-lived containers.

func ServiceState added in v5.5.1 

func ServiceState(service, state string) Check

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 added in v5.5.1 

func StderrContains(sub string) Check

StderrContains expects the command's stderr to contain a string, e.g. a container's stderr stream relayed by up.

func StdoutContains 

func StdoutContains(sub string) Check

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).

type CheckContext added in v5.5.1 

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 added in v5.5.1 

type Requirement func(t testing.TB, c *CLI) string

Requirement checks an environment prerequisite; it returns a non-empty skip reason when the requirement is not met.

func EngineVersionAtLeast added in v5.5.1 

func EngineVersionAtLeast(major int) Requirement

EngineVersionAtLeast requires a minimum daemon major version.

type Scenario added in v5.5.1 

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 added in v5.5.1 

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 added in v5.5.1 

func (s *Scenario) CLI() *CLI

CLI exposes the underlying CLI instance for the rare setup logic the declarative layer doesn't cover.

func (*Scenario) Defer added in v5.5.1 

func (s *Scenario) Defer(actions ...Action) *Scenario

Defer registers a best-effort cleanup action executed after the project is taken down, e.g. removing images the scenario pulled.

func (*Scenario) Dir added in v5.5.1 

func (s *Scenario) Dir() string

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 added in v5.5.1 

func (s *Scenario) Env(kv ...string) *Scenario

Env sets environment variables applied to every subsequent step command (and interpolated in the compose model).

func (*Scenario) NonNativePlatform added in v5.5.1 

func (s *Scenario) NonNativePlatform() string

NonNativePlatform returns a linux platform different from the daemon's, for scenarios exercising platform-pinned services without emulation.

func (*Scenario) Project added in v5.5.1 

func (s *Scenario) Project() string

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 added in v5.5.1 

func (s *Scenario) Requires(reqs ...Requirement) *Scenario

Requires skips the scenario unless every requirement is met by the target environment.

func (*Scenario) Step added in v5.5.1 

func (s *Scenario) Step(name string, action Action, checks ...Check) *Scenario

Step runs an action and asserts the expected observables. The command must succeed unless the action is marked MayFail. On the first unmet expectation the scenario fails with a transcript and project diagnostics.

type ScenarioOption added in v5.5.1 

type ScenarioOption func(*Scenario)

ScenarioOption customizes a Scenario at creation time.

func Serial added in v5.5.1 

func Serial() ScenarioOption

Serial disables the default parallel execution, for scenarios that mutate shared daemon state (e.g. removing images other tests may pull).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.