testcontainers::modules::RedisImage Class Reference

A reusable, copyable description of a Redis server container: the pinned image, the exposed server port, an in-container redis-cli ping readiness probe, and optional password / extra server arguments. More...

#include <testcontainers/modules/Redis.hpp>

Public Member Functions
	RedisImage ()
	A config ready to start(): image redis:7.2, port 6379 exposed, and readiness = an in-container redis-cli ping answering successfully.
RedisImage &	with_image (const std::string &reference)
	Override the pinned image with a full reference "name[:tag]" (tag defaults to "latest"), e.g.
RedisImage &	with_password (std::string password)
	Require a password: the server starts with --requirepass <password> and RedisContainer::connection_string() gains :password@.
RedisImage &	with_command_args (std::vector< std::string > args)
	Append arguments to the redis-server command line, e.g.
RedisImage &	with_command_arg (std::string arg)
	The single-argument twin of with_command_args (same placement and accumulation rules).
RedisImage &	with_env (std::string key, std::string value)
	Set an extra environment variable.
RedisImage &	with_label (std::string key, std::string value)
RedisImage &	with_network (std::string network)
	Join a user-defined network; peers resolve this container by name/alias at <alias>:6379 (kPort, not the mapped host port).
RedisImage &	with_network (const Network &network)
RedisImage &	with_network_alias (std::string alias)
RedisImage &	with_reuse (bool reuse=true)
	Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse).
RedisImage &	with_startup_timeout (std::chrono::milliseconds timeout)
	Budget for the whole readiness phase (default: 60s).
RedisImage &	with_startup_attempts (int n)
	Retry the whole create→start→wait sequence up to n times.
RedisImage &	with_customizer (std::function< void(GenericImage &)> customize)
	Register a callback that customizes the underlying GenericImage — the channel for every option this module does not surface (mounts, pull policy, ...).
const std::string &	password () const noexcept
	The configured password; empty when none.
const std::vector< std::string > &	command_args () const noexcept
	Extra redis-server arguments accumulated so far.
GenericImage	to_generic () const
	Render the full configuration — module options and customizers applied — into a plain GenericImage: the drop-down escape hatch when you need a raw core Container (or run-level tweaks) instead of a RedisContainer.
RedisContainer	start () const
	Create, start, and wait until the server answers redis-cli ping.

Static Public Attributes
static constexpr std::string_view	kDefaultImage = "redis:7.2"
	The pinned default image.
static constexpr std::uint16_t	kPort = 6379
	The server port INSIDE the container.

Detailed Description

A reusable, copyable description of a Redis server container: the pinned image, the exposed server port, an in-container redis-cli ping readiness probe, and optional password / extra server arguments.

The with_* builders mutate in place and return *this by reference, so a named config can be configured incrementally and started many times. Core options the module does not surface are reached through with_customizer; to_generic() drops down to a plain GenericImage when a raw core Container is wanted instead.

Constructor & Destructor Documentation

RedisImage()

testcontainers::modules::RedisImage::RedisImage

(

)

A config ready to start(): image redis:7.2, port 6379 exposed, and readiness = an in-container redis-cli ping answering successfully.

Member Function Documentation

with_image()

RedisImage & testcontainers::modules::RedisImage::with_image

(

const std::string &

reference

)

Override the pinned image with a full reference "name[:tag]" (tag defaults to "latest"), e.g.

"redis:7.4" or a registry-qualified mirror reference. The image must ship redis-cli — the readiness probe runs it; every official redis tag does.

with_password()

RedisImage & testcontainers::modules::RedisImage::with_password

(

std::string

password

)

Require a password: the server starts with --requirepass <password> and RedisContainer::connection_string() gains :password@.

The container also carries REDISCLI_AUTH=<password>, so in-container redis-cli runs — the readiness probe and any exec you issue — authenticate automatically. An empty password means no auth (the default). Test credentials only: the value is visible in the container's command line and environment via inspect.

with_command_args()

RedisImage & testcontainers::modules::RedisImage::with_command_args

