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

Upgrading to 1.1

Standalone formula acquire and release callbacks now run in the same dedicated guard process so cleanup can continue if the caller is killed. The body still runs in the caller. If your callbacks depend on process-local state or return resources restricted to the acquiring process, adapt them before upgrading. See Standalone resource lifecycles and the changelog.

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.