DockerContainer class

A Docker container managed by testcontainers-dart.

Instantiate with an image name and chain builder methods to configure it, then call start to create and start the container. Use use for an automatic start + stop with a try/finally guarantee.

Example:

await DockerContainer.use(
  DockerContainer('redis:7')
    .withExposedPorts([6379])
    .waitingFor(PortWaitStrategy(6379)),
  (container) async {
    final port = await container.exposedPort(6379);
    final client = RedisClient('localhost', port);
    // ... run tests
  },
);

Implemented types

WaitStrategyTarget

Constructors

DockerContainer(String image, {DockerClient? dockerClient}): Creates a DockerContainer for image.

Properties

command → Object?: The command override passed to withCommand, or null when the image's default entrypoint is used.
no setter
dockerClient → DockerClient: Returns the underlying DockerClient instance.
no setter
env → Map<String, String>: Environment variables injected into the container.
no setter
hashCode → int: The hash code for this object.
no setterinherited
image → String: The Docker image name (including optional tag) used to create the container.
final
kwargs → Map<String, Object?>: Extra Docker HostConfig fields passed to DockerClient.createContainer.
no setter
name → String?: The container name, or null when none was set.
no setter
network → Network?: The Network the container will be attached to, or null.
no setter
networkAliases → List<String>?: DNS aliases on network, or null.
no setter
ports → Map<int, int?>: Port map: container port → optional host port.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
status → String: The most recently refreshed container lifecycle status string.
no setteroverride
tmpfs → Map<String, String>: Tmpfs mounts: container path → options string.
no setter
volumes → Map<String, ({String bind, String mode})>: Volume bind mounts: host path → (bind: containerPath, mode: 'ro'|'rw').
no setter
wrappedContainer → Object: Returns this (the DockerContainer instance itself).
no setteroverride

Methods

configure() → void: Extension hook called by start just before the container is created.
containerHostIp() → Future<String>: Returns the host IP address through which this container is reachable.
override
containerInfo() → Future<ContainerInspectInfo?>: Returns detailed inspect information for this container.
override
copyFromContainer(String sourceInContainer, String destinationOnHost) → Future<void>: Downloads sourceInContainer from the container and writes it to destinationOnHost as a raw tar file.
copyIntoContainer(Transferable transferable, String destination, [int mode = kDefaultTransferMode]) → Future<void>: Copies transferable into the running container immediately.
exec(List<String> command) → Future<(int, Uint8List)>: Runs command inside the running container and returns its result.
override
execShell(String command) → Future<(int, Uint8List)>: Runs a shell command string inside the running container.
exposedPort(int port) → Future<int>: Returns the host port mapped to container port.
override
logs() → Future<(Uint8List, Uint8List)>: Returns the container's current log output as (stdout, stderr).
override
maybeEmulateAmd64() → DockerContainer: Conditionally adds platform: 'linux/amd64' emulation when running on an ARM64 host (e.g. Apple Silicon).
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
reload() → Future<void>: Refreshes the cached container status from the Docker daemon.
override
start() → Future<DockerContainer>: Creates and starts the container, then runs the wait strategy.
stop({bool force = true, bool deleteVolume = true}) → Future<void>: Removes the container.
toString() → String: A string representation of this object.
inherited
wait() → Future<int>: Blocks until the container stops and returns its exit code.
waitingFor(WaitStrategy strategy) → DockerContainer: Attaches a WaitStrategy that start will invoke after the container is running.
withBindPorts(int containerPort, [int? hostPort]) → DockerContainer: Maps containerPort to an optional fixed hostPort.
withCommand(Object command) → DockerContainer: Overrides the default command run by the container.
withCopyIntoContainer(Transferable transferable, String destination, int mode) → DockerContainer: Schedules transferable to be copied into the container at destination with Unix permission mode when start is called.
withEnv(String key, String value) → DockerContainer: Sets a single environment variable key to value.
withEnvFile(String envFile) → DockerContainer: Reads environment variables from a .env-style file and merges them into env.
withEnvs(Map<String, String> variables) → DockerContainer: Merges variables into the container's environment map.
withExposedPorts(List<int> exposedPorts) → DockerContainer: Exposes each port in exposedPorts with an ephemeral host port.
withKwargs(Map<String, Object?> kwargs) → DockerContainer: Merges kwargs into the extra Docker HostConfig fields.
withName(String name) → DockerContainer: Assigns a fixed name to the container.
withNetwork(Network network) → DockerContainer: Attaches the container to network.
withNetworkAliases(List<String> aliases) → DockerContainer: Sets DNS aliases for the container on its network.
withTmpfsMount(String containerPath, {String? size}) → DockerContainer: Adds a tmpfs mount at containerPath.
withVolumeMapping(String host, String container, String mode) → DockerContainer: Adds a volume bind mount from host to container with mode.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

splitCommand(String command) → List<String>: Splits a shell command string into tokens.
use<T>(DockerContainer container, Future<T> fn(DockerContainer)) → Future<T>: Starts container, runs fn with it, and stops it afterwards.