testcontainer
The hermit-crab way to run Docker containers in your Gleam tests.
Meet Pago, your paguro mascot. He carries the container so you don’t have to.
A small, type-safe Gleam library for spinning up real Docker containers
from your tests and dev tooling. Start a Postgres, run a query,
shut it down. Typed lifecycle and automatic cleanup even if your test
process crashes (except abrupt VM termination, e.g. kill -9).
use redis <- testcontainer.with_container(
container.new("redis:7-alpine")
|> container.expose_port(port.tcp(6379))
|> container.wait_for(wait.log("Ready to accept connections")),
)
let assert Ok(host_port) = container.host_port(redis, port.tcp(6379))
// connect to 127.0.0.1:host_port
Why use it
- 🦀 Crash-safe: a linked guard process cleans containers up even
if your test panics
- 🔒 Type-safe lifecycle: opaque builders,
use syntax, errors
always carry context
- 🐚 Zero ceremony: defaults that work, env vars when you need them
- 🚀 Fast: talks to Docker over the Unix socket directly via
gen_tcp (no HTTP client to drag along)
- 📦 Formule (companion package)
for ready-to-use Postgres / Redis / MySQL / RabbitMQ / Mongo with typed
connection records
- 🛠 Dockerfile build-on-test (testcontainer_dockerfile):
build custom images from a
Dockerfile at test time and use them as formulas
- 🧱 Compose stacks (testcontainer_compose):
spin up
docker-compose.yml stacks with typed services and guaranteed cleanup
- 🎨 Formulas Builder (testcontainer_formulas_builder):
visual block editor + codegen, also accepts Dockerfile / compose uploads
Install
gleam add testcontainer
Documentation
Full API docs: https://hexdocs.pm/testcontainer
License
MIT.