testcontainers Namespace Reference

Namespaces
namespace	docker
namespace	modules
namespace	wait_for
	Readiness conditions: the alternative types a WaitFor can hold, plus the convenience factories (below) that build them.

Classes
class	ConnectionString
	Assembles a connection URL — scheme://[user[:password]@]host[:port][/database][?key=value&...] — percent-encoding every component that needs it. More...
class	Container
	A RAII handle to a running container, normally obtained from GenericImage::start(). More...
struct	ContainerPort
	A port exposed by a container, with its protocol. More...
struct	ContainerRequest
	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...
class	CopyToContainer
	A request to copy a host file, in-memory bytes, or a host directory tree into a container, mapping to a tar PUTed to PUT /containers/{id}/archive. More...
struct	Device
	A host device node mapped into the container (a HostConfig.Devices entry) — docker run --device parity. More...
struct	CreateContainerSpec
	The flat create-body DTO for POST /containers/create, shared between the builder layer (ContainerRequest renders into it) and the client — typed fields for every option the library surfaces, translated into the daemon's JSON in one place. More...
struct	NetworkIpamPool
	One IPAM address pool of a network — an IPAM.Config entry, both as sent by POST /networks/create (NetworkCreateSpec::ipam_pools) and as read back by GET /networks/{id} (NetworkInspect::ipam_pools). More...
struct	NetworkCreateSpec
	Options for POST /networks/create (richer than just name+labels). More...
struct	VolumeCreateSpec
	Options for POST /volumes/create. More...
struct	VolumeInspect
	The subset of GET /volumes/{name} we care about. More...
struct	VolumePruneResult
	The daemon's report from POST /volumes/prune. More...
struct	NetworkEndpoint
	One attached container's endpoint on a network (a Containers map entry in GET /networks/{id}). More...
struct	NetworkInspect
	The subset of GET /networks/{id} we currently care about. More...
struct	ImageInspect
	The subset of GET /images/{reference}/json we currently care about. More...
struct	PortBinding
	A single published port binding from a container inspect. More...
struct	ContainerSummary
	A subset of one entry from GET /containers/json (the list endpoint). More...
struct	HostConfigInspect
	The HostConfig subset echoed back by GET /containers/{id}/json — the typed create-side knobs, readable back so tests can assert a limit landed. More...
struct	ContainerInspect
	The subset of GET /containers/{id}/json we currently care about. More...
struct	Response
	An HTTP response from the Docker Engine API. More...
class	DockerClient
	A synchronous client for the Docker Engine HTTP API. More...
struct	TlsMaterials
	TLS material paths attached to a resolved endpoint — filled by DockerHost::resolve() when the active docker context stores them (~/.docker/contexts/tls/...). More...
class	DockerHost
	A resolved Docker daemon endpoint: where and how to reach the daemon. More...
struct	LogOptions
	Options for GET /containers/{id}/logs. More...
struct	ContainerLogs
	Combined stdout / stderr text retrieved from a container. More...
class	DockerComposeContainer
	A RAII handle to a running Docker Compose project. More...
class	Error
	Base class for all testcontainers-cpp exceptions. More...
class	DockerError
	Failure while talking to the Docker daemon (transport, HTTP, or API error). More...
class	NotFoundError
	The daemon replied 404: the referenced resource does not exist. More...
class	TransportTimeoutError
	A transport operation exceeded its deadline — the TransportTimeouts connect budget or per-operation io deadline (see docker/Timeouts.hpp), or an internal handshake budget (the Ryuk registration). More...
class	StartupTimeoutError
	A container/service did not become ready within the caller's startup / wait-strategy timeout. More...
struct	ExecOptions
	Options for running a command inside a container via exec. More...
struct	ExecResult
	The result of running a command inside a container via exec. More...
struct	ExecStreamResult
	The result of a deadline-bounded streaming exec (the overload taking a deadline): why output delivery ended, plus the exit code when the command had actually finished by then. More...
class	GenericBuildableImage
	A reusable, copyable description of an image to BUILD from a Dockerfile and a build context. More...
class	GenericImage
	A reusable, copyable description of a container to run: image reference, exposed ports, environment, command, labels, and readiness conditions. More...
class	Healthcheck
	A container HEALTHCHECK definition, mirroring Docker's create-body Healthcheck object. More...
