Returns a specification to start this module under a supervisor.

See Supervisor.

Creates a Docker network.

Networks allow containers to communicate with each other using hostnames. Use Container.with_network/2 to attach a container to a network.

Parameters

• network_name: The name of the network to create.
• name: The name of the Testcontainers GenServer (defaults to Testcontainers).

Returns

• {:ok, network_id} if the network is created successfully.
• {:ok, :already_exists} if the network already exists.
• {:error, reason} on failure.

Returns the host to use for connecting to the given container.

In standard mode, returns the same as get_host/0 (the Docker host). In container networking mode (DooD), returns the container's internal IP since mapped ports on the bridge gateway may be unreachable.

Returns the port to use for connecting to the given container on the specified internal port.

In standard mode, returns the host-mapped port (same as Container.mapped_port/2). In container networking mode (DooD), returns the internal port directly since we connect to the container's IP on the bridge network.

Removes a Docker network.

Parameters

• network_name: The name of the network to remove.
• name: The name of the Testcontainers GenServer (defaults to Testcontainers).

Returns

• :ok if the network is removed successfully.
• {:error, reason} on failure.

Starts the Testcontainers application.

This will NOT terminate when the calling process exits, for ex a task.

Starts a Docker Compose environment based on the provided configuration.

Parameters

• config: A %DockerCompose{} struct containing the configuration.

Returns

• {:ok, compose_env} if the compose environment starts successfully.
• {:error, reason} on failure.

Starts a new container based on the provided configuration, applying any specified wait strategies.

This function performs several steps:

1. Pulls the necessary Docker image.
2. Creates and starts a container with the specified configuration.
3. Registers the container with a reaper process for automatic cleanup, ensuring it is stopped and removed when the current process exits or in case of unforeseen failures.

Parameters

• config: A %Container{} struct containing the configuration settings for the container, such as the image to use, environment variables, bound ports, and volume bindings.

Examples

iex> config = Testcontainers.MySqlContainer.new()
iex> {:ok, container} = Testcontainers.start_container(config)

Returns

• {:ok, container} if the container is successfully created, started, and passes all wait strategies.
• An error tuple, such as {:error, reason}, if there is a failure at any step in the process.

Notes

• The container is automatically registered with a reaper process, ensuring it is stopped and removed when the current process exits, or in the case of unforeseen failures.
• It's important to specify appropriate wait strategies to ensure the container is fully ready for interaction, especially for containers that may take some time to start up services internally.

Starts the Testcontainers application.

This will terminate when the calling process exits, for ex a task.

Stops a running Docker Compose environment.

Parameters

• compose_env: A %ComposeEnvironment{} struct representing the running environment.

Returns

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

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")