or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-org-testcontainers--mongodb

Testcontainers implementation for MongoDB that enables isolated database instances in Docker containers for Java unit testing

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.testcontainers/mongodb@1.21.x

To install, run

npx @tessl/cli install tessl/maven-org-testcontainers--mongodb@1.21.1

index.mddocs/

Testcontainers MongoDB Module

Testcontainers MongoDB module provides Docker container implementations for running isolated MongoDB database instances during Java unit and integration testing. The module offers two container types: MongoDBContainer for the core MongoDB database with automatic replica set initialization, and MongoDBAtlasLocalContainer which combines MongoDB with Atlas Search and Vector Search capabilities.

Package Information

  • Package Name: mongodb
  • Package Type: maven
  • GroupId: org.testcontainers
  • ArtifactId: mongodb
  • Language: Java
  • Installation:

Gradle:

testImplementation "org.testcontainers:mongodb:1.21.4"

Maven:

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>mongodb</artifactId>
    <version>1.21.4</version>
    <scope>test</scope>
</dependency>

Core Imports

import org.testcontainers.containers.MongoDBContainer;
import org.testcontainers.mongodb.MongoDBAtlasLocalContainer;
import org.testcontainers.utility.DockerImageName;

Basic Usage

Using MongoDBContainer

import org.testcontainers.containers.MongoDBContainer;

// Create and start a MongoDB container
try (MongoDBContainer mongoDBContainer = new MongoDBContainer("mongo:7.0")) {
    mongoDBContainer.start();

    // Get connection string for your MongoDB driver
    String connectionString = mongoDBContainer.getConnectionString();

    // Or get a replica set URL with database name
    String replicaSetUrl = mongoDBContainer.getReplicaSetUrl("mydb");

    // Use the connection string with your MongoDB driver
    // MongoClient mongoClient = MongoClients.create(connectionString);
}

Using MongoDBAtlasLocalContainer

import org.testcontainers.mongodb.MongoDBAtlasLocalContainer;

// Create and start a MongoDB Atlas Local container
try (MongoDBAtlasLocalContainer container =
        new MongoDBAtlasLocalContainer("mongodb/mongodb-atlas-local:7.0.9")) {
    container.start();

    // Get connection string
    String connectionString = container.getConnectionString();

    // Or get database-specific connection string
    String dbConnectionString = container.getDatabaseConnectionString("mydb");

    // Use with MongoDB driver to access Atlas Search features
    // MongoClient mongoClient = MongoClients.create(connectionString);
}

Architecture

Both container classes extend GenericContainer from the Testcontainers core library, inheriting standard container lifecycle management, port mapping, network configuration, and Docker interaction capabilities. The containers are designed to be used with Java's try-with-resources statement for automatic cleanup.

MongoDBContainer automatically initializes a single-node replica set on startup, which is required for testing MongoDB multi-document transactions. The initialization process waits for the replica set to be ready before the container is considered started.

MongoDBAtlasLocalContainer combines the MongoDB database engine with MongoT (a sidecar process for Atlas Search powered by Apache Lucene), providing local testing capabilities for Atlas Search and Vector Search features without requiring a cloud Atlas deployment.

Capabilities

MongoDBContainer - Core MongoDB Testing

MongoDBContainer provides a Testcontainers implementation for running MongoDB database instances with automatic replica set initialization for transaction testing.

package org.testcontainers.containers;

public class MongoDBContainer extends GenericContainer<MongoDBContainer> {

    // Constructors

    /**
     * Create a MongoDBContainer with default image mongo:4.0.10.
     *
     * @deprecated Use MongoDBContainer(DockerImageName) instead
     */
    @Deprecated
    public MongoDBContainer();

    /**
     * Create a MongoDBContainer with the specified Docker image name.
     * Supported images: mongo, mongodb/mongodb-community-server, mongodb/mongodb-enterprise-server
     *
     * @param dockerImageName the Docker image name (e.g., "mongo:7.0")
     */
    public MongoDBContainer(String dockerImageName);

    /**
     * Create a MongoDBContainer with the specified DockerImageName.
     *
     * @param dockerImageName the DockerImageName object
     */
    public MongoDBContainer(DockerImageName dockerImageName);

    // Connection Methods

    /**
     * Gets a connection string URL to the MongoDB instance.
     * Unlike getReplicaSetUrl(), this does not include a database name.
     *
     * @return connection string in format "mongodb://host:port"
     */
    public String getConnectionString();

