testcontainers::modules::MongoDBImage Class Reference

A MongoDB server for tests: a copyable, reusable description of a mongo container that always runs as a SINGLE-NODE REPLICA SET, so sessions, multi-document transactions, and change streams work out of the box. More...

#include <testcontainers/modules/MongoDB.hpp>

Public Member Functions
	MongoDBImage ()
	A config ready to start(): image mongo:7, port 27017 exposed, replica set "rs0", default database "test".
MongoDBImage &	with_image (const std::string &reference)
	Override the pinned image with a full reference "name[:tag]", e.g.
MongoDBImage &	with_replica_set_name (std::string name)
	Rename the replica set (default "rs0").
MongoDBImage &	with_database (std::string database)
	Set the database that a no-argument connection_string() points at (default "test").
MongoDBImage &	with_env (std::string key, std::string value)
	Set an extra environment variable (TZ and friends).
MongoDBImage &	with_label (std::string key, std::string value)
MongoDBImage &	with_network (std::string network)
	Join a user-defined network; peers resolve this container by name/alias at <alias>:27017 (kPort, not the mapped host port).
MongoDBImage &	with_network (const Network &network)
MongoDBImage &	with_network_alias (std::string alias)
MongoDBImage &	with_reuse (bool reuse=true)
	Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse).
MongoDBImage &	with_startup_timeout (std::chrono::milliseconds timeout)
	Budget for EACH of the two startup phases — the container-level readiness wait, and the replica-set initiation (rs.initiate + the PRIMARY election poll) that follows it — so the worst-case total is about twice this.
MongoDBImage &	with_startup_attempts (int n)
	Retry the whole create→start→initiate sequence up to n times.
MongoDBImage &	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, memory limits, pull policy, ...).
const std::string &	replica_set_name () const noexcept
const std::string &	database () const noexcept
GenericImage	to_generic () const
	Render the full configuration — the replica-set command line, both readiness waits, and the post-start hook that initiates the set and waits for PRIMARY — into a plain GenericImage: the drop-down escape hatch when you need a raw core Container instead of a MongoDBContainer.
MongoDBContainer	start () const
	Create and start the container, initiate the replica set, and wait until the node is the writable PRIMARY.

Static Public Attributes
static constexpr std::string_view	kDefaultImage = "mongo:7"
	The pinned default image.
static constexpr std::uint16_t	kPort = 27017
	The server port INSIDE the container.

Detailed Description

A MongoDB server for tests: a copyable, reusable description of a mongo container that always runs as a SINGLE-NODE REPLICA SET, so sessions, multi-document transactions, and change streams work out of the box.

start() boots the container, initiates the replica set, waits until the node is the writable PRIMARY, and returns a MongoDBContainer that hands out ready-to-use connection strings. The ~1–2s election cost is the whole price; a one-node primary serves plain CRUD exactly like a standalone.

The server runs WITHOUT authentication: MongoDB requires a cluster keyfile as soon as auth is combined with a replica set — test-hostile complexity for no isolation gain on a throwaway container. Do not set MONGO_INITDB_ROOT_USERNAME / MONGO_INITDB_ROOT_PASSWORD through a customizer: an auth-enabled replica-set member refuses to start without a keyfile.

The with_* builders mutate in place and return *this by reference, so a named config can be configured incrementally and started many times.

Constructor & Destructor Documentation

MongoDBImage()

testcontainers::modules::MongoDBImage::MongoDBImage

(

)

A config ready to start(): image mongo:7, port 27017 exposed, replica set "rs0", default database "test".

Member Function Documentation

with_image()

MongoDBImage & testcontainers::modules::MongoDBImage::with_image

(

const std::string &

reference

)

Override the pinned image with a full reference "name[:tag]", e.g.

a hub mirror or "mongo:8".

with_replica_set_name()

MongoDBImage & testcontainers::modules::MongoDBImage::with_replica_set_name ( std::string name )

inline

Rename the replica set (default "rs0").

Letters, digits, '-' and '_' only — anything else makes start() throw up front. The name never appears in connection_string() (clients connect directly), but is visible in rs.status() and via MongoDBContainer::replica_set_name().

with_database()

