containers library

Containers in tests, for any image: Docker started from a test class or a test, wired to the application, and removed afterwards.

Import it in test files that use containers:

import 'package:spring_boot_starter_test/containers.dart';

What it offers:

  • @Testcontainers(), @Container() and @ServiceConnection() for test classes (the generator starts the containers before the context and removes them after it);
  • GenericContainer: any image, with withEnv, withCommand, withExposedPorts, withCopyFile, waitingFor (Wait) and withReuse;
  • the modules PostgresContainer and KeycloakContainer, which know their @ServiceConnection properties;
  • DockerClient: the Docker Engine API on dart:io, with no package, for what the containers do not cover.

It is a library of its own, not part of spring_boot_starter_test.dart: the annotation Container would clash with Flutter's widget of that name in widget tests, and the classes need dart:io (they do not exist on the web). Containers are removed by the test run, and by a reaper (Testcontainers' Ryuk) when it dies; see docs/testing.md.

Spring (Java): Testcontainers (@Testcontainers, @Container, GenericContainer, PostgreSQLContainer) and Spring Boot's @ServiceConnection.

Classes

Container
Marks a static field that holds a container the tests need: it starts once, before the class's context, and is removed after the last test.
DockerClient
A client of the Docker Engine API, over the daemon's Unix socket (or tcp://) on dart:io: no package, no docker command.
DockerContainerConfig
What a container is made of, as the daemon's POST /containers/create takes it.
DockerContainerState
What docker inspect says about a container, in the parts a test needs.
DockerContainerSummary
A container of the list GET /containers/json returns.
DockerEndpoint
Where the Docker daemon listens: a Unix socket or a TCP address.
DockerExecResult
The outcome of a command run in a container with DockerClient.exec.
DockerLogLine
One line a container printed.
GenericContainer
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.
HttpWaitStrategy
Waits for an HTTP answer: made by Wait.forHttp(path).
KeycloakContainer
Keycloak in a container in development mode, with an admin user and optionally a realm imported from a JSON export, ready for the security tests: the issuer URI of the realm is what an application's @ServiceConnection() receives.
PostgresContainer
PostgreSQL in a container, ready for a test: a database, a user and a password set through the image's environment, and a wait that outlasts the image's two-step start: a temporary server initialises the database and stops, then the real one starts, so the container is ready when database system is ready to accept connections was logged twice (the wait of Testcontainers' PostgreSQLContainer), the port accepts connections, and the server answers the protocol's first message through the published port.
ServiceConnection
Marks a Container field whose connection properties become properties of the test's context: PostgresContainer sets spring.datasource.url, username and password, KeycloakContainer the issuer URIs.
ServiceConnectionProperties
A container that can say how an application connects to it: the properties @ServiceConnection() puts into the test's context.
TarFile
A file to put into a tar archive: the path inside the container (absolute or relative to the extraction directory), its bytes and its permission bits.
TestContainers
The containers of a test class: what the generated code of a class with @Container() fields calls.
Testcontainers
Marks a test class that uses containers; optional, as in Spring.
Wait
The ready-made wait strategies.
WaitStrategy
Decides when a started container counts as ready for the test: a port that accepts connections, a log line, an HTTP answer, a health check.
WaitTarget
What a WaitStrategy can look at: the started container, the ports published for it and the time left to become ready.

Enums

DockerStream
The output channel a DockerLogLine was written to.

Functions

tarArchive(List<TarFile> files, {DateTime? modified}) → Uint8List
Writes files as a ustar archive, the format Docker's PUT /containers/{id}/archive unpacks.

Exceptions / Errors

ContainerLaunchException
A container that started but did not become ready: it exited, its health check failed, or its wait strategy timed out. The message ends with the last lines it printed.
DockerException
An error of the Docker daemon, or a failure to talk to it: the daemon's own message is message.
DockerUnavailableException
No Docker daemon could be reached: its socket does not exist, nothing listens on it, or the platform is not supported yet (Windows' named pipe).