testcontainers::modules::NATSImage Class Reference

A reusable, copyable description of a NATS server container: the pinned image, the client and HTTP-monitoring ports, a log + /healthz readiness pair, and optional credentials / JetStream / extra server flags — all rendered into the command line (the server reads no environment). More...

#include <testcontainers/modules/NATS.hpp>

Public Member Functions
	NATSImage ()
	A config ready to start(): image nats:2.12, ports 4222 + 8222 exposed, no auth, JetStream off; readiness = the "Server is ready" log line, then /healthz answering 200 through the published port.
NATSImage &	with_image (const std::string &reference)
	Override the pinned image with a full reference "name[:tag]" (tag defaults to "latest"), e.g.
NATSImage &	with_username (std::string username)
	Require authentication: the server starts with --user <u> --pass <p> and url() gains user:pass@.
NATSImage &	with_password (std::string password)
	The password half of with_username (same pairing rule).
NATSImage &	with_jetstream (bool enable=true)
	Enable JetStream (-js).
NATSImage &	with_command_args (std::vector< std::string > args)
	Append nats-server flags after the managed ones, e.g.
NATSImage &	with_command_arg (std::string arg)
	The single-argument twin of with_command_args (same rules).
NATSImage &	with_env (std::string key, std::string value)
	Set an extra environment variable (for your own tooling — the module manages no env keys; nats-server is configured entirely by its command line).
NATSImage &	with_label (std::string key, std::string value)
NATSImage &	with_network (std::string network)
	Join a user-defined network; peers resolve this container by name/alias at <alias>:4222 (kClientPort, not the mapped host port).
NATSImage &	with_network (const Network &network)
NATSImage &	with_network_alias (std::string alias)
NATSImage &	with_reuse (bool reuse=true)
	Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse).
NATSImage &	with_startup_timeout (std::chrono::milliseconds timeout)
	Budget for the whole readiness phase (default: 60s; the server boots in well under a second — the budget covers slow CI daemons).
NATSImage &	with_startup_attempts (int n)
	Retry the whole create→start→wait sequence up to n times.
NATSImage &	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 &	username () const noexcept
	The configured username; empty when auth is off.
const std::string &	password () const noexcept
	The configured password; empty when auth is off.
bool	jetstream () const noexcept
	Whether JetStream will be enabled.
const std::vector< std::string > &	command_args () const noexcept
	Extra nats-server flags 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 NATSContainer.
NATSContainer	start () const
	Create, start, and wait until the server logs readiness and answers /healthz.

Static Public Attributes
static constexpr std::string_view	kDefaultImage = "nats:2.12"
	The pinned default image.
static constexpr std::uint16_t	kClientPort = 4222
	The client port INSIDE the container.
static constexpr std::uint16_t	kMonitoringPort = 8222
	The HTTP monitoring port INSIDE the container (/healthz, /varz, /connz, /jsz, ...).

Detailed Description

A reusable, copyable description of a NATS server container: the pinned image, the client and HTTP-monitoring ports, a log + /healthz readiness pair, and optional credentials / JetStream / extra server flags — all rendered into the command line (the server reads no environment).

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

NATSImage()

testcontainers::modules::NATSImage::NATSImage

(

)

A config ready to start(): image nats:2.12, ports 4222 + 8222 exposed, no auth, JetStream off; readiness = the "Server is ready" log line, then /healthz answering 200 through the published port.

Member Function Documentation

with_image()

NATSImage & testcontainers::modules::NATSImage::with_image

(

const std::string &

reference

)

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

"nats:2.14-alpine" or a registry-qualified mirror reference. The image must accept nats-server flags as its container command; every official nats tag does.

with_username()

NATSImage & testcontainers::modules::NATSImage::with_username

(

std::string

username

)

Require authentication: the server starts with --user <u> --pass <p> and url() gains user:pass@.

Set both halves or neither — start() throws at render on half a pair. Test credentials only: the values are visible in the container's command line via inspect.

with_password()

NATSImage & testcontainers::modules::NATSImage::with_password

(

std::string

password

)

The password half of with_username (same pairing rule).

with_jetstream()

NATSImage & testcontainers::modules::NATSImage::with_jetstream

