A reusable, copyable description of a container to run: image reference, exposed ports, environment, command, labels, and readiness conditions. More...

#include <testcontainers/GenericImage.hpp>

Public Member Functions
	GenericImage (std::string image, std::string tag="latest")
	Construct from an image name and tag.
ImageInspect	inspect () const
	inspect(image(), tag()) — a structured snapshot of THIS config's image on the daemon.
GenericImage &	with_image (const std::string &reference)
	Replace the image reference with "name[:tag]" (tag defaults to "latest"), keeping every other configured option — the same parsing as from_reference.
GenericImage &	with_exposed_port (ContainerPort p)
GenericImage &	with_env (std::string key, std::string value)
GenericImage &	with_cmd (std::vector< std::string > cmd)
GenericImage &	with_entrypoint (std::vector< std::string > entrypoint)
GenericImage &	with_working_dir (std::string working_dir)
GenericImage &	with_user (std::string user)
GenericImage &	with_privileged (bool privileged=true)
GenericImage &	with_isolation (std::string isolation)
	Container isolation technology (HostConfig.Isolation) — Windows daemons only: "process" or "hyperv".
GenericImage &	with_tty (bool tty=true)
	Allocate a pseudo-TTY for the container (Tty=true).
GenericImage &	with_mount (Mount mount)
GenericImage &	with_copy_to (CopyToContainer source)
	Copy a host file, in-memory bytes, or a host directory tree into the container after it is created and before it is started.
GenericImage &	with_label (std::string key, std::string value)
GenericImage &	with_wait (WaitFor w)
GenericImage &	with_startup_timeout (std::chrono::milliseconds timeout)
GenericImage &	with_healthcheck (Healthcheck hc)
GenericImage &	with_network (std::string network)
	Join the container to a user-defined network (HostConfig.NetworkMode).
GenericImage &	with_network (const Network &network)
	Overload taking the Network handle directly — .with_network(net) instead of .with_network(net.name()).
GenericImage &	with_network_alias (std::string alias)
	Add a DNS alias for this container on its network (NetworkingConfig).
GenericImage &	with_static_ipv4 (std::string ip)
	Assign a fixed IPv4 address to this container on its network (NetworkingConfig endpoint IPAMConfig.IPv4Address).
GenericImage &	with_container_name (std::string name)
	Set an explicit container name (passed as ?name= on create).
