youndie@kotlin.website:~/src$ cat kontainer/README.md

kontainer

kotlin/native · docker · testing
Containers for Kotlin/Native tests: a test brings up the broker or database it needs from the compose file the repository already has, on ports of its own, waits until it answers its own protocol, and can pause or stop it mid-test without breaking anyone else's run.

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, kill and back, and the scoped paused { } and stopped { } 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 next up on the host removes owned fixtures whose owner process was killed.
  • The engine client on its own — containers by label, inspect, lifecycle calls, exec with 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 up up to three times, and that path has no test, because the race cannot be provoked on demand.