TestcontainerEx.Engine.Status (testcontainer_ex v0.6.0)

Query runtime status of container engines (Docker, Podman, Minikube, Colima) directly via their APIs or CLI.

Each function returns a normalized status map that downstream libraries can consume without needing to know the specifics of each engine.

Status map format

%{
  engine: :docker | :podman | :minikube | :colima,
  running: boolean(),
  version: String.t() | nil,
  api_version: String.t() | nil,
  os: String.t() | nil,
  arch: String.t() | nil,
  cpus: integer() | nil,
  memory_bytes: integer() | nil,
  hostname: String.t() | nil,
  kernel_version: String.t() | nil,
  storage_driver: String.t() | nil,
  logging_driver: String.t() | nil,
  cgroup_driver: String.t() | nil,
  cgroup_version: String.t() | nil,
  plugins: [String.t()],
  registries: [String.t()],
  server_time: DateTime.t() | nil,
  labels: %{String.t() => String.t()},
  experimental: boolean(),
  raw: map() | nil
}

Usage

# Quick check — is any container engine reachable?
TestcontainerEx.Engine.Status.reachable?()
# => true

# Full status of the detected engine
TestcontainerEx.Engine.Status.status()
# => %{engine: :docker, running: true, version: "27.0.3", ...}

# Query a specific engine
TestcontainerEx.Engine.Status.status(:podman)
# => %{engine: :podman, running: true, ...}

# Engine-specific details
TestcontainerEx.Engine.Status.colima_status()
# => %{running: true, profile: "default", cpu: 2, memory: 4294967296, ...}

TestcontainerEx.Engine.Status.minikube_status()
# => %{running: true, profile: "minikube", cpus: 2, memory: 4096, ...}

Summary

Types

engine()

status_map()

Functions

apple_container_status()

Returns detailed Apple Container status by querying the container CLI.

colima_status()

Returns detailed Colima status by querying the colima CLI.

disk_usage(base_url \\ nil)

Returns disk usage summary via the Docker Engine API /system/df endpoint.

engine_info(base_url \\ nil)

Returns Docker daemon info by querying the Docker Engine API /info endpoint.

engine_version(base_url \\ nil)

Returns the Docker Engine API version by querying the /version endpoint.

events(opts \\ [], base_url \\ nil)

Returns the events stream from the Docker Engine API as a Req response.

list_containers(opts \\ [], base_url \\ nil)

Lists all containers via the Docker Engine API.

list_images(opts \\ [], base_url \\ nil)

Lists all images via the Docker Engine API.

list_networks(base_url \\ nil)

Lists all networks via the Docker Engine API.

list_volumes(base_url \\ nil)

Lists all volumes via the Docker Engine API.

minikube_status()

Returns detailed Minikube status by querying the minikube CLI.

ping(base_url \\ nil)

Pings the Docker Engine API to check if it is responsive.

reachable?()

Returns true if any container engine (Docker, Podman, Minikube, Colima) is reachable and responding to API calls.

status(engine \\ nil)

Returns a normalized status map for the given engine, or the auto-detected engine when no argument is passed.

Types

engine()

@type engine() :: :docker | :podman | :minikube | :colima | :apple_container

status_map()

@type status_map() :: %{
  engine: engine(),
  running: boolean(),
  version: String.t() | nil,
  api_version: String.t() | nil,
  os: String.t() | nil,
  arch: String.t() | nil,
  cpus: integer() | nil,
  memory_bytes: integer() | nil,
  hostname: String.t() | nil,
  kernel_version: String.t() | nil,
  storage_driver: String.t() | nil,
  logging_driver: String.t() | nil,
  cgroup_driver: String.t() | nil,
  cgroup_version: String.t() | nil,
  plugins: [String.t()],
  registries: [String.t()],
  server_time: DateTime.t() | nil,
  labels: %{required(String.t()) => String.t()},
  experimental: boolean(),
  raw: map() | nil
}

