Testing Infrastructure

Relevant source files

• api/types/container/exec.go
• api/types/volume/create_request.go
• client/container_exec.go
• client/container_exec_test.go
• client/container_resize.go
• client/container_resize_test.go
• contrib/nnp-test/Dockerfile
• contrib/syscall-test/Dockerfile
• daemon/cluster/controllers/plugin/controller.go
• daemon/cluster/controllers/plugin/controller_test.go
• daemon/cluster/convert/service_test.go
• daemon/cluster/convert/volume.go
• daemon/cluster/convert/volume_test.go
• daemon/cluster/utils.go
• daemon/command/metrics.go
• daemon/graphdriver/graphtest/graphbench_unix.go
• daemon/graphdriver/graphtest/graphtest_unix.go
• daemon/graphdriver/graphtest/testutil.go
• daemon/graphdriver/graphtest/testutil_unix.go
• daemon/id.go
• daemon/internal/libcontainerd/remote/client_io_windows.go
• daemon/internal/libcontainerd/remote/client_linux.go
• daemon/internal/libcontainerd/remote/client_windows.go
• daemon/internal/metrics/plugin_unix.go
• daemon/internal/metrics/plugin_unsupported.go
• daemon/list_test.go
• daemon/pkg/plugin/backend_linux_test.go
• daemon/pkg/plugin/defs.go
• integration-cli/fixtures_linux_daemon_test.go
• integration/container/create_test.go
• integration/container/daemon_linux_test.go
• integration/container/diff_test.go
• integration/container/exec_linux_test.go
• integration/container/exec_test.go
• integration/container/inspect_test.go
• integration/container/ipcmode_linux_test.go
• integration/container/kill_test.go
• integration/container/links_linux_test.go
• integration/container/list_test.go
• integration/container/logs_test.go
• integration/container/mounts_linux_test.go
• integration/container/nat_test.go
• integration/container/pause_test.go
• integration/container/pidmode_linux_test.go
• integration/container/remove_test.go
• integration/container/rename_test.go
• integration/container/resize_test.go
• integration/container/restart_test.go
• integration/container/run_cgroupns_linux_test.go
• integration/container/run_linux_test.go
• integration/container/stats_test.go
• integration/container/stop_linux_test.go
• integration/container/stop_test.go
• integration/container/update_linux_test.go
• integration/container/update_test.go
• integration/container/wait_test.go
• integration/daemon/daemon_test.go
• integration/internal/container/container.go
• integration/internal/container/exec.go
• integration/internal/container/ns.go
• integration/internal/container/ops.go
• integration/internal/container/states.go
• integration/internal/requirement/requirement.go
• integration/plugin/authz/main_test.go
• integration/plugin/logging/logging_linux_test.go
• integration/plugin/logging/validation_test.go
• integration/plugin/volumes/mounts_test.go
• integration/service/plugin_test.go
• integration/service/testdata/TestDockerIngressChainPosition_docker_forward.golden
• integration/system/cgroupdriver_systemd_test.go
• integration/system/event_test.go
• vendor/github.com/moby/moby/api/types/container/exec.go
• vendor/github.com/moby/moby/client/container_exec.go
• vendor/github.com/moby/moby/client/container_resize.go

The Testing Infrastructure provides the mechanisms to validate Docker Engine functionality across multiple layers, from individual Go packages to full API and CLI workflows. It encompasses specialized test runners, a dedicated daemon management framework for integration testing, and a suite of helpers to simulate complex container operations.

Overview

The Docker testing framework is categorized into four primary levels of validation:

• Unit Tests: Fast, isolated tests for individual packages using standard Go testing.
• Integration Tests (API-level): Validates the Docker Engine API by making HTTP requests from a client to a managed test daemon. Located in the integration/ directory.
• Integration-CLI Tests: Legacy test suites that execute the docker binary to verify CLI behavior. Located in integration-cli/.
• Compatibility Tests: Validation against third-party client libraries like docker-py.

Test Architecture

The following diagram illustrates how tests are initiated and the infrastructure that supports their execution.

Test Execution Flow

Sources: integration-cli/check_test.go54-103 integration/container/create_test.go10-30 integration/internal/container/ops.go16-18 internal/testutil/daemon/daemon.go1-50

Integration Testing Framework