(

std::vector< std::string >

args

)

Append arguments to the redis-server command line, e.g.

{"--maxmemory", "64mb"}. Repeatable; calls accumulate in order, placed after --requirepass when a password is set. Setting any args (or a password) makes the module own the container command; a customizer's with_cmd still wins (customizers run last).

with_command_arg()

RedisImage & testcontainers::modules::RedisImage::with_command_arg

(

std::string

arg

)

The single-argument twin of with_command_args (same placement and accumulation rules).

with_env()

RedisImage & testcontainers::modules::RedisImage::with_env	(	std::string	key,
		std::string	value )

Set an extra environment variable.

REDISCLI_AUTH belongs to with_password: setting it here alongside a password makes start() throw up front — unlike the DB modules' bash-read credential keys, it is read by EXEC'D processes (the readiness probe's redis-cli), where the FIRST duplicate of a key wins, so the module could not override a raw entry by ordering. Without a password the key is yours to set (custom auth setups).

with_label()

RedisImage & testcontainers::modules::RedisImage::with_label	(	std::string	key,
		std::string	value )

with_network() [1/2]

RedisImage & testcontainers::modules::RedisImage::with_network

(

std::string

network

)

Join a user-defined network; peers resolve this container by name/alias at <alias>:6379 (kPort, not the mapped host port).

with_network() [2/2]

RedisImage & testcontainers::modules::RedisImage::with_network

(

const Network &

network

)

with_network_alias()

RedisImage & testcontainers::modules::RedisImage::with_network_alias

(

std::string

alias

)

with_reuse()

RedisImage & testcontainers::modules::RedisImage::with_reuse

(

bool

reuse = true

)

Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse).

An adopted server keeps its keyspace: same config, next run, data intact.

with_startup_timeout()

RedisImage & testcontainers::modules::RedisImage::with_startup_timeout

(

std::chrono::milliseconds

timeout

)

Budget for the whole readiness phase (default: 60s).

Image pull time does not count against it.

with_startup_attempts()

RedisImage & testcontainers::modules::RedisImage::with_startup_attempts

(

int

n

)

Retry the whole create→start→wait sequence up to n times.

with_customizer()

RedisImage & testcontainers::modules::RedisImage::with_customizer

(

std::function< void(GenericImage &)>

customize

)

Register a callback that customizes the underlying GenericImage — the channel for every option this module does not surface (mounts, pull policy, ...).

Customizers run when the config is rendered (start() / to_generic()), in registration order, AFTER the module's own rendering — what they set wins over the module. Do not set REDISCLI_AUTH here: with_password manages it (see with_env).

password()

const std::string & testcontainers::modules::RedisImage::password ( ) const

inlinenoexcept

The configured password; empty when none.

command_args()

const std::vector< std::string > & testcontainers::modules::RedisImage::command_args ( ) const

inlinenoexcept

Extra redis-server arguments accumulated so far.

to_generic()

GenericImage testcontainers::modules::RedisImage::to_generic

(

)

const

Render the full configuration — module options and customizers applied — into a plain GenericImage: the drop-down escape hatch when you need a raw core Container (or run-level tweaks) instead of a RedisContainer.

Throws Error — before any daemon contact — when with_env carries REDISCLI_AUTH alongside a configured password (see with_env).

start()

RedisContainer testcontainers::modules::RedisImage::start

(

)

const

Create, start, and wait until the server answers redis-cli ping.

Throws on failure (StartupTimeoutError when the server never becomes ready within the startup timeout), like GenericImage::start().

Member Data Documentation

kDefaultImage

std::string_view testcontainers::modules::RedisImage::kDefaultImage = "redis:7.2"

staticconstexpr

The pinned default image.

Override with with_image; the hub-prefix substitution (TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX) applies as usual.

kPort

std::uint16_t testcontainers::modules::RedisImage::kPort = 6379

staticconstexpr

The server port INSIDE the container.

Peers on a shared docker network connect to <alias-or-name>:kPort; the test process itself uses RedisContainer::port() (the mapped host port) instead.