    /**
     * Gets a replica set URL for the default "test" database.
     *
     * @return replica set URL in format "mongodb://host:port/test"
     */
    public String getReplicaSetUrl();

    /**
     * Gets a replica set URL for the specified database.
     *
     * @param databaseName the name of the database
     * @return replica set URL in format "mongodb://host:port/databaseName"
     * @throws IllegalStateException if container is not running
     */
    public String getReplicaSetUrl(String databaseName);

    // Configuration Methods

    /**
     * Enables sharding on the MongoDB cluster.
     * Must be called before starting the container.
     *
     * @return this MongoDBContainer instance for method chaining
     */
    public MongoDBContainer withSharding();
}

MongoDBContainer Exception Types

package org.testcontainers.containers;

/**
 * Exception thrown when MongoDB replica set initialization fails.
 */
public static class MongoDBContainer.ReplicaSetInitializationException
        extends RuntimeException {

    /**
     * Creates a new ReplicaSetInitializationException with the given error message.
     *
     * @param errorMessage description of the initialization failure
     */
    ReplicaSetInitializationException(String errorMessage);
}

MongoDBContainer Features

  • Automatic Replica Set Initialization: Automatically initializes a single-node replica set named "docker-rs" on startup, enabling multi-document transaction testing
  • Dynamic Port Allocation: Uses random available ports to avoid conflicts in parallel test execution
  • Supported Images: Compatible with mongo, mongodb/mongodb-community-server, and mongodb/mongodb-enterprise-server Docker images
  • Exposed Port: 27017 (mapped to a random host port)
  • Default Wait Strategy: Waits for "waiting for connections" log message before considering container ready
  • Sharding Support: Optional sharding mode with different startup sequence and wait strategy
  • Container Reuse: Skips replica set initialization if container is reused and already initialized

MongoDBContainer Usage Example

import org.testcontainers.containers.MongoDBContainer;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;

// Basic usage with transactions
try (MongoDBContainer container = new MongoDBContainer("mongo:7.0")) {
    container.start();

    String connectionString = container.getConnectionString();

    try (MongoClient client = MongoClients.create(connectionString)) {
        // Use client for database operations including transactions
        // Replica set is automatically initialized and ready
    }
}

// Using with specific database
try (MongoDBContainer container = new MongoDBContainer("mongo:7.0")) {
    container.start();

    String replicaSetUrl = container.getReplicaSetUrl("myapp");

    try (MongoClient client = MongoClients.create(replicaSetUrl)) {
        // Client is connected to "myapp" database
    }
}

// Using with sharding enabled
try (MongoDBContainer container = new MongoDBContainer("mongo:7.0")) {
    container.withSharding().start();

    String connectionString = container.getConnectionString();
    // Container now has sharding enabled
}

MongoDBAtlasLocalContainer - Atlas Search Testing

MongoDBAtlasLocalContainer provides a Testcontainers implementation for MongoDB Atlas Local, which combines the MongoDB database engine with Atlas Search and Vector Search capabilities for local testing.

package org.testcontainers.mongodb;

public class MongoDBAtlasLocalContainer
        extends GenericContainer<MongoDBAtlasLocalContainer> {

    // Constructors

    /**
     * Create a MongoDBAtlasLocalContainer with the specified Docker image name.
     * Supported image: mongodb/mongodb-atlas-local
     *
     * @param dockerImageName the Docker image name (e.g., "mongodb/mongodb-atlas-local:7.0.9")
     */
    public MongoDBAtlasLocalContainer(String dockerImageName);

    /**
     * Create a MongoDBAtlasLocalContainer with the specified DockerImageName.
     *
     * @param dockerImageName the DockerImageName object
     */
    public MongoDBAtlasLocalContainer(DockerImageName dockerImageName);

    // Connection Methods

    /**
     * Gets the connection string to MongoDB.
     * Includes the directConnection=true parameter required for Atlas Local.
     *
     * @return connection string in format "mongodb://host:port/?directConnection=true"
     */
    public String getConnectionString();

    /**
     * Gets a database-specific connection string for the default "test" database.
     *
     * @return database connection string in format
     *         "mongodb://host:port/test?directConnection=true"
     */
    public String getDatabaseConnectionString();

    /**
     * Gets a database-specific connection string for the specified database.
     *
     * @param databaseName the name of the database
     * @return database connection string in format
     *         "mongodb://host:port/databaseName?directConnection=true"
     * @throws IllegalStateException if container is not running
     */
    public String getDatabaseConnectionString(String databaseName);
}