class	Mount
	A single filesystem mount for a container, mapping to one entry of Docker's create-body HostConfig.Mounts array. More...
class	Network
	A RAII handle to a user-defined Docker network. More...
struct	RegistryAuth
	Credentials for a Docker registry, used to pull private images. More...
struct	RestartPolicy
	A daemon-side restart policy (HostConfig.RestartPolicy): when the container exits, the daemon itself restarts it. More...
struct	TtySize
	A pseudo-TTY's dimensions in character cells. More...
struct	Ulimit
	A process resource limit (HostConfig.Ulimits entry), e.g. {"nofile", 1024, 2048}. More...
class	Volume
	A RAII handle to a named Docker volume. More...

Typedefs
using	LogConsumer = std::function<bool(LogSource source, std::string_view data)>
	A streaming log consumer.
using	LifecycleHook = std::function<void(DockerClient&, const std::string&)>
	A lifecycle hook: receives the Docker client and the container id at a defined point in the container's lifecycle.
using	WaitFor
	A readiness condition: a closed sum of the small wait strategies above, dispatched with std::visit.

Enumerations
enum class	AdoptOwnership { Keep , RemoveOnDrop }
	Who removes an adopted container. More...
enum class	Proto { Tcp , Udp , Sctp }
	Transport protocol of a container port. More...
enum class	ImagePullPolicy { Default , Always }
	When to pull the image before creating the container. More...
enum class	DockerScheme { Unix , NamedPipe , Tcp , Https }
	Transport scheme of a resolved Docker daemon endpoint. More...
enum class	LogSource { Stdout , Stderr }
	Which stream a streamed log chunk came from. More...
enum class	FollowEnd { ConsumerStopped , StreamEnded , DeadlineExpired }
	Why a deadline-bounded log/output stream ended (the follow_logs overload taking a deadline reports this instead of blocking indefinitely). More...
enum class	ComposeClientKind { Local , Containerised , Auto }
	Which compose client drives the project. More...
enum class	MountType { Bind , Volume , Tmpfs }
	How a mount is sourced, mirroring Docker's HostConfig.Mounts[].Type. More...

Functions
bool	operator== (const ContainerPort &a, const ContainerPort &b)
bool	operator!= (const ContainerPort &a, const ContainerPort &b)
ContainerPort	tcp (std::uint16_t port)
	Build a TCP container port (e.g. tcp(6379)).
ContainerPort	udp (std::uint16_t port)
	Build a UDP container port.
ContainerPort	sctp (std::uint16_t port)
	Build an SCTP container port.
std::string	to_string (const ContainerPort &p)
	Format a container port the way Docker names it, e.g. "6379/tcp".
Container	run (const ContainerRequest &request)
	Create, start, and wait for a container described by request, returning a RAII handle that removes the container on destruction (unless the request reused a persistent container).
Container	run (DockerClient client, const ContainerRequest &request)
	As above, but on a caller-supplied client — for a custom daemon endpoint or tuned transport timeouts.
