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
• 🧱 Formulas Builder (testcontainer_formulas_builder): visual block editor + codegen for testcontainer_formulas snippets

Install

gleam add testcontainer

Documentation

• Quickstart: 5-minute tour of the API
• Wait strategies: readiness probes that stay green
• Formulas: the customs paperwork that turns a raw container into a typed service
• Formula Builder (Astro): visual blocks + codegen for testcontainer_formulas snippets
• Networks & Stacks: multi-container setups
• Configuration: env vars, host overrides, registry auth
• Troubleshooting: common gotchas

Full API docs: https://hexdocs.pm/testcontainer

License

MIT.