(

bool

enable = true

)

Enable JetStream (-js).

Stream data lives in the container layer — gone with the container; with_reuse keeps it across runs, or mount a volume over a --store_dir directory through with_customizer.

with_command_args()

NATSImage & testcontainers::modules::NATSImage::with_command_args

(

std::vector< std::string >

args

)

Append nats-server flags after the managed ones, e.g.

{"--name", "orders-bus"} or {"--auth", "tok"}. Repeatable; calls accumulate in order. The flags the module renders stay with their typed setters: an entry naming the credentials (--user/--pass), JetStream (-js/--jetstream), the monitoring listener (-m/--http_port), the client listener (-p/--port, -a/--addr/--net), or a config file (-c/--config) makes start() throw up front — the server keeps the LAST occurrence of a flag, so a duplicate would silently desync the connection getters or starve the readiness probe (and a config file can re-set any of them invisibly). The check scans every entry, so a VALUE spelled like a managed flag (e.g. a server name of "-p") is rejected too. Full command ownership (config-file setups): a customizer's with_cmd (runs last, wins).

with_command_arg()

NATSImage & testcontainers::modules::NATSImage::with_command_arg

(

std::string

arg

)

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

with_env()

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

Set an extra environment variable (for your own tooling — the module manages no env keys; nats-server is configured entirely by its command line).

with_label()

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

with_network() [1/2]

NATSImage & testcontainers::modules::NATSImage::with_network

(

std::string

network

)

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

with_network() [2/2]

NATSImage & testcontainers::modules::NATSImage::with_network

(

const Network &

network

)

with_network_alias()

NATSImage & testcontainers::modules::NATSImage::with_network_alias

(

std::string

alias

)

with_reuse()

NATSImage & testcontainers::modules::NATSImage::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 JetStream streams: same config, next run, data intact.

with_startup_timeout()

NATSImage & testcontainers::modules::NATSImage::with_startup_timeout

(

std::chrono::milliseconds

timeout

)

Budget for the whole readiness phase (default: 60s; the server boots in well under a second — the budget covers slow CI daemons).

Image pull time does not count against it.

with_startup_attempts()

NATSImage & testcontainers::modules::NATSImage::with_startup_attempts

(

int

n

)

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

with_customizer()

NATSImage & testcontainers::modules::NATSImage::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. A with_cmd here replaces the module's flags wholesale: keep monitoring on 8222 (or replace the waits too), and keep credentials in the typed setters — flags set this way desync url() and the getters.

username()

const std::string & testcontainers::modules::NATSImage::username ( ) const

inlinenoexcept

The configured username; empty when auth is off.

password()

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

inlinenoexcept

The configured password; empty when auth is off.

jetstream()

bool testcontainers::modules::NATSImage::jetstream ( ) const

inlinenoexcept

Whether JetStream will be enabled.

command_args()

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

inlinenoexcept

Extra nats-server flags accumulated so far.

to_generic()

GenericImage testcontainers::modules::NATSImage::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 NATSContainer.

Throws Error — before any daemon contact — on half a credential pair, or on a module-managed flag inside with_command_args (see there).

start()

NATSContainer testcontainers::modules::NATSImage::start

(

)

const

Create, start, and wait until the server logs readiness and answers /healthz.

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::NATSImage::kDefaultImage = "nats:2.12"

staticconstexpr

The pinned default image.

Built FROM scratch: the only file inside is the server binary, so container().exec(...) has nothing to run — assert from the host instead (raw TCP on port(), or the monitoring API on monitoring_port()). The -alpine tags add a busybox shell; the module's flags-only command works on both variants. Override with with_image; the hub-prefix substitution (TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX) applies as usual.

kClientPort

std::uint16_t testcontainers::modules::NATSImage::kClientPort = 4222

staticconstexpr

The client port INSIDE the container.

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

kMonitoringPort

std::uint16_t testcontainers::modules::NATSImage::kMonitoringPort = 8222

staticconstexpr

The HTTP monitoring port INSIDE the container (/healthz, /varz, /connz, /jsz, ...).

Always enabled by the module (-m 8222); the endpoints answer plain unauthenticated GETs.