or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-org-testcontainers--mongodb

MongoDB module for Testcontainers that provides lightweight, throwaway instances of MongoDB databases for 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.0

index.mddocs/

Testcontainers MongoDB Module

The Testcontainers MongoDB module provides lightweight, throwaway instances of MongoDB databases for testing. It includes two container types: MongoDBContainer for standard MongoDB database testing with automatic replica set initialization, and MongoDBAtlasLocalContainer for MongoDB with Atlas Search and Vector Search capabilities.

Package Information

  • Package Name: org.testcontainers:mongodb
  • Package Type: Maven
  • Language: Java
  • Installation: Add to your Maven dependencies:
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>mongodb</artifactId>
  <version>1.21.3</version>
</dependency>

For Gradle:

testImplementation 'org.testcontainers:mongodb:1.21.3'

Core Imports

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

Basic Usage

Standard MongoDB Container

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 tests
    String connectionString = mongoDBContainer.getConnectionString();
    
    // Or get a replica set URL for a specific database
    String replicaSetUrl = mongoDBContainer.getReplicaSetUrl("myTestDatabase");
    
    // Use the connection string in your MongoDB client
    // MongoClient client = MongoClients.create(connectionString);
}

MongoDB Atlas Local Container

import org.testcontainers.mongodb.MongoDBAtlasLocalContainer;

// Create and start a MongoDB Atlas Local container with search capabilities
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("mySearchDatabase");
}

Capabilities

Standard MongoDB Container

The MongoDBContainer class provides a MongoDB database instance with automatic replica set initialization to support multi-document transactions.

public class MongoDBContainer extends GenericContainer<MongoDBContainer> {
    
    // Constructors
    @Deprecated
    public MongoDBContainer();
    public MongoDBContainer(String dockerImageName);
    public MongoDBContainer(DockerImageName dockerImageName);
    
    // Connection methods
    public String getConnectionString();
    public String getReplicaSetUrl();
    public String getReplicaSetUrl(String databaseName);
    
    // Configuration methods
    public MongoDBContainer withSharding();
}

Supported Images:

  • mongo (official MongoDB image)
  • mongodb/mongodb-community-server
  • mongodb/mongodb-enterprise-server

Exposed Ports: 27017

Connection Methods

  • getConnectionString(): Returns a MongoDB connection URL without database reference
  • getReplicaSetUrl(): Returns a replica set URL for the default "test" database
  • getReplicaSetUrl(String databaseName): Returns a replica set URL for the specified database

Configuration Methods

  • withSharding(): Enables sharding on the MongoDB cluster. Returns the container instance for method chaining.

Usage Example with Sharding

try (MongoDBContainer mongoDBContainer = new MongoDBContainer("mongo:7.0")
        .withSharding()) {
    mongoDBContainer.start();
    
    String connectionString = mongoDBContainer.getConnectionString();
    // Container now runs with sharding enabled
}

MongoDB Atlas Local Container

The MongoDBAtlasLocalContainer class provides a MongoDB Atlas Local instance with search and vector search capabilities.

public class MongoDBAtlasLocalContainer extends GenericContainer<MongoDBAtlasLocalContainer> {
    
    // Constructors
    public MongoDBAtlasLocalContainer(String dockerImageName);
    public MongoDBAtlasLocalContainer(DockerImageName dockerImageName);
    
    // Connection methods
    public String getConnectionString();
    public String getDatabaseConnectionString();
    public String getDatabaseConnectionString(String databaseName);
}

Supported Images: mongodb/mongodb-atlas-local

Exposed Ports: 27017

Connection Methods

  • getConnectionString(): Returns a MongoDB connection URL with directConnection=true parameter
  • getDatabaseConnectionString(): Returns a database-specific connection string for the default "test" database
  • getDatabaseConnectionString(String databaseName): Returns a database-specific connection string for the specified database

Inherited Container Functionality

Both container classes inherit extensive functionality from Testcontainers' GenericContainer, including:

Container Lifecycle

// Container lifecycle methods
public void start();
public void stop();
public void close(); // AutoCloseable interface
public boolean isRunning();

Network and Port Access

// Network access methods
public String getHost();
public Integer getMappedPort(int originalPort);
public Integer getFirstMappedPort();

Container Configuration

// Configuration methods (fluent interface - return this)
public SELF withExposedPorts(Integer... ports);
public SELF withEnv(String key, String value);
public SELF withCommand(String... commandParts);
public SELF withLogConsumer(Consumer<OutputFrame> logConsumer);

File Operations

// File transfer methods
public void copyFileToContainer(MountableFile mountableFile, String containerPath);
public void copyFileFromContainer(String containerPath, String destinationPath);

// Command execution
public Container.ExecResult execInContainer(String... command) 
    throws UnsupportedOperationException, IOException, InterruptedException;

Types

Core Types

// From Testcontainers core
class DockerImageName {
    public static DockerImageName parse(String fullImageName);
    public DockerImageName withTag(String tag);
}

// MongoDB-specific exception
class MongoDBContainer.ReplicaSetInitializationException extends RuntimeException {
    // Thrown when replica set initialization fails
}

// Container execution result
interface Container.ExecResult {
    int getExitCode();
    String getStdout();
    String getStderr();
}

Generic Container Types

// Log output consumer
interface Consumer<OutputFrame> {
    void accept(OutputFrame frame);
}

// File transfer
class MountableFile {
    public static MountableFile forClasspathResource(String resourcePath);
    public static MountableFile forHostPath(String path);
}

Error Handling

Replica Set Initialization

The MongoDBContainer may throw a ReplicaSetInitializationException if replica set initialization fails:

try (MongoDBContainer container = new MongoDBContainer("mongo:7.0")) {
    container.start(); // May throw ReplicaSetInitializationException
} catch (MongoDBContainer.ReplicaSetInitializationException e) {
    // Handle replica set initialization failure
    System.err.println("Failed to initialize replica set: " + e.getMessage());
}

Container State Validation

Connection string methods validate container state:

try (MongoDBContainer container = new MongoDBContainer("mongo:7.0")) {
    // This will throw IllegalStateException - container not started yet
    String url = container.getReplicaSetUrl("mydb"); 
} catch (IllegalStateException e) {
    System.err.println("Container must be started first");
}

Testing Patterns

Try-with-resources Pattern

Both containers implement AutoCloseable for automatic cleanup:

@Test
public void testMongoDBOperations() {
    try (MongoDBContainer mongoDBContainer = new MongoDBContainer("mongo:7.0")) {
        mongoDBContainer.start();
        
        // Your test code here
        String connectionString = mongoDBContainer.getConnectionString();
        // Container automatically stopped and cleaned up
    }
}

JUnit Integration

Containers work seamlessly with JUnit and other testing frameworks:

class MongoDBIntegrationTest {
    
    @Test
    void shouldExecuteTransactions() {
        try (MongoDBContainer mongoDBContainer = new MongoDBContainer("mongo:7.0")) {
            mongoDBContainer.start();
            
            // Test multi-document transactions using replica set URL
            String replicaSetUrl = mongoDBContainer.getReplicaSetUrl();
            // Execute your transaction test logic
        }
    }
    
    @Test 
    void shouldPerformAtlasSearchOperations() {
        try (MongoDBAtlasLocalContainer container = 
                new MongoDBAtlasLocalContainer("mongodb/mongodb-atlas-local:7.0.9")) {
            container.start();
            
            // Test Atlas search and vector search functionality
            String connectionString = container.getDatabaseConnectionString("searchdb");
            // Execute your search test logic
        }
    }
}