DockerClient class final

A client of the Docker Engine API, over the daemon's Unix socket (or tcp://) on dart:io: no package, no docker command.

It covers what a test needs: ping, version, imageExists, pullImage, createContainer, putFiles, startContainer, containerLogs, inspectContainer, exec, listContainers, stopContainer and removeContainer. A call the daemon rejects throws a DockerException with the daemon's message; a daemon that cannot be reached throws a DockerUnavailableException. The paths carry no API version, so the daemon answers in its current one.

Tests use GenericContainer and the modules built on it; use this class for what they do not cover.

final docker = await DockerClient.connect();
await docker.pullImage('redis:7.4-alpine');
final id = await docker.createContainer(
  const DockerContainerConfig(image: 'redis:7.4-alpine',
      exposedPorts: [6379]),
);
await docker.startContainer(id);
final state = await docker.inspectContainer(id);
print(state.mappedPort(6379)); // the random host port
await docker.removeContainer(id);
docker.close();

Testcontainers (Java): DockerClientFactory.lazyClient(), a docker-java DockerClient.

Constructors

DockerClient(DockerEndpoint endpoint)

A client of the daemon at endpoint; nothing connects until the first call.

Properties

endpoint → DockerEndpoint

The daemon this client talks to.

final

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

close() → void

Closes the connections to the daemon.

containerLogs(String id, {bool follow = false, int? tail}) → Stream<DockerLogLine>

What the container id prints, line by line, standard output and error together.

createContainer(DockerContainerConfig config, {String? name}) → Future<String>

Creates a container from config without starting it, and returns its id. With name it is called that; the daemon names it otherwise.

exec(String id, List<String> command) → Future<DockerExecResult>

Runs command in the running container id and waits for it: Testcontainers' execInContainer.

imageExists(String image) → Future<bool>

Whether image is in the daemon's local store.

inspectContainer(String id) → Future<DockerContainerState>

The state of the container id: whether it runs, its health, its published ports. Throws a DockerException (status 404) when it does not exist.

listContainers({List<String> labels = const [], bool all = false}) → Future<List<DockerContainerSummary>>

The containers with all of the labels (name=value, or just name); all includes the stopped ones.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

ping() → Future<void>

Checks that the daemon answers (GET /_ping).

pullImage(String image) → Future<void>

Downloads image from its registry, waiting for the end of the pull; its progress is ignored.

putFiles(String id, List<TarFile> files) → Future<void>

Copies files into the container id (created or running), the parent directories included: they are written as a tar archive and unpacked at the root.

removeContainer(String id, {bool force = true, bool volumes = true, Duration wait = const Duration(seconds: 10)}) → Future<void>

Removes the container id; force kills it first, volumes removes its anonymous volumes. A container that does not exist, or that the daemon is already removing (a container started with auto-remove goes away on its own once stopped), is not an error. Returns once the container is gone, or after wait if the daemon is still removing it.

startContainer(String id) → Future<void>

Starts the container id.

stopContainer(String id, {Duration? timeout}) → Future<void>

Stops the container id: its process gets SIGTERM, and SIGKILL after timeout (the daemon's default, 10 seconds, when null). A container that does not exist is not an error.

toString() → String

A string representation of this object.

inherited

version() → Future<Map<String, Object?>>

The daemon's version information (GET /version): Version, ApiVersion, Os, Arch...

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

connect({Map<String, String>? environment}) → Future<DockerClient>

Finds the daemon (DockerEndpoint.resolve) and checks it answers.

parseImage(String image) → (String, String?)

Splits an image reference into the name to pull and its tag: latest when none is given, none for a digest (name@sha256:...).