# kontainer

> 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.

Page: https://kotlin.website/kontainer

## 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](https://github.com/youndie/kontainer) is the missing piece: a Docker client that runs
inside the test process.

```kotlin
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:

```yaml
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`:

```kotlin
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](https://reposilite.kotlin.website/snapshots/io/github/youndie/kontainer/kontainer/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](https://kotlin.website/kafkakn) pauses and stops its own broker in the suite that gates every merge, and
[s3kn](https://kotlin.website/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.
