testcontainer

<p align="center">
  <img src="https://raw.githubusercontent.com/lupodevelop/testcontainer/main/assets/img/logo.png" alt="Pago, the paguro mascot, carrying a Docker container on his shell" width="220">
</p>

<h1 align="center">testcontainer</h1>

<p align="center">
  <a href="https://hex.pm/packages/testcontainer"><img src="https://img.shields.io/hexpm/v/testcontainer?color=ffaff3" alt="Hex Package"></a>
  <a href="https://hexdocs.pm/testcontainer/"><img src="https://img.shields.io/badge/hex-docs-ffaff3" alt="Hex Docs"></a>
  <a href="https://github.com/lupodevelop/testcontainer/actions/workflows/test.yml"><img src="https://github.com/lupodevelop/testcontainer/actions/workflows/test.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/lupodevelop/testcontainer/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT"></a>
  <a href="https://gleam.run"><img src="https://img.shields.io/badge/made%20with-gleam-ffaff3?logo=gleam" alt="Made with Gleam"></a>
</p>

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

```gleam
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](https://hex.pm/packages/testcontainer_formulas))
  for ready-to-use Postgres / Redis / MySQL / RabbitMQ / Mongo with typed
  connection records
- 🛠 **Dockerfile build-on-test** ([testcontainer_dockerfile](https://hex.pm/packages/testcontainer_dockerfile)):
  build custom images from a `Dockerfile` at test time and use them as formulas
- 🧱 **Compose stacks** ([testcontainer_compose](https://hex.pm/packages/testcontainer_compose)):
  spin up `docker-compose.yml` stacks with typed services and guaranteed cleanup
- 🎨 **Formulas Builder** ([testcontainer_formulas_builder](https://github.com/lupodevelop/testcontainer_formulas_builder)):
  visual block editor + codegen, also accepts Dockerfile / compose uploads

## Install

```sh
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](docs/formulas.md#standalone-resource-lifecycles)
and the [changelog](CHANGELOG.md).

## Documentation

- [Quickstart](docs/quickstart.md): 5-minute tour of the API
- [Wait strategies](docs/wait-strategies.md): readiness probes that
  stay green
- [Formulas](docs/formulas.md): the customs paperwork that turns a raw
  container into a typed service
- [Formula Builder (Astro)](formula-builder/README.md): visual blocks + codegen
  for `testcontainer_formulas` snippets
- [Networks & Stacks](docs/networks-and-stacks.md): multi-container
  setups
- [Configuration](docs/configuration.md): env vars, host overrides,
  registry auth
- [Troubleshooting](docs/troubleshooting.md): common gotchas

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

## License

[MIT](LICENSE).