The complete "what to run" for one container: the Docker create spec plus every run-time input the start orchestration needs (readiness conditions, files to copy in, lifecycle hooks, pull/reuse/retry policy). More...

#include <testcontainers/ContainerRequest.hpp>

Public Attributes
CreateContainerSpec	spec
	The Docker create body, fully translated: the image reference is already resolved/substituted, env entries are "KEY=VALUE", exposed ports are "6379/tcp" strings.
std::vector< ContainerPort >	exposed_ports
	The declared exposed ports in declaration order.
std::vector< CopyToContainer >	copy_to_sources
	Files / bytes copied into the container between create and start.
std::vector< std::uint16_t >	host_access_ports
	Host (test-process) ports the container must be able to reach via host.testcontainers.internal (see GenericImage::with_exposed_host_port).
std::vector< WaitFor >	waits
	Readiness conditions, run in order under one shared startup_timeout.
std::chrono::milliseconds	startup_timeout {std::chrono::seconds(60)}
std::optional< RegistryAuth >	registry_auth
	Explicit registry credentials for pulls.
ImagePullPolicy	pull_policy = ImagePullPolicy::Default
std::optional< std::chrono::seconds >	pull_max_age
	Age budget for the LOCAL image under ImagePullPolicy::Default: when set, the run pulls first if the local copy's Created timestamp is older than this — or cannot be read.
bool	reuse = false
	Opt-in container reuse; only effective when reuse is also enabled globally (see GenericImage::with_reuse for the full semantics).
std::vector< LifecycleHook >	created_hooks
	after create, before copy/start
std::vector< LifecycleHook >	starting_hooks
	after copy-to, before start
std::vector< LifecycleHook >	started_hooks
	after wait-until-ready
std::vector< LifecycleHook >	stopping_hooks
	fired by the Container at teardown
int	startup_attempts = 1
	create→start→wait attempts; values < 1 mean 1

Detailed Description

The complete "what to run" for one container: the Docker create spec plus every run-time input the start orchestration needs (readiness conditions, files to copy in, lifecycle hooks, pull/reuse/retry policy).

A plain copyable value, normally assembled by GenericImage::to_request() and consumed by run(). A caller with run-level needs (a custom DockerClient, a spec tweak no builder exposes) can edit or build one directly — the fields mirror the GenericImage builders one-to-one. If you build one by hand rather than via to_request(), you own the consistency of the port trio: exposed_ports (typed, declaration order), spec.exposed_ports (the rendered "6379/tcp" strings), and spec.published_ports (the explicit ephemeral bindings).

Member Data Documentation

◆ spec

CreateContainerSpec testcontainers::ContainerRequest::spec

The Docker create body, fully translated: the image reference is already resolved/substituted, env entries are "KEY=VALUE", exposed ports are "6379/tcp" strings.

Session/reuse labels are layered on by run() (they depend on the run, not the request).

◆ exposed_ports

std::vector<ContainerPort> testcontainers::ContainerRequest::exposed_ports

The declared exposed ports in declaration order.

The handle remembers them so Container::first_mapped_port() resolves the FIRST declared port; the rendered strings for the create body live in spec.exposed_ports.

◆ copy_to_sources

std::vector<CopyToContainer> testcontainers::ContainerRequest::copy_to_sources

Files / bytes copied into the container between create and start.

◆ host_access_ports

std::vector<std::uint16_t> testcontainers::ContainerRequest::host_access_ports

Host (test-process) ports the container must be able to reach via host.testcontainers.internal (see GenericImage::with_exposed_host_port).

When non-empty, run() starts the process-wide sshd sidecar, forwards these ports through it, and appends the alias's ExtraHosts entry to spec for this run.

◆ waits

std::vector<WaitFor> testcontainers::ContainerRequest::waits

Readiness conditions, run in order under one shared startup_timeout.

◆ startup_timeout

std::chrono::milliseconds testcontainers::ContainerRequest::startup_timeout {std::chrono::seconds(60)}

◆ registry_auth

std::optional<RegistryAuth> testcontainers::ContainerRequest::registry_auth

Explicit registry credentials for pulls.

When unset, credentials are auto-resolved from the Docker config for the image's registry.

◆ pull_policy

ImagePullPolicy testcontainers::ContainerRequest::pull_policy = ImagePullPolicy::Default

◆ pull_max_age

std::optional<std::chrono::seconds> testcontainers::ContainerRequest::pull_max_age

Age budget for the LOCAL image under ImagePullPolicy::Default: when set, the run pulls first if the local copy's Created timestamp is older than this — or cannot be read.

A missing image needs no pull here (create fetches it lazily), and Always makes this moot (it pulls regardless). Caveat: Created is the image's BUILD time, not the pull time, so an image built long ago re-pulls on every start even when the registry holds the same bytes.

◆ reuse

bool testcontainers::ContainerRequest::reuse = false

Opt-in container reuse; only effective when reuse is also enabled globally (see GenericImage::with_reuse for the full semantics).

◆ created_hooks

std::vector<LifecycleHook> testcontainers::ContainerRequest::created_hooks

after create, before copy/start

◆ starting_hooks

std::vector<LifecycleHook> testcontainers::ContainerRequest::starting_hooks

after copy-to, before start

◆ started_hooks

std::vector<LifecycleHook> testcontainers::ContainerRequest::started_hooks

after wait-until-ready

◆ stopping_hooks

std::vector<LifecycleHook> testcontainers::ContainerRequest::stopping_hooks

fired by the Container at teardown

◆ startup_attempts

int testcontainers::ContainerRequest::startup_attempts = 1

create→start→wait attempts; values < 1 mean 1

Public Attributes