testcontainer - v1.0.2

testcontainer/container

Types

Container

opaque </>

A handle to a running Docker container. Returned by testcontainer.start/1. Carries the container id, gateway host, port mapping and keep-alive flag.

port_mapping is keyed by (container_port, protocol) - protocol is always "tcp" or "udp" - so TCP and UDP ports with the same number don’t collide.

pub opaque type Container

ContainerSpec

opaque </>

Immutable description of a container to be started. Build it via new/1 and the with_* modifiers, then pass to testcontainer.start/1 or testcontainer.with_container/2.

pub opaque type ContainerSpec

Volume

opaque </>

A volume mount applied to a container. Build with bind_mount/2, readonly_bind_mount/2, or tmpfs/1.

pub opaque type Volume

Values

bind_mount

</> 
pub fn bind_mount(
  host_path: String,
  container_path: String,
) -> Volume

Creates a read-write bind mount from host_path to container_path.

command

</> 
pub fn command(
  spec: ContainerSpec,
) -> option.Option(List(String))

entrypoint

</> 
pub fn entrypoint(
  spec: ContainerSpec,
) -> option.Option(List(String))

env

</> 
pub fn env(
  spec: ContainerSpec,
) -> List(#(String, cowl.Secret(String)))

expose_port

</> 
pub fn expose_port(
  spec: ContainerSpec,
  p: port.Port,
) -> ContainerSpec

Exposes a single container port to the host (host port assigned dynamically).

expose_ports

</> 
pub fn expose_ports(
  spec: ContainerSpec,
  ps: List(port.Port),
) -> ContainerSpec

Exposes multiple container ports to the host.

host

</> 
pub fn host(c: Container) -> String

Returns the host that the test runner should use to reach the container’s mapped ports (typically the bridge gateway IP, or the value of TESTCONTAINERS_HOST_OVERRIDE).

host_port

</> 
pub fn host_port(
  c: Container,
  p: port.Port,
) -> Result(Int, error.Error)

Returns the host port that maps to the given container port, or PortNotMapped if the port is not exposed.

id

</> 
pub fn id(c: Container) -> String

Returns the Docker container id.

image

</> 
pub fn image(spec: ContainerSpec) -> String

is_privileged

</> 
pub fn is_privileged(spec: ContainerSpec) -> Bool

keep

</> 
pub fn keep(c: Container) -> Bool

Whether this container should be kept alive after the test (TESTCONTAINERS_KEEP=true or start_and_keep/1).

labels

</> 
pub fn labels(spec: ContainerSpec) -> List(#(String, String))

mapped_url

</> 
pub fn mapped_url(
  c: Container,
  p: port.Port,
  scheme: String,
) -> Result(String, error.Error)

Builds a URL for the given container port using the configured scheme, host, and mapped host port (e.g. "http://127.0.0.1:32768").

name

</> 
pub fn name(spec: ContainerSpec) -> option.Option(String)

network

</> 
pub fn network(spec: ContainerSpec) -> option.Option(String)

new

</> 
pub fn new(image: String) -> ContainerSpec

Creates a new spec for the given image (e.g. "redis:7-alpine"). The default wait strategy is wait.none/0 (no wait) - most images need a real wait_for/2 (e.g. wait.log("ready")) to be reliable.

on_network

</> 
pub fn on_network(
  spec: ContainerSpec,
  network: String,
) -> ContainerSpec

Attaches the container to the named Docker network.

ports

</> 
pub fn ports(spec: ContainerSpec) -> List(port.Port)

readonly_bind_mount

</> 
pub fn readonly_bind_mount(
  host_path: String,
  container_path: String,
) -> Volume

Creates a read-only bind mount.

tmpfs

</> 
pub fn tmpfs(container_path: String) -> Volume

Creates an in-memory tmpfs mount at container_path.

volumes

</> 
pub fn volumes(spec: ContainerSpec) -> List(Volume)

wait_for

</> 
pub fn wait_for(
  spec: ContainerSpec,
  strategy: wait.WaitStrategy,
) -> ContainerSpec

Sets the readiness wait strategy. The default is “no wait”.

wait_strategy

</> 
pub fn wait_strategy(spec: ContainerSpec) -> wait.WaitStrategy

with_bind_mount

</> 
pub fn with_bind_mount(
  spec: ContainerSpec,
  host: String,
  container_path: String,
) -> ContainerSpec

Adds a read-write bind mount (host path → container path).

with_command

</> 
pub fn with_command(
  spec: ContainerSpec,
  cmd: List(String),
) -> ContainerSpec

Overrides the container’s CMD.

with_entrypoint

</> 
pub fn with_entrypoint(
  spec: ContainerSpec,
  ep: List(String),
) -> ContainerSpec

Overrides the container’s ENTRYPOINT.

with_env

</> 
pub fn with_env(
  spec: ContainerSpec,
  key: String,
  value: String,
) -> ContainerSpec

Adds an environment variable. The value is wrapped in a cowl.Secret internally; use with_secret_env/3 if you already have a Secret.

with_envs

</> 
pub fn with_envs(
  spec: ContainerSpec,
  pairs: List(#(String, String)),
) -> ContainerSpec

Adds multiple environment variables at once.

with_label

</> 
pub fn with_label(
  spec: ContainerSpec,
  key: String,
  value: String,
) -> ContainerSpec

Adds a label to the container.

with_name

</> 
pub fn with_name(spec: ContainerSpec, n: String) -> ContainerSpec

Assigns a fixed name to the container (otherwise Docker auto-generates one).

with_privileged

</> 
pub fn with_privileged(spec: ContainerSpec) -> ContainerSpec

Marks the container as privileged.

with_readonly_bind

</> 
pub fn with_readonly_bind(
  spec: ContainerSpec,
  host: String,
  container_path: String,
) -> ContainerSpec

Adds a read-only bind mount.

with_secret_env

</> 
pub fn with_secret_env(
  spec: ContainerSpec,
  key: String,
  value: cowl.Secret(String),
) -> ContainerSpec

Adds an environment variable whose value is already a cowl.Secret.

with_tmpfs

</> 
pub fn with_tmpfs(
  spec: ContainerSpec,
  path: String,
) -> ContainerSpec

Mounts an in-memory tmpfs at the given path inside the container.

with_volume

</> 
pub fn with_volume(
  spec: ContainerSpec,
  v: Volume,
) -> ContainerSpec

Adds an arbitrary Volume (built with bind_mount/2, tmpfs/1, …).

✨ Search Document