std::string	version ()
	Library version string — the full semver, including any prerelease suffix (e.g.
std::string	dependency_report ()
	Human-readable report of the versions of the bundled third-party dependencies (Boost/Beast, nlohmann_json, OpenSSL, libarchive).

Typedef Documentation

LogConsumer

using testcontainers::LogConsumer = std::function<bool(LogSource source, std::string_view data)>

A streaming log consumer.

Invoked for each decoded chunk of log output with the source stream and the chunk bytes (the string_view is valid only for the duration of the call — copy if you need to retain it). Return true to keep receiving, false to stop the stream early.

LifecycleHook

using testcontainers::LifecycleHook = std::function<void(DockerClient&, const std::string&)>

A lifecycle hook: receives the Docker client and the container id at a defined point in the container's lifecycle.

A hook that throws aborts start() for the *-starting/-started/-created points (the partial container is then cleaned up); a *-stopping hook that throws is swallowed (teardown is best-effort and must never propagate, especially from the destructor).

WaitFor

using testcontainers::WaitFor

Initial value:

 
std::variant<wait_for::None, wait_for::LogMessage, wait_for::Duration, wait_for::Exit,
             wait_for::Healthcheck, wait_for::Http, wait_for::Port, wait_for::Command>

A readiness condition: a closed sum of the small wait strategies above, dispatched with std::visit.

Copyable so it lives happily in a vector.

Enumeration Type Documentation

AdoptOwnership

enum class testcontainers::AdoptOwnership

strong

Who removes an adopted container.

No default on purpose: adopting a container this library did not create must state the ownership decision explicitly at the call site.

Enumerator
Keep	never remove it — it is someone else's container
RemoveOnDrop	force-remove it when the handle is destroyed

Proto

enum class testcontainers::Proto

strong

Transport protocol of a container port.

Enumerator
Tcp
Udp
Sctp

ImagePullPolicy

enum class testcontainers::ImagePullPolicy

strong

When to pull the image before creating the container.

Enumerator
Default	pull only if missing locally (lazy, on create 404)
Always	always pull before create (even if present locally)

DockerScheme

enum class testcontainers::DockerScheme

strong

Transport scheme of a resolved Docker daemon endpoint.

Enumerator
Unix	unix:///var/run/docker.sock
NamedPipe	npipe:////./pipe/docker_engine
Tcp	tcp:// or http://
Https	https:// (TLS)

LogSource

enum class testcontainers::LogSource

strong

Which stream a streamed log chunk came from.

Enumerator
Stdout
Stderr

FollowEnd

enum class testcontainers::FollowEnd

strong

Why a deadline-bounded log/output stream ended (the follow_logs overload taking a deadline reports this instead of blocking indefinitely).

Enumerator
ConsumerStopped	the consumer returned false
StreamEnded	the stream completed (the container stopped) or was reset
DeadlineExpired	the deadline passed while waiting for more output

ComposeClientKind

enum class testcontainers::ComposeClientKind

strong

Which compose client drives the project.

Enumerator
Local	host docker compose CLI (the default)
Containerised	docker compose inside a long-lived docker:cli container
Auto	probe local; fall back to containerised

MountType

enum class testcontainers::MountType

strong

How a mount is sourced, mirroring Docker's HostConfig.Mounts[].Type.

Enumerator
Bind	host path -> container path
Volume	named volume -> container path
Tmpfs	in-memory filesystem at the container path (no source)

Function Documentation

operator==()

bool testcontainers::operator== ( const ContainerPort & a, const ContainerPort & b )

inline

operator!=()

bool testcontainers::operator!= ( const ContainerPort & a, const ContainerPort & b )

inline

tcp()

ContainerPort testcontainers::tcp ( std::uint16_t port )

inline

Build a TCP container port (e.g. tcp(6379)).

udp()

ContainerPort testcontainers::udp ( std::uint16_t port )

inline

Build a UDP container port.

sctp()

ContainerPort testcontainers::sctp ( std::uint16_t port )

inline

Build an SCTP container port.

to_string()

std::string testcontainers::to_string ( const ContainerPort & p )

inline

Format a container port the way Docker names it, e.g. "6379/tcp".

run() [1/2]

Container testcontainers::run

(

const ContainerRequest &

request

)

Create, start, and wait for a container described by request, returning a RAII handle that removes the container on destruction (unless the request reused a persistent container).

Boots the crash-safety reaper and connects to the daemon from the environment (DOCKER_HOST etc.) — this is exactly what GenericImage::start() runs. Throws on failure, best-effort removing a container that was created but never became ready.

run() [2/2]

Container testcontainers::run	(	DockerClient	client,
		const ContainerRequest &	request )

As above, but on a caller-supplied client — for a custom daemon endpoint or tuned transport timeouts.

The reaper is booted on client's daemon (not the environment one); reapers are per-daemon, keyed by endpoint URL, so a second daemon used in the same process gets its own crash-safe reaper (two URL spellings of one daemon count as two endpoints — harmless, two reapers). The client is copied into the returned handle.

version()

std::string testcontainers::version

(

)

Library version string — the full semver, including any prerelease suffix (e.g.

"1.2.3" or "1.2.3-alpha.4").

dependency_report()

std::string testcontainers::dependency_report

(

)

Human-readable report of the versions of the bundled third-party dependencies (Boost/Beast, nlohmann_json, OpenSSL, libarchive).

Primarily a build/link smoke check that the whole toolchain is wired up. The OpenSSL line appears only in builds that link it (i.e. with TLS and/or host-port forwarding enabled — the default).