testcontainer - v1.0.0

testcontainer

Values

copy_file_to

</> 
pub fn copy_file_to(
  c: container.Container,
  host_path: String,
  container_path: String,
) -> Result(Nil, error.Error)

Copies a file from the host filesystem into a running container. host_path must be an absolute path to a readable file on the host. container_path is the absolute destination path inside the container.

use _ <- result.try(testcontainer.copy_file_to(c, “/host/init.sql”, “/tmp/init.sql”))

exec

</> 
pub fn exec(
  c: container.Container,
  cmd: List(String),
) -> Result(exec.ExecResult, error.Error)

Executes a command inside a running container.

force_stop

</> 
pub fn force_stop(
  c: container.Container,
) -> Result(Nil, error.Error)

Stops and removes a container ignoring the keep flag. Useful to programmatically tear down containers that were started with start_and_keep/1 or under TESTCONTAINERS_KEEP=true.

logs

</> 
pub fn logs(
  c: container.Container,
) -> Result(String, error.Error)

Returns the combined stdout+stderr log output of a running container (full log).

logs_tail

</> 
pub fn logs_tail(
  c: container.Container,
  n: Int,
) -> Result(String, error.Error)

Like logs/1 but returns only the last n lines.

stack

</> 
pub fn stack(
  network_name: String,
  build: fn(network.Network) -> Result(output, error.Error),
) -> stack.Stack(output)

Builds a Stack(output) - a network plus a typed multi-container build function. See with_stack/2.

start

</> 
pub fn start(
  spec: container.ContainerSpec,
) -> Result(container.Container, error.Error)

Starts a container described by spec and returns it. The caller is responsible for calling stop/1 when done. For automatic cleanup, prefer with_container/2.

start_and_keep

</> 
pub fn start_and_keep(
  spec: container.ContainerSpec,
) -> Result(container.Container, error.Error)

Starts a container and forces the keep flag, so it will NOT be removed by stop/1 even if TESTCONTAINERS_KEEP=false. Useful for inspection and debugging from a REPL.

stop

</> 
pub fn stop(c: container.Container) -> Result(Nil, error.Error)

Stops and removes a container. When TESTCONTAINERS_KEEP is set (or the container was started via start_and_keep/1) the container is left running for manual inspection. Use force_stop/1 to tear it down regardless.

with_container

</> 
pub fn with_container(
  spec: container.ContainerSpec,
  body: fn(container.Container) -> Result(a, error.Error),
) -> Result(a, error.Error)

Starts a container, runs body/1, then stops and removes it. A linked guard process ensures cleanup also runs if the caller crashes.

use c <- testcontainer.with_container(spec)

with_container_mapped

</> 
pub fn with_container_mapped(
  spec: container.ContainerSpec,
  map_error: fn(error.Error) -> e,
  body: fn(container.Container) -> Result(a, e),
) -> Result(a, e)

Like with_container/2 but maps the library’s error type into a custom error type before propagating.

use c <- testcontainer.with_container_mapped( spec, fn(e) { MyError.Container(e) }, )

with_formula

</> 
pub fn with_formula(
  f: formula.Formula(output),
  body: fn(output) -> Result(a, error.Error),
) -> Result(a, error.Error)

Starts a container using a Formula, extracts the typed output, then calls body/1. Lifecycle and cleanup work exactly like with_container/2.

use pg <- testcontainer.with_formula(postgres.formula(config)) // pg :: PostgresContainer

with_network

</> 
pub fn with_network(
  name: String,
  body: fn(network.Network) -> Result(a, error.Error),
) -> Result(a, error.Error)

Creates a Docker network, runs body/1, then removes it. Cleanup runs even if body/1 returns an error. Re-export of network.with_network/2 for one-import ergonomics.

use net <- testcontainer.with_network(“test-net”)

with_stack

</> 
pub fn with_stack(
  s: stack.Stack(output),
  body: fn(output) -> Result(a, error.Error),
) -> Result(a, error.Error)

Creates the stack’s network, runs the stack’s build function to produce a typed output, then runs body/1 against that output. The network is torn down after body/1 returns. The recommended pattern is to let the stack provide a Network and nest with_container / with_formula calls inside body, so each container is cleaned up by its own guard before the network is removed:

use net <- testcontainer.with_stack( testcontainer.stack(“app-test-net”, fn(n) { Ok(n) }), ) use pg <- testcontainer.with_formula( postgres.new() |> postgres.on_network(net) |> postgres.formula(), ) // …

See testcontainer/stack.{Stack} for notes on advanced builders.

✨ Search Document