testcontainer/formula

Types

Formula

opaque </>

A Formula combines a ContainerSpec with a typed extraction function.

When testcontainer.with_formula/2 starts the container it calls extract on the running Container to produce a service-specific output type (e.g. PostgresContainer, RedisContainer).

Formulas are defined in the companion package testcontainer_formulas, not in this core package. The core only defines the type and the lifecycle entry point.

use pg <- testcontainer.with_formula(postgres.formula(config)) // pg has type PostgresContainer with .connection_url, .host, .port, …

pub opaque type Formula(output)

A StandaloneFormula manages a resource with its own acquire/release lifecycle, independent of a single Docker container. Use this for resources like docker-compose stacks that are not backed by a single container spec.

Unlike Formula, StandaloneFormula is generic in its error type so callers can surface domain-specific errors without mapping them into testcontainer/error.Error.

use stack <- testcontainer.with_standalone_formula(compose_formula)

pub opaque type StandaloneFormula(output, err)

Values

new

</>

pub fn new(
  spec: container.ContainerSpec,
  extract: fn(container.Container) -> Result(output, error.Error),
) -> Formula(output)

Create a Formula from a ContainerSpec and an extraction function. Called by formula modules (e.g. testcontainer_formulas/postgres).

new_standalone

</>

pub fn new_standalone(
  acquire: fn() -> Result(output, err),
  release: fn() -> Result(Nil, err),
) -> StandaloneFormula(output, err)

Create a StandaloneFormula from acquire and release functions. acquire is called once to obtain the resource; release is always called after the body finishes, even on a returned error or catchable panic. Both callbacks run in the same dedicated guard process, while the body runs in the caller. Return resources that the caller can use across processes. If the caller dies, a successful acquisition is released even when acquisition or release was already in progress. Failed acquisitions must clean up any partial resources themselves. VM termination prevents remaining cleanup.