testcontainers::modules::MosquittoImage Class Reference

A reusable, copyable description of an Eclipse Mosquitto MQTT broker: the pinned image, port 1883 exposed, and a managed mosquitto.conf (copied in before start) that accepts anonymous clients from outside the container — the stock image config would listen on the container's loopback only, so the mapped port would connect to nothing. More...

#include <testcontainers/modules/Mosquitto.hpp>

Public Member Functions
	MosquittoImage ()
	A config ready to start(): image eclipse-mosquitto:2.0, port 1883 exposed, managed config listener 1883 + allow_anonymous true, and readiness = the broker's own "running" log line (printed after the listening sockets are open).
MosquittoImage &	with_image (const std::string &reference)
	Override the pinned image with a full reference "name[:tag]" (tag defaults to "latest"), e.g.
MosquittoImage &	with_config_option (std::string key, std::string value)
	Append one option line, <key> <value>, to the managed config — e.g.
MosquittoImage &	with_config (std::filesystem::path host_conf)
	Replace the managed config with a host file, copied to kConfigPath at start (the file is read at copy time).
MosquittoImage &	with_config_content (std::string conf)
	As with_config, from in-memory bytes instead of a host file.
MosquittoImage &	with_env (std::string key, std::string value)
	Set an extra environment variable (for your own tooling — the image reads none itself; mosquitto is configured by file only, so there are no managed keys to collide with).
MosquittoImage &	with_label (std::string key, std::string value)
MosquittoImage &	with_network (std::string network)
	Join a user-defined network; peers resolve this container by name/alias at <alias>:1883 (kPort, not the mapped host port).
MosquittoImage &	with_network (const Network &network)
MosquittoImage &	with_network_alias (std::string alias)
MosquittoImage &	with_reuse (bool reuse=true)
	Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse).
MosquittoImage &	with_startup_timeout (std::chrono::milliseconds timeout)
	Budget for the whole readiness phase (default: 60s; the broker itself boots in well under a second — the budget covers slow CI daemons).
MosquittoImage &	with_startup_attempts (int n)
	Retry the whole create→start→wait sequence up to n times.
MosquittoImage &	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 (extra listener ports, mounts, a password-file copy, ...).
const std::vector< std::pair< std::string, std::string > > &	config_options () const noexcept
	Option lines accumulated by with_config_option, in call order.
GenericImage	to_generic () const
	Render the full configuration — managed or replacement config file, option lines, customizers — into a plain GenericImage: the drop-down escape hatch when a raw core Container is wanted.
MosquittoContainer	start () const
	Create, start, and wait until the broker logs that it is running (the listening sockets are open by then).

Static Public Attributes
static constexpr std::string_view	kDefaultImage = "eclipse-mosquitto:2.0"
	The pinned default image.
static constexpr std::uint16_t	kPort = 1883
	The MQTT port INSIDE the container.
static constexpr std::string_view	kConfigPath = "/mosquitto/config/mosquitto.conf"
	Where the image reads its configuration — the managed config (or your with_config replacement) is copied here before start.

Detailed Description

A reusable, copyable description of an Eclipse Mosquitto MQTT broker: the pinned image, port 1883 exposed, and a managed mosquitto.conf (copied in before start) that accepts anonymous clients from outside the container — the stock image config would listen on the container's loopback only, so the mapped port would connect to nothing.

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

MosquittoImage()

testcontainers::modules::MosquittoImage::MosquittoImage

(

)

A config ready to start(): image eclipse-mosquitto:2.0, port 1883 exposed, managed config listener 1883 + allow_anonymous true, and readiness = the broker's own "running" log line (printed after the listening sockets are open).

Member Function Documentation

with_image()

MosquittoImage & testcontainers::modules::MosquittoImage::with_image

(

const std::string &

reference

)

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

"eclipse-mosquitto:2.1-alpine" or a mirror reference — any image that reads kConfigPath and logs startup to stdout/stderr works.

with_config_option()

MosquittoImage & testcontainers::modules::MosquittoImage::with_config_option	(	std::string	key,
		std::string	value )

Append one option line, <key> <value>, to the managed config — e.g.

("persistence", "true"). Repeatable; lines land after the managed listener block in call order, so listener-scoped options bind to the module's port-1883 listener. Incompatible with with_config / with_config_content (render throws): a replaced config owns its options.

with_config()

MosquittoImage & testcontainers::modules::MosquittoImage::with_config

(

std::filesystem::path

host_conf

)

Replace the managed config with a host file, copied to kConfigPath at start (the file is read at copy time).

You then own the whole contract: keep a listener 1883 (the published port — a listenerless config serves the container's loopback only while the readiness wait still passes), keep startup logs on stdout/stderr at the default log_type, and choose your own auth (allow_anonymous defaults to false once a listener is defined). Repeat calls replace again; the last one wins.

with_config_content()

MosquittoImage & testcontainers::modules::MosquittoImage::with_config_content

(

std::string

conf

)

As with_config, from in-memory bytes instead of a host file.

with_env()

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

Set an extra environment variable (for your own tooling — the image reads none itself; mosquitto is configured by file only, so there are no managed keys to collide with).

with_label()

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

with_network() [1/2]

MosquittoImage & testcontainers::modules::MosquittoImage::with_network

(

std::string

network

)

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

with_network() [2/2]

MosquittoImage & testcontainers::modules::MosquittoImage::with_network

(

const Network &

network

)

with_network_alias()

MosquittoImage & testcontainers::modules::MosquittoImage::with_network_alias

(

std::string

alias

)

with_reuse()

MosquittoImage & testcontainers::modules::MosquittoImage::with_reuse

(

bool

reuse = true

)

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

An adopted broker keeps its retained messages and persistent sessions: same config, next run, state intact.

with_startup_timeout()

MosquittoImage & testcontainers::modules::MosquittoImage::with_startup_timeout

(

std::chrono::milliseconds

timeout

)

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

Image pull time does not count against it.

with_startup_attempts()

MosquittoImage & testcontainers::modules::MosquittoImage::with_startup_attempts

(

int

n

)

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

with_customizer()

MosquittoImage & testcontainers::modules::MosquittoImage::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 (extra listener ports, mounts, a password-file copy, ...).

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.

config_options()

const std::vector< std::pair< std::string, std::string > > & testcontainers::modules::MosquittoImage::config_options ( ) const

inlinenoexcept

Option lines accumulated by with_config_option, in call order.

to_generic()

GenericImage testcontainers::modules::MosquittoImage::to_generic

(

)

const

Render the full configuration — managed or replacement config file, option lines, customizers — into a plain GenericImage: the drop-down escape hatch when a raw core Container is wanted.

Throws Error — before any daemon contact — when option lines are combined with a replacement config (see with_config_option).

start()

MosquittoContainer testcontainers::modules::MosquittoImage::start

(

)

const

Create, start, and wait until the broker logs that it is running (the listening sockets are open by then).

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

Member Data Documentation

kDefaultImage

std::string_view testcontainers::modules::MosquittoImage::kDefaultImage = "eclipse-mosquitto:2.0"

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::MosquittoImage::kPort = 1883

staticconstexpr

The MQTT port INSIDE the container.

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

kConfigPath

std::string_view testcontainers::modules::MosquittoImage::kConfigPath = "/mosquitto/config/mosquitto.conf"

staticconstexpr

Where the image reads its configuration — the managed config (or your with_config replacement) is copied here before start.