GenericImage &	with_platform (std::string platform)
	Pin the create platform as a free-form "<os>/<arch>" string (e.g.
GenericImage &	with_registry_auth (RegistryAuth auth)
	Supply explicit registry credentials for pulling a private image.
GenericImage &	with_memory_limit (std::int64_t bytes)
	Set a hard memory limit in bytes (HostConfig.Memory).
GenericImage &	with_shm_size (std::int64_t bytes)
	Set the size of /dev/shm in bytes (HostConfig.ShmSize).
GenericImage &	with_ulimit (std::string name, std::int64_t soft, std::int64_t hard)
	Add a process resource limit (HostConfig.Ulimits), e.g.
GenericImage &	with_cap_add (std::string cap)
	Add a Linux capability to grant (HostConfig.CapAdd), e.g. "NET_ADMIN".
GenericImage &	with_cap_drop (std::string cap)
	Add a Linux capability to drop (HostConfig.CapDrop).
GenericImage &	with_extra_host (const std::string &host, const std::string &ip)
	Add an /etc/hosts entry (HostConfig.ExtraHosts) mapping host to ip.
GenericImage &	with_cpu_limit (double cpus)
	Cap the container at cpus CPUs' worth of time (HostConfig.NanoCpus) — the docker run --cpus knob, e.g.
GenericImage &	with_cpuset_cpus (std::string cpus)
	Pin the container to specific host CPUs (HostConfig.CpusetCpus), e.g.
GenericImage &	with_pids_limit (std::int64_t limit)
	Cap the number of processes in the container (HostConfig.PidsLimit); -1 lifts any daemon-default cap.
GenericImage &	with_restart_policy (RestartPolicy policy)
	Have the DAEMON restart the container when it exits (HostConfig.RestartPolicy), e.g.
GenericImage &	with_dns_server (std::string server)
	Add a DNS server for the container (HostConfig.Dns).
GenericImage &	with_dns_search (std::string domain)
	Add a DNS search domain (HostConfig.DnsSearch).
GenericImage &	with_dns_option (std::string option)
	Add a resolver option (HostConfig.DnsOptions), e.g. "ndots:2".
GenericImage &	with_sysctl (std::string key, std::string value)
	Set a namespaced kernel parameter for the container (HostConfig.Sysctls), e.g.
GenericImage &	with_device (std::string path_on_host, std::string path_in_container, std::string cgroup_permissions="rwm")
	Map a host device node into the container (HostConfig.Devices) — the docker run --device knob.
GenericImage &	with_exposed_host_port (std::uint16_t port)
	Expose a port of the HOST (the machine the tests run on) to this container: services listening on 127.0.0.1:<port> in the test process become reachable from inside the container at host.testcontainers.internal:<port>.
GenericImage &	with_create_body_patch (std::string json_object)
	Deep-merge a raw Docker /containers/create body fragment into the create body (RFC 7386 merge applied AFTER our typed fields, so it overrides them).
GenericImage &	with_image_pull_policy (ImagePullPolicy policy)
	Control whether the image is pulled before create.
GenericImage &	with_image_pull_policy (std::chrono::seconds max_age)
	Age-based pull: pull before create when the LOCAL image's Created timestamp is older than max_age — or cannot be read; a missing image is still fetched lazily by create itself.
GenericImage &	with_reuse (bool reuse=true)
	Enable container reuse.
GenericImage &	with_image_name_substitutor (std::function< std::string(const std::string &)> fn)
	Override how the image reference is rewritten before create.
GenericImage &	with_created_hook (LifecycleHook hook)
	Register a hook fired right after the container is created (id assigned), before any copy-to and before start.
GenericImage &	with_starting_hook (LifecycleHook hook)
	Register a hook fired after copy-to and immediately before the container is started.
GenericImage &	with_started_hook (LifecycleHook hook)
	Register a hook fired after the container is started AND has become ready (wait strategies satisfied), before the handle is returned.
GenericImage &	with_stopping_hook (LifecycleHook hook)
	Register a hook fired by the Container when it is being torn down: on an explicit stop()/remove(), or on destruction of an auto-removing handle, before the container is removed.
GenericImage &	with_startup_attempts (int n)
	Retry the whole create→start→wait sequence up to n times if an attempt fails (each retry creates a brand-new container).
const std::string &	image () const noexcept
const std::string &	tag () const noexcept
const std::vector< ContainerPort > &	exposed_ports () const noexcept
const std::vector< std::pair< std::string, std::string > > &	env () const noexcept
const std::vector< std::string > &	cmd () const noexcept
const std::vector< std::string > &	entrypoint () const noexcept
const std::optional< std::string > &	working_dir () const noexcept
const std::optional< std::string > &	user () const noexcept
bool	privileged () const noexcept
const std::optional< std::string > &	isolation () const noexcept
bool	tty () const noexcept
const std::vector< Mount > &	mounts () const noexcept
const std::vector< CopyToContainer > &	copy_to_sources () const noexcept
const std::vector< std::pair< std::string, std::string > > &	labels () const noexcept
const std::vector< WaitFor > &	waits () const noexcept
std::chrono::milliseconds	startup_timeout () const noexcept
const std::optional< Healthcheck > &	healthcheck () const noexcept
const std::optional< std::string > &	network () const noexcept
const std::vector< std::string > &	network_aliases () const noexcept
const std::optional< std::string > &	static_ipv4 () const noexcept
const std::optional< std::string > &	container_name () const noexcept
const std::optional< std::string > &	platform () const noexcept
const std::optional< RegistryAuth > &	registry_auth () const noexcept
const std::optional< std::int64_t > &	memory_limit () const noexcept
const std::optional< std::int64_t > &	shm_size () const noexcept
const std::vector< Ulimit > &	ulimits () const noexcept
const std::vector< std::string > &	cap_add () const noexcept
const std::vector< std::string > &	cap_drop () const noexcept
const std::vector< std::string > &	extra_hosts () const noexcept
const std::vector< std::uint16_t > &	exposed_host_ports () const noexcept
const std::string &	create_body_patch () const noexcept
ImagePullPolicy	image_pull_policy () const noexcept
const std::optional< std::chrono::seconds > &	pull_max_age () const noexcept
bool	reuse () const noexcept
const std::function< std::string(const std::string &)> &	image_name_substitutor () const noexcept
const std::vector< LifecycleHook > &	created_hooks () const noexcept
const std::vector< LifecycleHook > &	starting_hooks () const noexcept
const std::vector< LifecycleHook > &	started_hooks () const noexcept
const std::vector< LifecycleHook > &	stopping_hooks () const noexcept
int	startup_attempts () const noexcept
ContainerRequest	to_request () const
	Snapshot this builder into a self-contained ContainerRequest — the fully-translated create spec (resolved/substituted image reference, env joined to "KEY=VALUE"; exposed ports were already rendered as declared) plus every run-time input (waits, copy-to sources, hooks, pull/reuse/retry policy).
Container	start () const
	Create, start, and wait for a container from this image, returning a RAII handle that removes the container on destruction.

Static Public Member Functions
static GenericImage	from_reference (const std::string &reference)
	Construct from a full image reference "name[:tag]" (tag defaults to "latest"), e.g.
static bool	exists (const std::string &name, const std::string &tag="latest")
	True when the image <name>:<tag> is already present on the daemon — name and tag are separate, exactly like the constructor.
static ImageInspect	inspect (const std::string &name, const std::string &tag="latest")
	A structured snapshot of the image <name>:<tag> on the daemon (GET /images/{ref}/json): id, repo tags/digests, creation time, os / architecture, size, and the image config (labels, env, cmd, entrypoint, exposed ports, workdir, user).

Detailed Description

A reusable, copyable description of a container to run: image reference, exposed ports, environment, command, labels, and readiness conditions.

The with_* builders mutate in place and return *this by reference, so a named config can be configured incrementally and started many times — no consume-self, no use-after-move. A single unqualified overload chains on both a named lvalue and a temporary (GenericImage("redis","7.2").with_*()...).

The whole configuration is held directly in an embedded ContainerRequest request_ — create fields in request_.spec, the orchestration state (waits, copy-to sources, hooks, reuse, …) beside them — so a new option is added in one place (a setter + getter forwarding to request_) without a parallel private field and a hand-written copy in to_request(). Exposed ports are rendered into the spec as they are declared, keeping the typed/string/publish-all trio consistent by construction. Only the fields whose translation must wait until start() — the image reference (resolve

substitution) and env (pair → "KEY=VALUE"; the pair form backs the env() getter) — are kept as separate domain fields.

Constructor & Destructor Documentation

◆ GenericImage()

testcontainers::GenericImage::GenericImage	(	std::string	image,
		std::string	tag = "latest" )

inlineexplicit

Construct from an image name and tag.

Member Function Documentation

◆ from_reference()

GenericImage testcontainers::GenericImage::from_reference ( const std::string & reference )

static

Construct from a full image reference "name[:tag]" (tag defaults to "latest"), e.g.

for an externally-resolved reference. To run an image built by GenericBuildableImage, prefer its build(), which returns a GenericImage.

◆ exists()

bool testcontainers::GenericImage::exists	(	const std::string &	name,
		const std::string &	tag = "latest" )

static

True when the image <name>:<tag> is already present on the daemon — name and tag are separate, exactly like the constructor.

A purely local check (GET /images/{ref}/json), no registry is contacted. Useful to skip an expensive GenericBuildableImage::build() when a previous run already produced the image:

GenericImage img = GenericImage::exists("app", "v1")
                       ? GenericImage("app", "v1")
                       : app_buildable.build();

name must not embed a tag: for a full "name[:tag]" reference (or a digest), call DockerClient::image_exists directly. Note: presence says nothing about freshness — if the build inputs can change under the same tag, derive the tag from a hash of the inputs. Throws DockerError when the daemon cannot be reached or errors.

◆ inspect() [1/2]

ImageInspect testcontainers::GenericImage::inspect	(	const std::string &	name,
		const std::string &	tag = "latest" )

static

A structured snapshot of the image <name>:<tag> on the daemon (GET /images/{ref}/json): id, repo tags/digests, creation time, os / architecture, size, and the image config (labels, env, cmd, entrypoint, exposed ports, workdir, user).

A purely local lookup, no registry is contacted; name and tag are separate, exactly like exists. Throws DockerError if the image is absent (NotFoundError) or the daemon cannot be reached. For a full "name[:tag]" reference, an image ID, or a digest, call DockerClient::inspect_image directly.

◆ inspect() [2/2]

ImageInspect testcontainers::GenericImage::inspect ( ) const

inspect(image(), tag()) — a structured snapshot of THIS config's image on the daemon.

The reference is used verbatim: no image-name substitutor or env-prefix rewrite is applied (exactly like exists; start() is where substitution happens).

◆ with_image()

GenericImage & testcontainers::GenericImage::with_image ( const std::string & reference )

Replace the image reference with "name[:tag]" (tag defaults to "latest"), keeping every other configured option — the same parsing as from_reference.

Lets a copied base config swap the image without rebuilding the rest.

◆ with_exposed_port()

GenericImage & testcontainers::GenericImage::with_exposed_port ( ContainerPort p )

inline

◆ with_env()

GenericImage & testcontainers::GenericImage::with_env	(	std::string	key,
		std::string	value )

inline

◆ with_cmd()

GenericImage & testcontainers::GenericImage::with_cmd ( std::vector< std::string > cmd )

inline

◆ with_entrypoint()

GenericImage & testcontainers::GenericImage::with_entrypoint ( std::vector< std::string > entrypoint )

inline

◆ with_working_dir()

GenericImage & testcontainers::GenericImage::with_working_dir ( std::string working_dir )

inline

◆ with_user()

GenericImage & testcontainers::GenericImage::with_user ( std::string user )

inline

◆ with_privileged()

GenericImage & testcontainers::GenericImage::with_privileged ( bool privileged = true )

inline

◆ with_isolation()

GenericImage & testcontainers::GenericImage::with_isolation ( std::string isolation )

inline

Container isolation technology (HostConfig.Isolation) — Windows daemons only: "process" or "hyperv".

Docker Desktop defaults Windows containers to Hyper-V isolation, under which some operations are unavailable (e.g. copying files into a RUNNING container); "process" lifts that but requires the image build to match the host build. Leave unset on Linux daemons — they REJECT any non-default value at create time ("Invalid isolation: ... Unix only supports 'default'").

◆ with_tty()

GenericImage & testcontainers::GenericImage::with_tty ( bool tty = true )

inline

Allocate a pseudo-TTY for the container (Tty=true).

The log stream is then raw/unframed (no multiplex header) with no separate stderr channel — Container::logs() / follow_logs() read it without demuxing. Note a TTY also rewrites \n to \r\n.

◆ with_mount()

GenericImage & testcontainers::GenericImage::with_mount ( Mount mount )

inline

◆ with_copy_to()

GenericImage & testcontainers::GenericImage::with_copy_to ( CopyToContainer source )

inline

Copy a host file, in-memory bytes, or a host directory tree into the container after it is created and before it is started.

For a single-file source the target's parent directory must already exist in the image; a directory source creates the target chain itself. Add several to copy multiple entries.

◆ with_label()

GenericImage & testcontainers::GenericImage::with_label	(	std::string	key,
		std::string	value )

inline

◆ with_wait()

GenericImage & testcontainers::GenericImage::with_wait ( WaitFor w )

inline

◆ with_startup_timeout()

GenericImage & testcontainers::GenericImage::with_startup_timeout ( std::chrono::milliseconds timeout )

inline

◆ with_healthcheck()

GenericImage & testcontainers::GenericImage::with_healthcheck ( Healthcheck hc )

inline

◆ with_network() [1/2]

GenericImage & testcontainers::GenericImage::with_network ( std::string network )

inline

Join the container to a user-defined network (HostConfig.NetworkMode).

Containers on the same network resolve each other by container name.

◆ with_network() [2/2]

GenericImage & testcontainers::GenericImage::with_network ( const Network & network )

Overload taking the Network handle directly — .with_network(net) instead of .with_network(net.name()).

Only the name is recorded; the handle keeps sole ownership of the network (RAII removal on destruction).

◆ with_network_alias()

GenericImage & testcontainers::GenericImage::with_network_alias ( std::string alias )

inline

Add a DNS alias for this container on its network (NetworkingConfig).

Peers on the same network can resolve this container by the alias in addition to its container name. Requires with_network(...) to take effect; aliases without a target network are ignored.

◆ with_static_ipv4()

GenericImage & testcontainers::GenericImage::with_static_ipv4 ( std::string ip )

inline

Assign a fixed IPv4 address to this container on its network (NetworkingConfig endpoint IPAMConfig.IPv4Address).

Requires with_network(...) on a user-defined network whose subnet contains the address (e.g. one created via Network::builder().with_subnet(...)); without a target network there is no endpoint to pin, so this is ignored.

◆ with_container_name()

GenericImage & testcontainers::GenericImage::with_container_name ( std::string name )

inline

Set an explicit container name (passed as ?name= on create).

Useful so peers on the same network can resolve this container by name.

◆ with_platform()

GenericImage & testcontainers::GenericImage::with_platform ( std::string platform )

inline

Pin the create platform as a free-form "<os>/<arch>" string (e.g.

"windows/amd64"), sent as the ?platform= query on create. Useful to select a Windows image variant on a Windows-containers engine.

◆ with_registry_auth()

GenericImage & testcontainers::GenericImage::with_registry_auth ( RegistryAuth auth )

inline

Supply explicit registry credentials for pulling a private image.

When unset, credentials are auto-resolved from the Docker config (if any).

◆ with_memory_limit()

GenericImage & testcontainers::GenericImage::with_memory_limit ( std::int64_t bytes )

inline

Set a hard memory limit in bytes (HostConfig.Memory).

◆ with_shm_size()

GenericImage & testcontainers::GenericImage::with_shm_size ( std::int64_t bytes )

inline

Set the size of /dev/shm in bytes (HostConfig.ShmSize).

◆ with_ulimit()

GenericImage & testcontainers::GenericImage::with_ulimit	(	std::string	name,
		std::int64_t	soft,
		std::int64_t	hard )

inline

Add a process resource limit (HostConfig.Ulimits), e.g.

with_ulimit("nofile", 1024, 2048). Add several to set multiple limits.

◆ with_cap_add()

GenericImage & testcontainers::GenericImage::with_cap_add ( std::string cap )

inline

Add a Linux capability to grant (HostConfig.CapAdd), e.g. "NET_ADMIN".

◆ with_cap_drop()

GenericImage & testcontainers::GenericImage::with_cap_drop ( std::string cap )

inline

Add a Linux capability to drop (HostConfig.CapDrop).

◆ with_extra_host()

GenericImage & testcontainers::GenericImage::with_extra_host	(	const std::string &	host,
		const std::string &	ip )

inline

Add an /etc/hosts entry (HostConfig.ExtraHosts) mapping host to ip.

◆ with_cpu_limit()

GenericImage & testcontainers::GenericImage::with_cpu_limit ( double cpus )

inline

Cap the container at cpus CPUs' worth of time (HostConfig.NanoCpus) — the docker run --cpus knob, e.g.

1.5 for one and a half CPUs.

◆ with_cpuset_cpus()

GenericImage & testcontainers::GenericImage::with_cpuset_cpus ( std::string cpus )

inline

Pin the container to specific host CPUs (HostConfig.CpusetCpus), e.g.

"0-2,7" — the docker run --cpuset-cpus knob. Linux daemons only.

◆ with_pids_limit()

GenericImage & testcontainers::GenericImage::with_pids_limit ( std::int64_t limit )

inline

Cap the number of processes in the container (HostConfig.PidsLimit); -1 lifts any daemon-default cap.

Linux daemons only.

◆ with_restart_policy()

GenericImage & testcontainers::GenericImage::with_restart_policy ( RestartPolicy policy )

inline

Have the DAEMON restart the container when it exits (HostConfig.RestartPolicy), e.g.

with_restart_policy(RestartPolicy::on_failure(3)). See RestartPolicy for the auto-remove and Ryuk interactions.

◆ with_dns_server()

GenericImage & testcontainers::GenericImage::with_dns_server ( std::string server )

inline

Add a DNS server for the container (HostConfig.Dns).

Add several for several servers; together they REPLACE the daemon's default resolvers in the container's /etc/resolv.conf.

◆ with_dns_search()

GenericImage & testcontainers::GenericImage::with_dns_search ( std::string domain )

inline

Add a DNS search domain (HostConfig.DnsSearch).

◆ with_dns_option()

GenericImage & testcontainers::GenericImage::with_dns_option ( std::string option )

inline

Add a resolver option (HostConfig.DnsOptions), e.g. "ndots:2".

◆ with_sysctl()

GenericImage & testcontainers::GenericImage::with_sysctl	(	std::string	key,
		std::string	value )

inline

Set a namespaced kernel parameter for the container (HostConfig.Sysctls), e.g.

with_sysctl("net.ipv4.ip_unprivileged_port_start", "0"). Linux daemons only, and the daemon accepts only NAMESPACED sysctls (net.*, kernel.shm*‍/msg*‍/sem, fs.mqueue.*) — host-wide ones are rejected.

◆ with_device()

GenericImage & testcontainers::GenericImage::with_device	(	std::string	path_on_host,
		std::string	path_in_container,
		std::string	cgroup_permissions = "rwm" )

inline

Map a host device node into the container (HostConfig.Devices) — the docker run --device knob.

cgroup_permissions is any subset of r(ead)/w(rite)/m(knod). Linux daemons only; path_on_host must exist on the machine the DAEMON runs on (with Docker Desktop, its Linux VM).

◆ with_exposed_host_port()

GenericImage & testcontainers::GenericImage::with_exposed_host_port ( std::uint16_t port )

inline

Expose a port of the HOST (the machine the tests run on) to this container: services listening on 127.0.0.1:<port> in the test process become reachable from inside the container at host.testcontainers.internal:<port>.

Add several to expose multiple ports.

Works regardless of where the daemon runs (Docker Desktop VM, remote engine): the first start() needing it launches one process-wide testcontainers/sshd sidecar container and tunnels each exposed port back to the host through an SSH remote forward. Requires a Linux-containers daemon; supported on the default bridge network and user-defined networks (with_network) — not on network modes "host", "none", or "container:...". If the library was built with TC_HOST_PORT_FORWARDING=OFF (a build without libssh2/OpenSSL), start() throws a DockerError naming that option.

◆ with_create_body_patch()

GenericImage & testcontainers::GenericImage::with_create_body_patch ( std::string json_object )

inline

Deep-merge a raw Docker /containers/create body fragment into the create body (RFC 7386 merge applied AFTER our typed fields, so it overrides them).

This is the escape hatch for any field not exposed as a typed setter: nest HostConfig fields under "HostConfig". json_object must be a JSON object.

◆ with_image_pull_policy() [1/2]

GenericImage & testcontainers::GenericImage::with_image_pull_policy ( ImagePullPolicy policy )

inline

Control whether the image is pulled before create.

Default keeps the lazy behavior (pull only on a create 404); Always pulls before create even when the image is already present locally. Each call REPLACES the whole pull policy — an age budget set earlier is cleared.

◆ with_image_pull_policy() [2/2]

GenericImage & testcontainers::GenericImage::with_image_pull_policy ( std::chrono::seconds max_age )

inline

Age-based pull: pull before create when the LOCAL image's Created timestamp is older than max_age — or cannot be read; a missing image is still fetched lazily by create itself.

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. Each call replaces the whole pull policy.

◆ with_reuse()

GenericImage & testcontainers::GenericImage::with_reuse ( bool reuse = true )

inline

Enable container reuse.

When reuse is also enabled globally (testcontainers.reuse.enable=true in ~/.testcontainers.properties or TESTCONTAINERS_REUSE_ENABLE=true), start() first looks for an already-running container matching this config (by a stable reuse-hash label) and ADOPTS it instead of creating a new one; the returned handle is persistent (it does NOT remove the container on destruction, and the container is NOT Ryuk-reaped, so it survives across runs). When reuse is not enabled globally this is a no-op: start() behaves exactly like a normal (reaped, auto-removed) container.

Matching is CONFIG-based, not content-based: the reuse hash covers the create body and the copy-to descriptors. Byte sources contribute their content; a host-path source contributes its path plus each file's SIZE and MTIME — editing a copied fixture in place therefore invalidates the match (a fresh container is created; the stale one lingers until pruned, like any config change). Only an edit that keeps both size and mtime (e.g. a deliberate timestamp reset) goes unnoticed; content is never re-read for hashing.

◆ with_image_name_substitutor()

GenericImage & testcontainers::GenericImage::with_image_name_substitutor ( std::function< std::string(const std::string &)> fn )

inline

Override how the image reference is rewritten before create.

When set this REPLACES the default env-prefix substitution (TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX); the function receives "name:tag" and returns the reference to actually use.

◆ with_created_hook()

GenericImage & testcontainers::GenericImage::with_created_hook ( LifecycleHook hook )

inline

Register a hook fired right after the container is created (id assigned), before any copy-to and before start.

A throwing created hook aborts start() and the partial container is cleaned up. Add several to run them in registration order. The hook receives the public DockerClient and the container id, so it can inspect/exec/copy via the existing API.

◆ with_starting_hook()

GenericImage & testcontainers::GenericImage::with_starting_hook ( LifecycleHook hook )

inline

Register a hook fired after copy-to and immediately before the container is started.

A throwing starting hook aborts start() and the partial container is cleaned up. Add several to run them in registration order.

◆ with_started_hook()

GenericImage & testcontainers::GenericImage::with_started_hook ( LifecycleHook hook )

inline

Register a hook fired after the container is started AND has become ready (wait strategies satisfied), before the handle is returned.

A throwing started hook aborts start() and the container is cleaned up. Add several to run them in registration order.

◆ with_stopping_hook()

GenericImage & testcontainers::GenericImage::with_stopping_hook ( LifecycleHook hook )

inline

Register a hook fired by the Container when it is being torn down: on an explicit stop()/remove(), or on destruction of an auto-removing handle, before the container is removed.

Fired exactly once and never on a persistent (reusable) handle's drop. A throwing stopping hook is swallowed (teardown is best-effort). Add several to run them in registration order.

◆ with_startup_attempts()

GenericImage & testcontainers::GenericImage::with_startup_attempts ( int n )

inline

Retry the whole create→start→wait sequence up to n times if an attempt fails (each retry creates a brand-new container).

Values < 1 are treated as 1 (a single attempt, no retry).

◆ image()

const std::string & testcontainers::GenericImage::image ( ) const

inlinenoexcept

◆ tag()

const std::string & testcontainers::GenericImage::tag ( ) const

inlinenoexcept

◆ exposed_ports()

const std::vector< ContainerPort > & testcontainers::GenericImage::exposed_ports ( ) const

inlinenoexcept

◆ env()

const std::vector< std::pair< std::string, std::string > > & testcontainers::GenericImage::env ( ) const

inlinenoexcept

◆ cmd()

const std::vector< std::string > & testcontainers::GenericImage::cmd ( ) const

inlinenoexcept

◆ entrypoint()

const std::vector< std::string > & testcontainers::GenericImage::entrypoint ( ) const

inlinenoexcept

◆ working_dir()

const std::optional< std::string > & testcontainers::GenericImage::working_dir ( ) const

inlinenoexcept

◆ user()

const std::optional< std::string > & testcontainers::GenericImage::user ( ) const

inlinenoexcept

◆ privileged()

bool testcontainers::GenericImage::privileged ( ) const

inlinenoexcept

◆ isolation()

const std::optional< std::string > & testcontainers::GenericImage::isolation ( ) const

inlinenoexcept

◆ tty()

bool testcontainers::GenericImage::tty ( ) const

inlinenoexcept

◆ mounts()

const std::vector< Mount > & testcontainers::GenericImage::mounts ( ) const

inlinenoexcept

◆ copy_to_sources()

const std::vector< CopyToContainer > & testcontainers::GenericImage::copy_to_sources ( ) const

inlinenoexcept

◆ labels()

const std::vector< std::pair< std::string, std::string > > & testcontainers::GenericImage::labels ( ) const

inlinenoexcept

◆ waits()

const std::vector< WaitFor > & testcontainers::GenericImage::waits ( ) const

inlinenoexcept

◆ startup_timeout()

std::chrono::milliseconds testcontainers::GenericImage::startup_timeout ( ) const

inlinenoexcept

◆ healthcheck()

const std::optional< Healthcheck > & testcontainers::GenericImage::healthcheck ( ) const

inlinenoexcept

◆ network()

const std::optional< std::string > & testcontainers::GenericImage::network ( ) const

inlinenoexcept

◆ network_aliases()

const std::vector< std::string > & testcontainers::GenericImage::network_aliases ( ) const

inlinenoexcept

◆ static_ipv4()

const std::optional< std::string > & testcontainers::GenericImage::static_ipv4 ( ) const

inlinenoexcept

◆ container_name()

const std::optional< std::string > & testcontainers::GenericImage::container_name ( ) const

inlinenoexcept

◆ platform()

const std::optional< std::string > & testcontainers::GenericImage::platform ( ) const

inlinenoexcept

◆ registry_auth()

const std::optional< RegistryAuth > & testcontainers::GenericImage::registry_auth ( ) const

inlinenoexcept

◆ memory_limit()

const std::optional< std::int64_t > & testcontainers::GenericImage::memory_limit ( ) const

inlinenoexcept

◆ shm_size()

const std::optional< std::int64_t > & testcontainers::GenericImage::shm_size ( ) const

inlinenoexcept

◆ ulimits()

const std::vector< Ulimit > & testcontainers::GenericImage::ulimits ( ) const

inlinenoexcept

◆ cap_add()

const std::vector< std::string > & testcontainers::GenericImage::cap_add ( ) const

inlinenoexcept

◆ cap_drop()

const std::vector< std::string > & testcontainers::GenericImage::cap_drop ( ) const

inlinenoexcept

◆ extra_hosts()

const std::vector< std::string > & testcontainers::GenericImage::extra_hosts ( ) const

inlinenoexcept

◆ exposed_host_ports()

const std::vector< std::uint16_t > & testcontainers::GenericImage::exposed_host_ports ( ) const

inlinenoexcept

◆ create_body_patch()

const std::string & testcontainers::GenericImage::create_body_patch ( ) const

inlinenoexcept

◆ image_pull_policy()

ImagePullPolicy testcontainers::GenericImage::image_pull_policy ( ) const

inlinenoexcept

◆ pull_max_age()

const std::optional< std::chrono::seconds > & testcontainers::GenericImage::pull_max_age ( ) const

inlinenoexcept

◆ reuse()

bool testcontainers::GenericImage::reuse ( ) const

inlinenoexcept

◆ image_name_substitutor()

const std::function< std::string(const std::string &)> & testcontainers::GenericImage::image_name_substitutor ( ) const

inlinenoexcept

◆ created_hooks()

const std::vector< LifecycleHook > & testcontainers::GenericImage::created_hooks ( ) const

inlinenoexcept

◆ starting_hooks()

const std::vector< LifecycleHook > & testcontainers::GenericImage::starting_hooks ( ) const

inlinenoexcept

◆ started_hooks()

const std::vector< LifecycleHook > & testcontainers::GenericImage::started_hooks ( ) const

inlinenoexcept

◆ stopping_hooks()

const std::vector< LifecycleHook > & testcontainers::GenericImage::stopping_hooks ( ) const

inlinenoexcept

◆ startup_attempts()

int testcontainers::GenericImage::startup_attempts ( ) const

inlinenoexcept

◆ to_request()

ContainerRequest testcontainers::GenericImage::to_request ( ) const

Snapshot this builder into a self-contained ContainerRequest — the fully-translated create spec (resolved/substituted image reference, env joined to "KEY=VALUE"; exposed ports were already rendered as declared) plus every run-time input (waits, copy-to sources, hooks, pull/reuse/retry policy).

start() is exactly run(to_request()); call this directly to tweak the request or to run() it on a custom DockerClient.

◆ start()

Container testcontainers::GenericImage::start ( ) const

Create, start, and wait for a container from this image, returning a RAII handle that removes the container on destruction.

Throws on failure (best-effort removing a container that started but never became ready).

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ GenericImage()

Member Function Documentation

◆ from_reference()

◆ exists()

◆ inspect() [1/2]

◆ inspect() [2/2]

◆ with_image()

◆ with_exposed_port()

◆ with_env()

◆ with_cmd()

◆ with_entrypoint()

◆ with_working_dir()

◆ with_user()

◆ with_privileged()

◆ with_isolation()

◆ with_tty()

◆ with_mount()

◆ with_copy_to()

◆ with_label()

◆ with_wait()

◆ with_startup_timeout()

◆ with_healthcheck()

◆ with_network() [1/2]

◆ with_network() [2/2]

◆ with_network_alias()

◆ with_static_ipv4()

◆ with_container_name()

◆ with_platform()

◆ with_registry_auth()

◆ with_memory_limit()

◆ with_shm_size()

◆ with_ulimit()

◆ with_cap_add()

◆ with_cap_drop()

◆ with_extra_host()

◆ with_cpu_limit()

◆ with_cpuset_cpus()

◆ with_pids_limit()

◆ with_restart_policy()

◆ with_dns_server()

◆ with_dns_search()

◆ with_dns_option()

◆ with_sysctl()

◆ with_device()

◆ with_exposed_host_port()

◆ with_create_body_patch()

◆ with_image_pull_policy() [1/2]

◆ with_image_pull_policy() [2/2]

◆ with_reuse()

◆ with_image_name_substitutor()

◆ with_created_hook()

◆ with_starting_hook()

◆ with_started_hook()

◆ with_stopping_hook()

◆ with_startup_attempts()

◆ image()

◆ tag()

◆ exposed_ports()

◆ env()

◆ cmd()

◆ entrypoint()

◆ working_dir()

◆ user()

◆ privileged()

◆ isolation()

◆ tty()

◆ mounts()

◆ copy_to_sources()

◆ labels()

◆ waits()

◆ startup_timeout()

◆ healthcheck()

◆ network()

◆ network_aliases()

◆ static_ipv4()

◆ container_name()