GenericContainer class

Any Docker image, started for a test: its environment, command, ports and files set with fluent methods, and a wait strategy that decides when it is ready.

start() pulls the image when it is missing, creates the container with the ports published on random free ports of the host (on the loopback interface), copies the files in, starts it, and returns when the wait strategy says it is ready; stop() removes it. Every container is labelled with the id of the test run, so the reaper removes it when the process dies without stopping it (see ContainerRuntime). As a @Container() field of a test class it is started once before the class's context and stopped after it.

The fluent methods return the container itself, as GenericContainer: on a module such as PostgresContainer write cascades (..withReuse(true)) to keep its own type.

// Redis, from the plain image: a log line says it is ready.
final redis = GenericContainer('redis:7.4-alpine')
    .withExposedPorts([6379])
    .waitingFor(Wait.forLogMessage(r'Ready to accept connections'));
await redis.start();
final url = 'redis://${redis.host}:${redis.mappedPort(6379)}';
// ...
await redis.stop();

Testcontainers (Java):

GenericContainer<?> redis = new GenericContainer<>("redis:7.4-alpine")
    .withExposedPorts(6379)
    .waitingFor(Wait.forLogMessage(".*Ready to accept connections.*", 1));
redis.start();
String host = redis.getHost();
Integer port = redis.getMappedPort(6379);
Implemented types
Implementers

Constructors

GenericContainer(String image)
A container of image (postgres:17, quay.io/keycloak/keycloak:26.8); nothing happens until start.

Properties

containerId → String
The container's id; throws before start.
no setteroverride
docker → DockerClient
The client of the daemon the container runs on.
no setteroverride
exposedPorts → List<int>
The container ports published with withExposedPorts.
no setteroverride
hashCode → int
The hash code for this object.
no setterinherited
host → String
The host the published ports are reached on: 127.0.0.1 for a local daemon.
no setteroverride
image → String
The image the container is created from.
final
isStarted → bool
Whether start succeeded and stop was not called since.
no setter
remaining → Duration
How long the strategy may still take; it is the container's startup timeout, less the time already spent.
no setteroverride
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
waitStrategy → WaitStrategy
The wait strategy, for modules that extend it.
no setter

Methods

baseUrl(int port, {String scheme = 'http'}) → String
scheme://host:port of the container's port: http unless scheme says otherwise.
execInContainer(List<String> command) → Future<DockerExecResult>
Runs command in the started container and waits for it.
getLogs() → Future<String>
Everything the container printed so far, standard output and error together.
inspect() → Future<DockerContainerState>
The container's state, as the daemon reports it now.
override
logs() → Stream<DockerLogLine>
The container's output from its start, following it until it stops.
override
mappedPort(int port) → int
The port on host that the container's port is published on; the port must be listed in withExposedPorts, and the container started.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
poll(String description, Future<bool> check(), {Duration interval = const Duration(milliseconds: 100)}) → Future<void>
Calls check every interval until it returns true.
override
start() → Future<void>
Pulls the image if it is missing, creates the container, copies the files in, starts it and waits until it is ready.
stop() → Future<void>
Removes the container (killing it when it still runs). A container that is not started, or was found again through withReuse, is left as it is.
toString() → String
A string representation of this object.
override
waitingFor(WaitStrategy strategy) → GenericContainer
Decides when the started container counts as ready: see Wait. By default Wait.forListeningPort().
withCommand(List<String> command) → GenericContainer
Replaces the image's default command (CMD) with command.
withCopyContent(Object content, String containerPath, {int mode = 420}) → GenericContainer
Creates the file containerPath with content (a String or bytes) in the container before it starts.
withCopyFile(String hostPath, String containerPath, {int mode = 420}) → GenericContainer
Copies the file at hostPath to containerPath in the container before it starts. A relative hostPath starts at the working directory (the package, under dart test); the file is read at start. mode is the permission (0644 by default, as 0x1A4).
withEntrypoint(List<String> entrypoint) → GenericContainer
Replaces the image's entry point with entrypoint.
withEnv(String name, String value) → GenericContainer
Sets the environment variable name.
withEnvironment(Map<String, String> variables) → GenericContainer
Sets several environment variables.
withExposedPorts(List<int> ports) → GenericContainer
Publishes the container's TCP ports on random free ports of the host; mappedPort says which.
withHealthCheck(List<String> test, {Duration interval = const Duration(seconds: 1), Duration timeout = const Duration(seconds: 3), int retries = 10}) → GenericContainer
Gives the container a health check, for Wait.forHealthcheck() and for images that define none: test is the command in exec form (['CMD-SHELL', 'pg_isready -U test']), run every interval; after retries failures the container is unhealthy.
withLabel(String name, String value) → GenericContainer
Adds the label name=value to the container.
withReuse(bool reuse) → GenericContainer
Keeps the container alive after the tests, for the next run to use again (off by default, and ignored when the CI environment variable is set).
withStartupTimeout(Duration timeout) → GenericContainer
How long the wait strategy may take (60 seconds by default); the image pull is not counted.

Operators

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