testcontainers_gleam

Gleam wrapper for the Elixir testcontainers library.

Provides functions to start and stop Docker containers in tests. Use testcontainers_gleam/container to build a container definition, then pass it to start_container to run it.

Example

import testcontainers_gleam
import testcontainers_gleam/container

let c =
  container.new("redis:7.4-alpine")
  |> container.with_exposed_port(6379)

let assert Ok(running) = testcontainers_gleam.start_container(c)
let id = container.container_id(running)
let assert Ok(port) = container.mapped_port(running, 6379)

let assert Ok(Nil) = testcontainers_gleam.stop_container(id)

Types

ContainerError

</>

Error returned by testcontainers operations.

pub type ContainerError {
  HttpError(status: Int)
  FailedToPullImage
  FailedToCreateContainer
  FailedToStartContainer
  FailedToGetContainer
  WaitStrategyFailed
  Unknown
}

Constructors

```
HttpError(status: Int)
```
HTTP error from the Docker API with the status code.
```
FailedToPullImage
```
Failed to pull the container image.
```
FailedToCreateContainer
```
Failed to create the container.
```
FailedToStartContainer
```
Failed to start the container.
```
FailedToGetContainer
```
Failed to inspect a running container.
```
WaitStrategyFailed
```
A wait strategy timed out or failed.
```
Unknown
```
An unexpected error from the Elixir library.

ContainerResult

</>

Result alias for testcontainers operations.

pub type ContainerResult(a) =
  Result(a, ContainerError)

Values

start_container

</>

pub fn start_container(
  container: container.Container,
) -> Result(container.Container, ContainerError)

Start a container and wait until it is ready.

Automatically starts the Testcontainers GenServer if it is not already running. Returns the started container on success, which can be queried with container.container_id and container.mapped_port.

Example

let c =
  container.new("redis:7.4-alpine")
  |> container.with_exposed_port(6379)

let assert Ok(running) = testcontainers_gleam.start_container(c)

start_link

</>

pub fn start_link() -> Result(Nil, ContainerError)

Start the Testcontainers GenServer.

This is called automatically by start_container, so you only need to call it directly if you want to manage the lifecycle yourself. Returns Ok(Nil) if the GenServer was started or is already running.

stop_container

</>

pub fn stop_container(
  container_id: String,
) -> Result(Nil, ContainerError)

Stop a running container by its container ID.

Example

let assert Ok(Nil) = testcontainers_gleam.stop_container(id)