A flexible, user-defined container specification with full lifecycle control.
CustomContainer lets users define any container configuration and then
manage it through a unified API — start, stop, restart, pause, inspect,
exec, logs, stats, file upload/download, and more.
Defining a custom container
alias TestcontainerEx.CustomContainer
alias TestcontainerEx.Container.Config
config =
CustomContainer.new("my-app:latest")
|> CustomContainer.with_exposed_port(8080)
|> CustomContainer.with_exposed_port(5432)
|> CustomContainer.with_env("DATABASE_URL", "postgres://localhost/mydb")
|> CustomContainer.with_volume("/host/data", "/app/data")
|> CustomContainer.with_cmd(["my-app", "start"])
|> CustomContainer.with_network("my-network")
|> CustomContainer.with_wait_strategy(
TestcontainerEx.Wait.http("/health", 8080, status_code: 200)
)Starting and controlling
# Start the container
{:ok, container} = TestcontainerEx.start_container(config)
# Execute a command inside
{:ok, output} = TestcontainerEx.exec(container.container_id, ["ls", "/app"])
# Stream logs
{:ok, logs} = TestcontainerEx.container_logs(container.container_id, tail: 100)
# Get resource usage stats
stats = TestcontainerEx.container_stats(container.container_id)
# Stop and remove
:ok = TestcontainerEx.stop_container(container.container_id)
:ok = TestcontainerEx.container_remove(container.container_id, force: true)Using with ExUnit
import TestcontainerEx.ExUnit
# Per-test container
container :my_app, CustomContainer.new("my-app:latest")Summary
Functions
Sets a callback to run after the container starts successfully.
Receives (custom_container, started_container_config, conn).
Returns the host and port for a given container port.
Returns a connection URL for common protocols.
Returns a connection URL with authentication.
Creates a custom container from an existing Config struct.
Creates a new custom container with the given image.
Returns a map of runtime information for a started container.
Sets whether the container should be auto-removed when stopped.
Sets the command to run in the container.
Adds a file to copy into the container at startup.
Sets CPU limit (fraction of a CPU core, e.g. 0.5 for half a core).
Sets DNS servers.
Sets the domain name.
Sets the entrypoint.
Sets an environment variable.
Sets multiple environment variables.
Adds an exposed port (random host port).
Adds multiple exposed ports.
Adds an extra host entry (hostname -> ip).
Adds a fixed port mapping (container_port -> host_port).
Sets the hostname inside the container.
Sets the container image.
Adds a label to the container.
Adds multiple labels.
Sets memory limit in bytes.
Sets the container name.
Adds a named volume mount.
Sets the network mode or network name.
Sets the network mode (e.g. "host", "bridge", "none").
Sets privileged mode.
Sets the pull policy.
Sets the restart policy (e.g. "always", "unless-stopped", "on-failure:5").
Sets the stop signal (e.g. "SIGTERM", "SIGKILL").
Sets the stop timeout in seconds.
Sets the user (UID or user:group) for the container.
Adds a bind mount (host path -> container path).
Adds multiple wait strategies.
Adds a wait strategy for container readiness.
Sets the working directory inside the container.
Types
@type t() :: %TestcontainerEx.CustomContainer{ after_start: (TestcontainerEx.Container.Config.t(), TestcontainerEx.Container.Config.t(), Req.Request.t() -> :ok | {:error, term()}), auto_remove: boolean(), config: TestcontainerEx.Container.Config.t(), labels: %{required(String.t()) => String.t()}, wait_strategies: [struct()] }
Functions
@spec after_start(t(), (t(), TestcontainerEx.Container.Config.t(), Req.Request.t() -> term())) :: t()
Sets a callback to run after the container starts successfully.
Receives (custom_container, started_container_config, conn).
@spec endpoint(TestcontainerEx.Container.Config.t(), integer()) :: {String.t(), integer()} | nil
Returns the host and port for a given container port.
@spec endpoint_url(TestcontainerEx.Container.Config.t(), integer(), String.t()) :: String.t() | nil
Returns a connection URL for common protocols.
Examples
iex> CustomContainer.endpoint_url(container, 5432, "postgres")
"postgres://localhost:5432"
iex> CustomContainer.endpoint_url(container, 6379, "redis")
"redis://localhost:6379"@spec endpoint_url( TestcontainerEx.Container.Config.t(), integer(), String.t(), keyword() ) :: String.t() | nil
Returns a connection URL with authentication.
@spec from_config(TestcontainerEx.Container.Config.t()) :: t()
Creates a custom container from an existing Config struct.
Creates a new custom container with the given image.
@spec runtime_info(TestcontainerEx.Container.Config.t()) :: map()
Returns a map of runtime information for a started container.
Sets whether the container should be auto-removed when stopped.
Sets the command to run in the container.
Adds a file to copy into the container at startup.
Sets CPU limit (fraction of a CPU core, e.g. 0.5 for half a core).
Sets DNS servers.
Sets the domain name.
Sets the entrypoint.
Sets an environment variable.
Sets multiple environment variables.
Adds an exposed port (random host port).
Adds multiple exposed ports.
Adds an extra host entry (hostname -> ip).
Adds a fixed port mapping (container_port -> host_port).
Sets the hostname inside the container.
Sets the container image.
Adds a label to the container.
Adds multiple labels.
Sets memory limit in bytes.
Sets the container name.
Adds a named volume mount.
Sets the network mode or network name.
Sets the network mode (e.g. "host", "bridge", "none").
Sets privileged mode.
Sets the pull policy.
Sets the restart policy (e.g. "always", "unless-stopped", "on-failure:5").
Sets the stop signal (e.g. "SIGTERM", "SIGKILL").
Sets the stop timeout in seconds.
Sets the user (UID or user:group) for the container.
Adds a bind mount (host path -> container path).
Adds multiple wait strategies.
Adds a wait strategy for container readiness.
Sets the working directory inside the container.