Functions

apple_container_status()

@spec apple_container_status() :: map()

Returns detailed Apple Container status by querying the container CLI.

Returns a map with Apple Container-specific fields:

%{
  running: boolean(),
  version: String.t() | nil,
  kernel_version: String.t() | nil,
  cpus: integer() | nil,
  memory_bytes: integer() | nil
}

colima_status()

@spec colima_status() :: map()

Returns detailed Colima status by querying the colima CLI.

Returns a map with Colima-specific fields:

%{
  running: boolean(),
  profile: String.t(),
  colima_version: String.t() | nil,
  socket_path: String.t() | nil,
  kubernetes: boolean(),
  cpu: integer() | nil,
  memory_bytes: integer() | nil,
  disk_bytes: integer() | nil,
  arch: String.t() | nil,
  runtime: String.t() | nil,
  network_address: String.t() | nil,
  raw: String.t()
}

disk_usage(base_url \\ nil)

@spec disk_usage(String.t() | nil) :: {:ok, map()} | {:error, term()}

Returns disk usage summary via the Docker Engine API /system/df endpoint.

engine_info(base_url \\ nil)

@spec engine_info(String.t() | nil) :: {:ok, map()} | {:error, term()}

Returns Docker daemon info by querying the Docker Engine API /info endpoint.

This works for Docker and Podman (which both implement the Docker Engine API).

engine_version(base_url \\ nil)

@spec engine_version(String.t() | nil) :: {:ok, map()} | {:error, term()}

Returns the Docker Engine API version by querying the /version endpoint.

events(opts \\ [], base_url \\ nil)

@spec events(
  keyword(),
  String.t() | nil
) :: {:ok, reference()} | {:error, term()}

Returns the events stream from the Docker Engine API as a Req response.

Options:

:since — show events since this timestamp
:until — show events until this timestamp
:filters — map of event filters

Returns {:ok, reference()} on success.

list_containers(opts \\ [], base_url \\ nil)

@spec list_containers(
  keyword(),
  String.t() | nil
) :: {:ok, [map()]} | {:error, term()}

Lists all containers via the Docker Engine API.

Options:

:all — include stopped containers (default: false)
:limit — maximum number of containers to return
:filters — map of label filters

list_images(opts \\ [], base_url \\ nil)

@spec list_images(
  keyword(),
  String.t() | nil
) :: {:ok, [map()]} | {:error, term()}

Lists all images via the Docker Engine API.

Options:

:all — include intermediate images (default: false)
:filters — map of filters

list_networks(base_url \\ nil)

@spec list_networks(String.t() | nil) :: {:ok, [map()]} | {:error, term()}

Lists all networks via the Docker Engine API.

list_volumes(base_url \\ nil)

@spec list_volumes(String.t() | nil) :: {:ok, map()} | {:error, term()}

Lists all volumes via the Docker Engine API.

minikube_status()

@spec minikube_status() :: map()

Returns detailed Minikube status by querying the minikube CLI.

Returns a map with Minikube-specific fields:

%{
  running: boolean(),
  profile: String.t(),
  minikube_version: String.t() | nil,
  cpus: integer() | nil,
  memory_mb: integer() | nil,
  disk_mb: integer() | nil,
  driver: String.t() | nil,
  container_runtime: String() | nil,
  kubernetes_version: String.t() | nil,
  apiserver: boolean(),
  raw: map()
}

ping(base_url \\ nil)

@spec ping(String.t() | nil) :: :ok | {:error, term()}

Pings the Docker Engine API to check if it is responsive.

reachable?()

@spec reachable?() :: boolean()

Returns true if any container engine (Docker, Podman, Minikube, Colima) is reachable and responding to API calls.

status(engine \\ nil)

@spec status(engine() | nil) :: status_map()

Returns a normalized status map for the given engine, or the auto-detected engine when no argument is passed.

Returns %{engine: nil, running: false} when the engine is not available.