MongoDBImage & testcontainers::modules::MongoDBImage::with_database ( std::string database )

inline

Set the database that a no-argument connection_string() points at (default "test").

MongoDB creates databases lazily on first write, so nothing is provisioned server-side. Use a valid MongoDB database name — the value also becomes mongosh()'s positional argument, where a name with ':' or '/' would parse as a connection string instead.

with_env()

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

inline

Set an extra environment variable (TZ and friends).

Do not set MONGO_INITDB_ROOT_USERNAME / MONGO_INITDB_ROOT_PASSWORD here: an auth-enabled replica-set member refuses to start without a cluster keyfile (see the class note), so start() throws up front on either key. The other MONGO_INITDB_* keys only affect initdb.d scripts, which this module deliberately does not stage.

with_label()

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

inline

with_network() [1/2]

MongoDBImage & testcontainers::modules::MongoDBImage::with_network ( std::string network )

inline

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

with_network() [2/2]

MongoDBImage & testcontainers::modules::MongoDBImage::with_network

(

const Network &

network

)

with_network_alias()

MongoDBImage & testcontainers::modules::MongoDBImage::with_network_alias ( std::string alias )

inline

with_reuse()

MongoDBImage & testcontainers::modules::MongoDBImage::with_reuse ( bool reuse = true )

inline

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

An adopted container's replica-set config persists in its data directory, so it is already the PRIMARY.

with_startup_timeout()

MongoDBImage & testcontainers::modules::MongoDBImage::with_startup_timeout ( std::chrono::milliseconds timeout )

inline

Budget for EACH of the two startup phases — the container-level readiness wait, and the replica-set initiation (rs.initiate + the PRIMARY election poll) that follows it — so the worst-case total is about twice this.

Default 60s per phase. Image pull time does not count against it.

with_startup_attempts()

MongoDBImage & testcontainers::modules::MongoDBImage::with_startup_attempts ( int n )

inline

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

with_customizer()

MongoDBImage & testcontainers::modules::MongoDBImage::with_customizer ( std::function< void(GenericImage &)> customize )

inline

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

Customizers run when the config is rendered (start() / to_generic()), in registration order, AFTER the module's own rendering. Caveats: the replica-set choreography lives in the rendered command, waits, and started hook — replacing any of them disables it — and MONGO_INITDB_* env set here breaks the boot (see the class note on auth; initdb scripts double-start the server and write against a not-yet-initiated member).

replica_set_name()

const std::string & testcontainers::modules::MongoDBImage::replica_set_name ( ) const

inlinenoexcept

database()

const std::string & testcontainers::modules::MongoDBImage::database ( ) const

inlinenoexcept

to_generic()

GenericImage testcontainers::modules::MongoDBImage::to_generic

(

)

const

Render the full configuration — the replica-set command line, both readiness waits, and the post-start hook that initiates the set and waits for PRIMARY — into a plain GenericImage: the drop-down escape hatch when you need a raw core Container instead of a MongoDBContainer.

Extend the result, don't rebuild it: replacing the command or the hooks disables the replica-set choreography. Throws Error on an invalid config (a replica-set name outside [A-Za-z0-9_-]; MONGO_INITDB_ROOT_* env set through with_env) before any daemon contact.

start()

MongoDBContainer testcontainers::modules::MongoDBImage::start

(

)

const

Create and start the container, initiate the replica set, and wait until the node is the writable PRIMARY.

Returns the running handle; throws — and removes the partial container — if any phase fails (StartupTimeoutError when readiness or the election never arrives, DockerError for daemon failures), like GenericImage::start().

Member Data Documentation

kDefaultImage

std::string_view testcontainers::modules::MongoDBImage::kDefaultImage = "mongo:7"

staticconstexpr

The pinned default image.

Override with with_image; any image with mongosh on the PATH works (official mongo:5.0 or newer — older images ship only the removed legacy shell and are not supported).

kPort

std::uint16_t testcontainers::modules::MongoDBImage::kPort = 27017

staticconstexpr

The server port INSIDE the container.

Peers on a shared docker network connect to <alias-or-name>:kPort (append ?directConnection=true to their URI too); the test process itself uses MongoDBContainer::port() (the mapped host port) instead.