View Source Testcontainers.Connection (testcontainers v1.1.1)
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
.
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)
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 fromexec_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 fromexec_create/2
).
Returns
:ok
if the command execution started successfully.{:error, reason}
on failure.
Examples
:ok = Testcontainers.Connection.exec_start("my_exec_id")
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.
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")
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()
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}
wherelogs
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")
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")