Why it exists
The JVM has Testcontainers. A linuxX64 test binary has nothing, so native suites usually start their services from a shell script before Gradle and read an address from the environment. That works until a test needs to break the broker — then it breaks it for the whole suite, and ends up behind a switch CI never sets.
kontainer is the missing piece: a Docker client that runs inside the test process.
val db = Fixture.owned(listOf("../compose/postgres.yml"), ports = mapOf("pg" to listOf(5432)))
try {
db.up()
db.awaitReady("pg", 5432, Probe.postgres())
val url = "postgresql://127.0.0.1:${db.port("pg", 5432)}/postgres"
db.paused("pg", 5432, Probe.postgres()) {
// The database is frozen here: connections open, nothing answers.
}
// And back, answering again, on the same port.
} finally {
db.down()
}
What you get
- Owned and shared fixtures. An owned fixture has a project name no other process uses and ports of its own; a shared one keeps a fixed name, is reused between runs, and refuses faults.
- Readiness by protocol, through the published port: a Kafka ApiVersions request, Postgres, HTTP by path and status, or your own. A TCP connect is not readiness — the engine's proxy accepts it even for a paused container.
- Faults —
pause,stop,killand back, and the scopedpaused { }andstopped { }that put the service back and wait for it to answer again even when the block throws. - Cleanup —
down()removes containers, networks and volumes, and the nextupon the host removes owned fixtures whose owner process was killed. - The engine client on its own — containers by label,
inspect, lifecycle calls,execwith the exit code and both streams,logs, every failure as a type.
The compose file stays yours
The one thing kontainer asks of it is to publish each port through a variable named after the service and the port, with a default that keeps the file working for docker compose up by hand:
services:
pg:
image: postgres:18-alpine
environment: { POSTGRES_PASSWORD: kontainer }
ports: ["127.0.0.1:${KONTAINER_PORT_PG_5432:-5432}:5432"]
The chosen port is passed in before up, which is also what lets Kafka advertise it.
Install
Published for linuxX64 to the portfolio's Reposilite on every push to main:
repositories {
maven("https://reposilite.kotlin.website/snapshots") {
mavenContent { includeGroupAndSubgroups("io.github.youndie") }
}
}
kotlin {
sourceSets.getByName("linuxX64Test").dependencies {
implementation("io.github.youndie.kontainer:kontainer:0.1.0.<run>")
}
}
The latest is the last one in maven-metadata.xml. It needs a Docker Engine with API 1.44 or newer, its socket readable by the test process, and the docker compose v2 plugin — ubuntu-latest runners have all three.
An owned apache/kafka:4.3.1 broker, from up to its first ApiVersions answer, takes a median of 3.5 s on an ubuntu-latest runner. That is what one fault test with a broker of its own costs. kafkakn pauses and stops its own broker in the suite that gates every merge, and s3kn starts its own S3 server when no endpoint is given.
Limitations
- Only
linuxX64. The JVM target is planned; macOS and arm64 are not. - No containers described in Kotlin — a compose file is the description — and no image API.
- No network faults such as latency or loss: a service is paused, stopped or killed.
- A lost race for a port retries
upup to three times, and that path has no test, because the race cannot be provoked on demand.