View Source Testcontainers.Connection (testcontainers v1.0.0)

This module provides an abstraction for interacting with Docker containers.

It manages the lifecycle of Docker containers, including creating, starting, and stopping instances, as well as executing commands within running containers. Communication with the Docker daemon is handled through a GenServer, which maintains the state of the connection and executes commands asynchronously.

Examples

The following examples demonstrate basic usage:

# Start a new container
{:ok, container} = Testcontainers.Connection.start_container("my_container_id")

# Execute a command within a running container
result = Testcontainers.Connection.exec_create("my_container_id", ["ls"])

Notes

  • This module should be used as a singleton. It is started with the application and should not be manually restarted.
  • All interaction with containers should go through this module to ensure proper connection management and error handling.

Summary

Functions

Returns a specification to start this module under a supervisor.

Creates a Docker container based on the specified configuration.

Creates a new execution context in a running container and runs the specified command.

Retrieves detailed information about a specific exec command.

Initiates the execution of a previously created command in a running container.

Retrieves information about a specific container.

Pulls a Docker image.

Starts a previously created Docker container.

Starts the GenServer (if it's not already started), enabling the handling of Docker containers.

Retrieves the stdout logs from a specified container.

Stops a running container.

Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

create_container(container)

View Source

Creates a Docker container based on the specified configuration.

The container is not started automatically. Use start_container/1 to run it.

Parameters

  • container: A %Container{} struct containing the configuration for the new Docker container.

Returns

  • {:ok, container_id} if the container is successfully created.
  • {:error, reason} on failure.

Examples

config = %Container{image: "nginx:latest"}
{:ok, container_id} = Testcontainers.Connection.create_container(config)
Link to this function

exec_create(container_id, command)

View Source

Creates a new execution context in a running container and runs the specified command.

This function is used to execute a one-off command within the context of the container.

Parameters

  • container_id: The ID of the container, as a string.
  • command: A list of strings representing the command and its arguments to run in the container.

Returns

  • {:ok, exec_id} which is an identifier for the executed command, useful for further inspection or interaction.
  • {:error, reason} on failure.

Examples

{:ok, exec_id} = Testcontainers.Connection.exec_create("my_container_id", ["ls", "-la"])

Retrieves detailed information about a specific exec command.

It's particularly useful for obtaining the exit status and other related data after a command has been executed in a container.

Parameters

  • exec_id: A string representing the unique identifier of the executed command (obtained from exec_create/2).

Returns

  • {:ok, %{running: _, exit_code: _}} with information about running state and exit code.
  • {:error, reason} on failure.

Examples

{:ok, exec_info} = Testcontainers.Connection.exec_inspect("my_exec_id")

Initiates the execution of a previously created command in a running container.

This function is used after exec_create/2 to start the execution of the command within the container context.

Parameters

  • exec_id: A string representing the unique identifier of the command to be executed (obtained from exec_create/2).

Returns

  • :ok if the command execution started successfully.
  • {:error, reason} on failure.

Examples

:ok = Testcontainers.Connection.exec_start("my_exec_id")
Link to this function

get_container(container_id)

View Source

Retrieves information about a specific container.

This can be used to check the status, inspect the configuration, and gather other runtime information about the container.

Parameters

  • container_id: The ID of the container, as a string.

Returns

  • {:ok, %Testcontainers.Container{}} with detailed information about the container.
  • {:error, reason} on failure.

Examples

{:ok, %Testcontainers.Container{}} = Testcontainers.Connection.get_container("my_container_id")

Pulls a Docker image.

This function sends a request to the Docker daemon to pull an image from a Docker registry. If the image already exists locally, it will be skipped.

Parameters

  • image: A string representing the Docker image tag.

Examples

:ok = Testcontainers.Connection.pull_image("nginx:latest")

Returns

  • :ok if the image is successfully pulled.
  • {:error, reason} if there is a failure to pull the image.

Notes

  • This function requires that the Docker daemon is running and accessible.
  • Network issues or invalid image tags can cause failures.
Link to this function

start_container(container_id)

View Source

Starts a previously created Docker container.

Requires the container ID of a container that has been created but not yet started.

Parameters

  • container_id: The ID of the container to start, as a string.

Returns

  • :ok if the container starts successfully.
  • {:error, reason} on failure.

Examples

:ok = Testcontainers.Connection.start_container("my_container_id")
Link to this function

start_eager(options \\ [])

View Source

Starts the GenServer (if it's not already started), enabling the handling of Docker containers.

This function should typically be called at the start of your application to ensure the GenServer is running.

Parameters

  • options: (Optional) A list of options. This can be empty as the defaults are usually sufficient.

Returns

  • {:ok, pid} on successful start.
  • {:error, reason} on failure.

Examples

{:ok, pid} = Testcontainers.Connection.start_eager()
Link to this function

stdout_logs(container_id)

View Source

Retrieves the stdout logs from a specified container.

Useful for debugging and monitoring, this function collects the logs that have been written to stdout within the container.

Parameters

  • container_id: The ID of the container, as a string.

Returns

  • {:ok, logs} where logs is the content that has been written to stdout in the container.
  • {:error, reason} on failure.

Examples

{:ok, logs} = Testcontainers.Connection.stdout_logs("my_container_id")
Link to this function

stop_container(container_id)

View Source

Stops a running container.

This sends a stop command to the specified container. The Docker daemon terminates the container process gracefully.

Parameters

  • container_id: The ID of the container to stop, as a string.

Returns

  • :ok if the container stops successfully.
  • {:error, reason} on failure.

Examples

:ok = Testcontainers.Connection.stop_container("my_container_id")