testcontainer_dockerfile

Build custom Docker images from a Dockerfile and use them as typed formulas with testcontainer. Pago handles the build; you get the container.

testcontainer is a container runner: it does not build images. This package fills the build-on-test gap by shelling out to docker build and wrapping the resulting image in a Formula.

let cfg =
  testcontainer_dockerfile.new("./Dockerfile")
  |> testcontainer_dockerfile.with_context(".")
  |> testcontainer_dockerfile.with_build_arg("BUILD_VERSION", "dev")
  |> testcontainer_dockerfile.with_expose_port(port.tcp(3000))
  |> testcontainer_dockerfile.with_env("LOG_LEVEL", "info")
  |> testcontainer_dockerfile.with_wait(wait.health_check())

let assert Ok(formula) = testcontainer_dockerfile.formula(cfg)
use container <- testcontainer.with_formula(formula)
// the image is built once, the container is created from it,
// and torn down on scope exit.

Why use it

• 🛠 Build-on-test: real docker build driven from your test code, layers and all
• 🔒 Type-safe pipeline: with_* builders compose the resulting spec, applied after build
• 🩺 Validation upfront: missing files, invalid build-arg keys, and unsafe characters caught before invoking Docker
• ⏱ Configurable timeout: 10-minute default, override via with_timeout(ms)
• 📦 Plays with the ecosystem: builds images that flow into testcontainer.with_formula like any other formula

Install

gleam add testcontainer_dockerfile

API

Build configuration

• new(path) — start with a Dockerfile path
• with_context(cfg, path) — build context (default .)
• with_build_arg(cfg, key, value) — passed as --build-arg to docker build
• with_timeout(cfg, ms) — override the 10-minute build timeout

Container shape (applied AFTER build)

Mirror testcontainer/container builders, but on the built image:

• with_expose_port(cfg, port)
• with_env(cfg, key, value)
• with_label(cfg, key, value)
• with_wait(cfg, strategy)
• with_command(cfg, cmd) / with_entrypoint(cfg, ep)
• with_name(cfg, name) / with_network(cfg, name)

Lifecycle

• formula(cfg) -> Result(Formula(DockerImage), error.Error) — runs docker build eagerly; pass the returned Formula to testcontainer.with_formula.

Errors (testcontainer_dockerfile/error)

pub type Error {
  DockerNotFound
  DockerfileNotFound(path: String)
  BuildFailed(path: String, reason: String)
}

BuildFailed.reason includes full docker build output (stdout + stderr merged), so you see exactly which RUN step broke.

How it works

docker build --quiet --no-cache -f <path> [--build-arg ...] <context> is invoked via erlang:open_port with {spawn_executable, ...} (no shell, no escape risk). With --quiet, Docker prints only the final image ID on stdout — that's what formula/1 returns.

After build:

1. The image ID becomes a regular container.new(image_id) spec.
2. Any with_expose_port, with_env, with_wait etc. accumulated on DockerfileConfig are applied to that spec via a chain of transform functions.
3. The configured spec is wrapped in a Formula(DockerImage) that returns the image ID as the typed output.

When to use this vs alternatives

Workflow	Tool
Pre-built public image (postgres:16, redis:7)	testcontainer core, container.new
Custom image, pre-built in CI	testcontainer core with image tag
Custom image, built inline at test time	this package
docker-compose.yml orchestrating multiple services	testcontainer_compose

Development

gleam run -m testcontainer_dockerfile_dev   # Dev runner (needs Docker)
gleam test                                   # Unit tests (no Docker)
TESTCONTAINERS_INTEGRATION=true gleam test   # Integration tests (Docker required)

See also

• testcontainer — the core container runner
• testcontainer_formulas — pre-built formulas for Postgres / Redis / MySQL / RabbitMQ / Mongo
• testcontainer_compose — spin up docker-compose.yml stacks
• testcontainer_formulas_builder — visual builder + codegen, also accepts Dockerfile / compose uploads

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

License

MIT.