class

Testcontainers::DockerContainer

Inherits Reference < Object

DockerContainer is the main class for managing Docker containers in tests. It provides a fluent API to configure, start, stop, and interact with containers.

Example:

container = Testcontainers::DockerContainer.new("redis:latest")
  .with_exposed_port(6379)
  .with_env("REDIS_PASSWORD", "secret")

container.start
host = container.host
port = container.mapped_port(6379)

# ... run tests ...

container.stop
container.remove

Constructors

new(image : String)

Initializes a new DockerContainer.

  • image: The Docker image to use (e.g. "redis:latest")
Source

Instance methods

command
Source
command=(command : Array(String) | Nil)
Source
container_id

The container ID once created

Source
created_at

The creation timestamp

Source
dead?

Returns whether the container is dead.

Source
delete(force : Bool = false, volumes : Bool = false) : self

Alias for remove.

Source
entrypoint
Source
entrypoint=(entrypoint : Array(String) | Nil)
Source
env
Source
env=(env : Array(String))
Source
exec(cmd : Array(String)) : String

Executes a command in the container.

Returns the output from the command.

Source
exists?

Returns whether the container exists.

Source
exited?

Returns whether the container is stopped/exited.

Source
exposed_ports
Source
exposed_ports=(exposed_ports : Hash(String, Hash(String, String)))
Source
filesystem_binds
Source
filesystem_binds=(filesystem_binds : Array(String))
Source
first_mapped_port

Returns the first mapped port.

Source
get_env(key : String) : String | Nil

Returns an environment variable value from the container config.

Source
healthcheck
Source
healthcheck=(healthcheck : Docr::Types::HealthConfig | Nil)
Source
healthy?

Returns whether the container is healthy.

Source
host

Returns the container's host address.

Source
image
Source
image=(image : String)
Source
info

Returns the container's full inspect data.

Source
kill(signal : String = "SIGKILL") : self

Kills the container with the specified signal.

Source
labels
Source
labels=(labels : Hash(String, String))
Source
logs(stdout : Bool = true, stderr : Bool = true) : String

Returns the container's logs.

Source
mapped_port(port : Int32 | String) : Int32

Returns the mapped host port for the given container port.

Source
name

Container configuration properties

Source
name=(name : String | Nil)

Container configuration properties

Source
pause

Pauses the container.

Source
paused?

Returns whether the container is paused.

Source
port_bindings
Source
port_bindings=(port_bindings : Hash(String, Array(Docr::Types::PortBinding)))
Source
remove(force : Bool = false, volumes : Bool = false) : self

Removes/deletes the container.

Source
restart

Restarts the container.

Source
restarting?

Returns whether the container is restarting.

Source
running?

Returns whether the container is running.

Source
start

Starts the container.

This will:

  1. Pull the image if not present
  2. Create the container
  3. Start the container
  4. Execute the wait strategy (if any)

Returns self for method chaining.

Source
status

Returns the container's status string. Possible values: "created", "running", "paused", "restarting", "removing", "exited", "dead"

Source
stop(force : Bool = false) : self

Stops the container.

Source
stop!

Stops the container forcefully.

Source
supports_healthcheck?

Returns whether the container supports healthchecks.

Source
unpause

Unpauses the container.

Source
use

Starts the container, yields it to a block, then stops and removes it.

Source
volumes
Source
volumes=(volumes : Hash(String, Hash(String, String)))
Source
wait_for

Wait strategy: a Proc that receives the container and waits for readiness

Source
wait_for=(wait_for : Proc(DockerContainer, Nil) | Nil)

Wait strategy: a Proc that receives the container and waits for readiness

Source
wait_for_healthcheck(timeout : Int32 = 60, interval : Float64 = 0.5) : Bool

Waits for the container to be healthy.

Source
wait_for_http(path : String = "/", container_port : Int32 = 80, timeout : Int32 = 60, interval : Float64 = 0.5, status : Int32 = 200, https : Bool = false) : Bool

Waits for an HTTP endpoint to respond with the expected status code.

Source
wait_for_logs(matcher : Regex, timeout : Int32 = 60, interval : Float64 = 0.5) : Bool

Waits for the container's logs to match the given regex.

Source
wait_for_tcp_port(port : Int32, timeout : Int32 = 60, interval : Float64 = 0.5) : Bool

Waits for a TCP port to be open.

Source
wait_for_user_defined?

Returns whether the wait strategy was explicitly set by the user.

Source
with_command(cmd : Array(String)) : self

Sets the command to run in the container from an array.

Source
with_command(*parts : String) : self

Sets the command to run in the container.

Source
with_entrypoint(entrypoint : Array(String)) : self

Sets the entrypoint for the container from an array.

Source
with_entrypoint(*parts : String) : self

Sets the entrypoint for the container.

Source
with_env(key : String, value : String) : self

Sets a single environment variable.

Source
with_env(env : Hash(String, String)) : self

Sets environment variables from a Hash.

Source
with_env(env : Array(String)) : self

Sets environment variables from an array of "KEY=VALUE" strings.

Source
with_exposed_port(port : Int32 | String) : self

Adds a single exposed port to the container. The port will be mapped to a random host port.

Source
with_exposed_ports(ports : Array(Int32 | String)) : self

Adds multiple exposed ports from an array.

Source
with_exposed_ports(*ports : Int32 | String) : self

Adds multiple exposed ports to the container.

Source
with_filesystem_bind(host_path : String, container_path : String, mode : String = "rw") : self

Adds a filesystem bind mount.

Source
with_filesystem_binds(binds : Array(String)) : self

Adds multiple filesystem binds.

Source
with_fixed_exposed_port(container_port : Int32 | String, host_port : Int32) : self

Adds a fixed port mapping (container_port -> host_port).

Source
with_healthcheck(test : String | Array(String), interval : Float64 = 30.0, timeout : Float64 = 30.0, retries : Int32 = 3, shell : Bool = false, start_period : Float64 = 0.0) : self

Configures a healthcheck for the container.

Options:

  • test: Command to run (string or array)
  • interval: Seconds between checks (default: 30)
  • timeout: Seconds before check is considered hung (default: 30)
  • retries: Number of retries before unhealthy (default: 3)
  • shell: Whether to use CMD-SHELL (default: false)
Source
with_label(key : String, value : String) : self

Adds a single label.

Source
with_labels(labels : Hash(String, String)) : self

Adds labels to the container.

Source
with_name(name : String) : self

Sets the container name.

Source
with_volume(volume : String) : self

Adds a single volume.

Source
with_volumes(volumes : Hash(String, Hash(String, String))) : self

Adds volumes.

Source
with_wait_for

Sets a custom wait strategy block. The block receives the container instance and should block until the container is ready.

Source
with_wait_for_healthcheck(timeout : Int32 = 60, interval : Float64 = 0.5) : self

Sets the wait strategy to wait for the healthcheck.

Source
with_wait_for_http(path : String = "/", container_port : Int32 = 80, timeout : Int32 = 60, interval : Float64 = 0.5, status : Int32 = 200, https : Bool = false) : self

Sets the wait strategy to wait for an HTTP endpoint.

Source
with_wait_for_logs(matcher : Regex, timeout : Int32 = 60, interval : Float64 = 0.5) : self

Sets the wait strategy to wait for a specific log message.

Source
with_wait_for_tcp_port(port : Int32, timeout : Int32 = 60, interval : Float64 = 0.5) : self

Sets the wait strategy to wait for a TCP port.

Source
with_working_dir(working_dir : String) : self

Sets the working directory inside the container.

Source
working_dir
Source
working_dir=(working_dir : String | Nil)
Source