A Testcontainers-style library for Kotlin Multiplatform: JVM, macOS (arm64/x64), Linux (x64/arm64), Windows (mingwX64).
Common code talks to the Docker Engine API over a unix socket, a Windows named pipe or TCP;
there are no JVM dependencies (no docker-java). Everything is suspend.
GenericContainer("redis:7-alpine") {
withExposedPorts(6379)
waitingFor(Wait.forLogMessage(".*Ready to accept connections.*"))
}.use { redis ->
connect(redis.host, redis.getMappedPort(6379))
}
PostgreSQLContainer { databaseName = "app" }.use { pg ->
println(pg.jdbcUrl)
pg.execInContainer("psql", "-U", pg.username, "-c", "select 1")
}GenericContainer: TCP and UDP ports (random/fixed), env, labels, cmd/entrypoint, hostname, network mode (host,none, ...), extra hosts, DNS,withAccessToHost()(host.testcontainers.internal), platform, memory/CPU/shm limits, ulimits, capabilities, read-only rootfs, init, bind mounts, named volumes,volumesFrom, tmpfs, privileged mode, networks with aliases, andwithCreateContainerModifierfor the raw create body.- Lifecycle: startup checks (
isRunning,oneShot,minimumDuration), startup attempts,dependsOn, concurrentstartAll/stopAll, hooks (containerIsCreated,...Starting,...Started,...Stopping,...Stopped), reusable containers (withReuse()+testcontainers.reuse.enable=true). - Output:
logStream()/logLines()flows,withLogConsumer,followOutput,ToStringConsumer;awaitExit(). The library's own messages go toDocker.logger(log.level, defaultWARN). - Files: copy into a container (before or after start; bytes, host files/directories via
MountableFile, classpath resources on the JVM) and out of it (copyFileFromContainer,copyFilesFromContainer), binary-safe. execInContainer: user, env, working directory, stdin (closed afterwards, so the command sees EOF), optional timeout; waits for the real exit code however long the command runs.- Wait strategies:
forListeningPort(host side +/proc/net/tcpinside the container),forLogMessage(follows the output stream),forHttp/forHttps(port, status codes or a status predicate, body predicate, method, headers, basic auth, request body, read timeout; HTTPS withallowInsecure()on the JVM),forSuccessfulCommand,forHealthcheck,allOf, andwithStartupTimeouton any single strategy. Startup fails fast if the container exits; a timeout says what it waited for and the last reason it was not ready, followed by the container logs. - Images: pull policies (
defaultPolicy,alwaysPull,ageBased) with retries of transient failures, registry credentials from the docker CLI config (auths,credHelpers,credsStore,DOCKER_AUTH_CONFIG), name substitution for registry mirrors (hub.image.name.prefix), images built from a Dockerfile (ImageFromDockerfile, honouring.dockerignoreand<Dockerfile>.dockerignore). - Docker Compose:
ComposeContainer(below). - Cleanup through Ryuk (
testcontainers/ryuk), on JVM and Native alike. - Modules:
PostgreSQLContainer,RedisContainer.
Every suspending operation has a blocking twin with a Blocking suffix, for plain test functions or main():
startBlocking(), stopBlocking(), execInContainerBlocking(...), logsBlocking(), copyFileFromContainerBlocking(...),
useBlocking { }, startAllBlocking(...), Docker.isAvailableBlocking(). Don't call them from a coroutine.
@Test
fun redis() {
GenericContainer("redis:7-alpine") { withExposedPorts(6379) }.useBlocking { redis ->
connect(redis.host, redis.getMappedPort(6379))
}
}ComposeContainer runs a project with the docker compose CLI (or docker-compose) against the same daemon,
under a random project name, and waits for the services you declare:
ComposeContainer("src/test/resources/compose.yaml")
.withEnv("TAG", "16") // ${TAG} in the compose file
.withExposedService("db", 5432, Wait.forLogMessage(".*ready to accept connections.*", times = 2))
.withExposedService("api", 8080, Wait.forHttp("/health"))
.use { compose ->
val port = compose.getServicePort("api", 8080)
compose.getContainer("db").execInContainer("psql", "-U", "postgres", "-c", "select 1")
}Ports need not be published in the compose file: unpublished ones are forwarded through a socat ambassador
(alpine/socat, override with socat.container.image). getContainer("worker-2") reaches other replicas.
Also: profiles, withBuild(), withPull(...), withRemoveImages(...), volumes removed on stop() by default.
Ryuk removes the project's resources if the process dies.
Settings are read like in testcontainers-java: the environment variable TESTCONTAINERS_<KEY>
(ryuk.disabled → TESTCONTAINERS_RYUK_DISABLED), then ~/.testcontainers.properties.
TestcontainersConfig.set(key, value) overrides both from code.
| Key | Purpose |
|---|---|
tc.host (or TC_HOST) |
Testcontainers Desktop / Cloud endpoint, used first |
docker.host |
daemon, after DOCKER_HOST |
hub.image.name.prefix |
registry mirror for Docker Hub images, e.g. registry.corp/mirror/ |
pull.retries |
retries of transient pull failures (default 2) |
testcontainers.reuse.enable |
allow withReuse() (or TESTCONTAINERS_REUSE_ENABLE) |
log.level |
DEBUG, INFO, WARN (default), ERROR |
ryuk.disabled, ryuk.container.image, ryuk.container.privileged |
resource reaper |
host.override |
host for mapped ports |
docker.socket.override |
socket path to mount into Ryuk |
The daemon is found in this order: tc.host, DOCKER_HOST, docker.host, the docker CLI context
(DOCKER_CONTEXT, else currentContext in ~/.docker/config.json; DOCKER_CONFIG moves that directory),
then on Windows \\.\pipe\docker_engine, elsewhere well-known sockets (Docker Desktop, rootless, Colima,
OrbStack, Rancher, Podman). Docker.resolvedEndpoint.source says which one was used.
Registry credentials come from DOCKER_AUTH_CONFIG (the JSON of a config.json) or ~/.docker/config.json;
helpers are the docker-credential-<name> programs on PATH. Docker.registryCredentials and
Docker.imageNameSubstitutor replace either from code.
Maven coordinates live in gradle.properties (buildInfo.*), the plugin version in gradle/libs.versions.toml.
Modules are published with vanniktech/gradle-maven-publish-plugin:
./gradlew publishToMavenLocal./gradlew publishAndReleaseToMavenCentralMaven Central credentials and the signing key are read from ~/.gradle/gradle.properties and are never stored in
this repository. Publish from macOS: the Apple targets cannot be built elsewhere.
HTTPS wait strategies on native targets (JVM only), TLS for tcp:// (detected and reported, not supported), JS/Wasm targets.
On native targets the docker compose CLI call has no timeout.
./gradlew :testcontainers-core:jvmTest :testcontainers-core:macosArm64TestThe named-pipe transport is Win32 (CreateFileW/ReadFile/WriteFile) on mingwX64 and RandomAccessFile
on the JVM. src/mingwTest checks it against an in-process fake daemon; on a Windows machine with
Docker Desktop run ./gradlew :testcontainers-core:mingwX64Test. From macOS/Linux the test binary can be
cross-linked (linkDebugTestMingwX64) and run under wine (the named-pipe and unit tests only).
WindowsContainerTest (mingwX64 only) runs mcr.microsoft.com/windows/nanoserver against a daemon in
Windows-containers mode, e.g. GitHub's windows-2025 runner; the tag must match the host build
(TC_WINDOWS_TEST_IMAGE overrides it). It is skipped on Linux-containers daemons, and the Linux container
tests are skipped on Windows-containers daemons. Ryuk is not started for Windows daemons (it is a Linux image),
so cleanup relies on stop() / use {}.