MongoDBAtlasLocalContainer Features

  • Atlas Search Integration: Includes MongoT sidecar process for Atlas Search functionality powered by Apache Lucene
  • Vector Search Support: Enables testing of Vector Search features locally
  • Direct Connection Mode: All connection strings include directConnection=true parameter
  • Dynamic Port Allocation: Uses random available ports to avoid conflicts
  • Supported Images: Compatible with mongodb/mongodb-atlas-local Docker images
  • Exposed Port: 27017 (mapped to a random host port)
  • Health Check Wait Strategy: Waits for "runner healthcheck" command to succeed before considering container ready
  • Default Database: Uses "test" as the default database name

MongoDBAtlasLocalContainer Usage Example

import org.testcontainers.mongodb.MongoDBAtlasLocalContainer;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.MongoCollection;
import org.bson.Document;

// Basic usage
try (MongoDBAtlasLocalContainer container =
        new MongoDBAtlasLocalContainer("mongodb/mongodb-atlas-local:7.0.9")) {
    container.start();

    String connectionString = container.getConnectionString();

    try (MongoClient client = MongoClients.create(connectionString)) {
        // Use client for database operations with Atlas Search
        MongoDatabase database = client.getDatabase("test");
        MongoCollection<Document> collection = database.getCollection("products");

        // Create Atlas Search indexes and perform searches
        // Note: Atlas Search is eventually consistent, may need polling
    }
}

// Using with specific database
try (MongoDBAtlasLocalContainer container =
        new MongoDBAtlasLocalContainer("mongodb/mongodb-atlas-local:7.0.9")) {
    container.start();

    String dbConnectionString = container.getDatabaseConnectionString("searchdb");

    try (MongoClient client = MongoClients.create(dbConnectionString)) {
        // Client is connected to "searchdb" database
        // Use Atlas Search and Vector Search features
    }
}

Inherited Container Methods

Both MongoDBContainer and MongoDBAtlasLocalContainer inherit methods from GenericContainer in the Testcontainers core library:

Lifecycle Management

// Start the container
public void start();

// Stop the container
public void stop();

// Check if container is running
public boolean isRunning();

Port and Network Access

// Get the container host (typically "localhost")
public String getHost();

// Get the mapped host port for an internal container port
public Integer getMappedPort(int originalPort);

// Get the first mapped port
public Integer getFirstMappedPort();

Configuration (Fluent API)

// Expose additional ports
public SELF withExposedPorts(Integer... ports);

// Set environment variables
public SELF withEnv(String key, String value);

// Set container command
public SELF withCommand(String... commandParts);

// Set wait strategy
public SELF waitingFor(WaitStrategy waitStrategy);

Container Operations

// Execute command in running container
public Container.ExecResult execInContainer(String... command)
    throws IOException, InterruptedException;

Resource Management

Both containers implement AutoCloseable and can be used with try-with-resources:

try (MongoDBContainer container = new MongoDBContainer("mongo:7.0")) {
    container.start();
    // Use container
} // Automatically stopped and cleaned up

Notes

  • MongoDB Driver Required: This module provides only the container infrastructure. You must add a MongoDB driver dependency (e.g., org.mongodb:mongodb-driver-sync) to your project to connect to the containers
  • Docker Required: Testcontainers requires a Docker environment to be available
  • Test Scope: This library is typically added with test scope as it's intended for testing purposes
  • Replica Set Transactions: MongoDBContainer's automatic replica set initialization enables testing of multi-document transactions, which require a replica set in MongoDB 4.0+
  • Atlas Search Consistency: Atlas Search in MongoDBAtlasLocalContainer is eventually consistent - tests may need to poll or wait for indexes to be updated after data insertion
  • Port Conflicts: Both containers use dynamic port allocation, making them safe for parallel test execution
  • Image Compatibility: Always verify that the Docker image version you specify is compatible with your MongoDB driver version
  • Connection Strings: MongoDBContainer provides both simple connection strings and replica-set URLs, while MongoDBAtlasLocalContainer always includes the directConnection=true parameter