The modern integration suite (found in integration/) focuses on testing the Engine API directly using the official Go client.

Test Daemon Management

The testutil/daemon package provides the Daemon struct, which encapsulates a background dockerd process. This allows tests to spin up isolated Engine instances with specific configurations (e.g., custom storage drivers, experimental features, or user namespaces).

Key functions in testutil/daemon:

• daemon.New(t): Initializes a new daemon instance for a test integration/daemon/daemon_test.go39
• d.Start(t, args...): Launches the daemon process with provided CLI flags integration/daemon/daemon_test.go42
• d.Stop(t): Gracefully shuts down the daemon and cleans up resources integration/daemon/daemon_test.go40
• d.Restart(t, args...): Restarts the daemon, often used to test state persistence integration/container/daemon_linux_test.go115

Integration Test Helpers

Tests utilize a set of internal packages to simplify container and network manipulation:

• Container Ops: integration/internal/container provides functional options (ConfigOpt) to build container configurations integration/internal/container/ops.go17-18
• State Polling: The poll package (from gotest.tools) is used with helpers like container.IsInState to wait for asynchronous operations to complete integration/container/kill_test.go28 integration/container/stop_test.go15

Common Test Pattern

A typical integration test follows this lifecycle:

1. Setup: Call setupTest(t) to initialize the environment integration/container/create_test.go33
2. Configuration: Use container.Run or container.Create with options like WithImage, WithCmd, or WithRestartPolicy integration/container/stop_test.go28-32
3. Execution: Invoke API methods via apiClient (e.g., ContainerKill, ContainerStop) integration/container/kill_test.go78-80
4. Validation: Assert results and poll for expected state changes integration/container/kill_test.go83

Sources: integration/container/create_test.go32-71 integration/container/stop_test.go22-47 integration/internal/container/ops.go1-100 internal/testutil/daemon/daemon.go1-100

CLI Testing Infrastructure

Integration-CLI tests (legacy) focus on the docker binary. They use a suite-based approach where tests are grouped into classes like DockerCLIRunSuite or DockerDaemonSuite.

Execution Environment

• testEnv: A global execution environment that tracks the OSType, IsRootless status, and API versions integration/container/run_linux_test.go35-40
• icmd: Used to run shell commands and verify exit codes and output buffers integration/daemon/daemon_test.go29

CLI vs API Space Mapping

The following diagram bridges natural language test requirements to the specific code entities used in the CLI and API integration layers.

Sources: integration/container/stop_test.go40 integration/container/kill_test.go23 integration/container/daemon_linux_test.go115 integration/internal/container/ops.go17-50

Storage and Graph Driver Testing

The daemon/graphdriver/graphtest package provides a standardized test suite for storage drivers (e.g., overlay2, btrfs). This ensures that any graph driver implementation adheres to the required interface behaviors.

Graph Test Suite

• Driver Setup: GetDriver creates or retrieves a driver instance for testing daemon/graphdriver/graphtest/graphtest_unix.go62
• Validation Tests:
  • DriverTestCreateEmpty: Verifies new layers are empty daemon/graphdriver/graphtest/graphtest_unix.go84
  • DriverTestDeepLayerRead: Tests performance and correctness across many filesystem layers daemon/graphdriver/graphtest/graphtest_unix.go144
  • DriverTestDiffApply: Validates the export/import (diff) logic between layers daemon/graphdriver/graphtest/graphtest_unix.go174

Sources: daemon/graphdriver/graphtest/graphtest_unix.go27-174

Environment and Clean Utilities

Testing requires strict control over host resources to prevent interference between tests.

• Skip Logic: Tests extensively use skip.If to bypass platform-specific or requirement-specific tests (e.g., skipping Windows-only tests on Linux) integration/container/run_linux_test.go35 integration/container/create_test.go147
• Cleanup: Tests utilize t.Cleanup() and helper functions like container.Remove to ensure the daemon state is reset integration/container/create_test.go138 integration/container/mounts_linux_test.go52
• Resource Isolation: The daemon's RootDir is often set to a temporary directory to isolate filesystem changes integration/daemon/daemon_test.go49

Sources: integration/container/create_test.go147 integration/container/run_linux_test.go35-40 integration/daemon/daemon_test.go49-53 integration/container/mounts_linux_test.go52-57