Public API for TestcontainerEx.
This module is a thin facade that delegates to the GenServer
(TestcontainerEx.Server) and domain modules.
Engine Selection
By default, TestcontainerEx auto-detects the container engine. You can explicitly select an engine in three ways (in order of precedence):
1. Runtime override (highest priority)
Use set_engine/1 to switch engines at runtime, per-process:
TestcontainerEx.set_engine(:podman)
TestcontainerEx.container_engine() # => :podmanTo reset back to auto-detection:
TestcontainerEx.clear_engine()2. Via start_link/1 option
TestcontainerEx.start_link(engine: :docker)3. Via CONTAINER_ENGINE environment variable
CONTAINER_ENGINE=docker mix testRuntime reconnection
Use reconnect/1 to switch engines on a running server. This stops all
tracked containers and re-initializes the connection:
TestcontainerEx.reconnect(engine: :podman)Supported engine values:
:auto— auto-detect (default):docker— Docker Desktop, Colima, or socket-based Docker:podman— Podman socket or container env:colima— Colima only:minikube— Minikube only:apple_container— Apple Container only
Summary
Functions
Returns container logs.
Convenience alias for start_container/2.
Convenience alias for start_containers/2.
Executes a command inside a running container.
Returns the latest Docker inspect result for a container ID.
Monitors a container until a predicate returns {:ok, value} or the timeout elapses.
Parses the default gateway IP from /proc/net/route content.
Convenience alias for start_container/2.
Convenience alias for start_containers/2.
Returns true when running inside a container (Docker, Podman, Kubernetes).
Starts multiple containers.
Stops a container and waits until Docker no longer reports it running.
Stops multiple containers.
Functions
Returns container logs.
Options include :stdout, :stderr, :timestamps, :tail, :since,
:until_time, and :follow.
Convenience alias for start_container/2.
Convenience alias for start_containers/2.
Executes a command inside a running container.
Returns the latest Docker inspect result for a container ID.
Monitors a container until a predicate returns {:ok, value} or the timeout elapses.
The predicate receives the latest inspected container and must return {:ok, value}
to succeed or {:error, reason} to retry.
Parses the default gateway IP from /proc/net/route content.
Returns {:ok, ip_string} or {:error, :no_default_route}.
Convenience alias for start_container/2.
Convenience alias for start_containers/2.
Returns true when running inside a container (Docker, Podman, Kubernetes).
Accepts optional overrides for the .dockerenv path, cgroup path,
Kubernetes secrets path, and Podman containerenv path
(useful for testing on non-Linux hosts).
Starts multiple containers.
Accepts a list of config builders and returns {:ok, containers} only when
all containers start successfully. On failure, returns {:error, results}
where results contains per-container {:ok, container} or {:error, reason}
entries in the same order as the input.
Stops a container and waits until Docker no longer reports it running.
Stops multiple containers.
Returns {:ok, results} with one result per container ID. Nonexistent
containers are treated as already stopped by the Docker API.