Testcontainers RabbitMQ

A specialized Testcontainers module that provides throwaway RabbitMQ containers for Java integration testing. This module extends GenericContainer to offer RabbitMQ-specific functionality including credential configuration, SSL/TLS setup, custom configuration files, and convenient access methods for AMQP and management endpoints.

Key Information for Agents

Required Dependencies:

• org.testcontainers:rabbitmq (this package)
• org.testcontainers:testcontainers is required (provided transitively)
• com.rabbitmq:amqp-client is recommended for connecting to the container (not required by testcontainers itself)
• Docker must be installed and running
• JUnit 4 or JUnit 5 for test framework integration (optional but recommended)

Core Classes:

• RabbitMQContainer - Main container class extending GenericContainer<RabbitMQContainer>
• RabbitMQContainer.SslVerification - Enum for SSL verification modes (VERIFY_NONE, VERIFY_PEER)
• Inherits all methods from GenericContainer including start(), stop(), execInContainer(), getLogs(), isRunning(), withEnv(), withNetwork(), withReuse(), withStartupTimeout()

Default Behaviors:

• Default image: rabbitmq:3.7.25-management-alpine (when using deprecated no-arg constructor)
• Default credentials: username="guest", password="guest"
• Default exposed ports: 5672 (AMQP), 5671 (AMQPS), 15672 (HTTP management), 15671 (HTTPS management)
• Port mapping: Random available ports on host (use getAmqpPort(), getHttpPort(), etc. to retrieve)
• Health check: Waits for "Server startup complete" message in container logs
• Startup timeout: Inherited from GenericContainer (typically 60 seconds, configurable via withStartupTimeout())
• Container reuse: Not enabled by default (new container per test)
• Network isolation: Each container runs in isolated network by default
• SSL/TLS: Disabled by default (requires explicit configuration with withSSL())
• Configuration files: No custom configuration by default (uses RabbitMQ defaults)
• Wait strategy: Log-based wait strategy (monitors container logs for "Server startup complete")
• Virtual host: Default vhost "/" is available immediately after startup
• Management plugin: Included in -management image variants (required for HTTP/HTTPS endpoints and rabbitmqadmin)

Threading Model:

• Container operations are synchronous (blocking)
• start() method blocks until container is ready (waits for health check)
• stop() method blocks until container is stopped
• Container instances are not thread-safe for concurrent modification
• Multiple containers can run concurrently in separate instances (each gets unique ports)
• Client connections from RabbitMQ Java client are independent of container lifecycle
• Container lifecycle methods should not be called concurrently on the same instance
• Use @ClassRule or @Rule for JUnit 4, or @Container for JUnit 5 to manage lifecycle
• execInContainer() executes synchronously and blocks until command completes
• Access methods (getAmqpPort(), getAmqpUrl(), etc.) are thread-safe for read operations once container is started

Lifecycle:

• Container must be started with container.start() before use
• Container automatically waits for health check to pass before start() returns
• Container must be stopped with container.stop() for cleanup
• Always stop containers in finally blocks or use try-with-resources
• Container stops automatically when try-with-resources block exits
• Failed containers may leave Docker resources; always call stop() even on errors
• Use try-with-resources syntax for automatic disposal (recommended pattern)
• Container configuration must be set before calling start()
• execInContainer() can only be called after container has started
• Container logs are available via getLogs() after start
• Container state: isRunning() returns true after successful start(), false after stop()
• Port values remain valid only while container is running; accessing ports after stop() may return stale values

Exceptions:

• ContainerLaunchException - Container failed to start (timeout, image pull failure, port binding conflicts, etc.)
• IllegalStateException - Container not started when accessing ports/URLs (call start() first)
• PortBindingException - Port binding conflicts (rare, Testcontainers usually handles automatically)
• DockerNotAvailableException - Docker daemon not accessible (check Docker is running)
• ImagePullException - Failed to pull Docker image (network issues, invalid image tags)
• TimeoutException - Health check timeout (container started but not ready within timeout period)
• IOException from execInContainer() - Command execution failures (command not found, permission denied)
• Network errors from RabbitMQ clients - Connection failures, authentication errors, connection refused
• TimeoutException from RabbitMQ clients - Connection timeout errors (container not ready, network issues)
• ShutdownSignalException from RabbitMQ clients - Connection closed unexpectedly (container stopped, network issues)
• IllegalArgumentException - Invalid configuration (null parameters, invalid file paths, invalid SSL configuration)

Edge Cases:

• Port conflicts: Testcontainers automatically finds available ports, but conflicts can occur in CI/CD environments with limited port ranges
• Image pull failures: Network issues or invalid image tags cause startup failures (check image name and network connectivity)
• Health check timeouts: Slow container startup may exceed timeout (adjust with withStartupTimeout(Duration.ofMinutes(2)))
• Multiple containers: Each container gets unique ports; coordinate if testing multi-container scenarios (clustering, federation)
• Container reuse: Enable with withReuse(true) to reuse containers across test runs (requires testcontainers.properties configuration)
• Network isolation: Containers cannot communicate by default; use withNetwork() and withNetworkAliases() for multi-container tests
• Resource cleanup: Always stop containers even if tests fail; use try/finally or test framework hooks
• Concurrent tests: Each test should use separate container instances to avoid port conflicts
• CI/CD environments: May require Docker-in-Docker or remote Docker configuration
• Credential authentication: If non-default credentials set, all RabbitMQ client connections must include credentials; getAdminUsername()/getAdminPassword() provide configured values
• SSL configuration: All three certificate files (key, cert, CA) must be valid and accessible; invalid certificates cause container startup failures
• Configuration file format: Sysctl format requires empty line at end; erlang format must be valid Erlang syntax
• Container restart: Data is lost on container restart (ephemeral storage, no persistence by default)
• execInContainer() output: Returns ExecResult with exit code, stdout, and stderr; check exit code for command success
• Empty password: Default password is "guest"; empty passwords may not work with all RabbitMQ versions
• Client connection timing: Wait for start() to return before connecting clients; container may need additional time to be fully ready (add small delay if needed)
• File system permissions: MountableFile resources must be readable; classpath resources must exist
• Configuration file loading: Happens during startup; large files may slow container start
• RabbitMQ version compatibility: Different RabbitMQ versions may have different configuration syntax; verify image version matches requirements
• Management plugin: Required for HTTP/HTTPS endpoints; included in -management image variants
• Virtual hosts: Default vhost is "/"; create additional vhosts using execInContainer() with rabbitmqctl
• Queue durability: Queues declared as durable survive container restart only if data persistence is configured (not default)
• Connection factory timeout: Set appropriate timeouts on ConnectionFactory (connectionTimeout, handshakeTimeout) to avoid hanging on connection failures
• Container logs: Large log output may cause memory issues; use getLogs() sparingly or with limits
• execInContainer() command format: Commands are split by spaces; use array syntax for complex commands with arguments
• RabbitMQ client version: Ensure RabbitMQ Java client version is compatible with RabbitMQ server version in container
• Network host mode: Containers use bridge network by default; host network mode not supported (use port mapping instead)
• Container image tags: Use specific version tags (e.g., "rabbitmq:3.12-management-alpine") for reproducible tests
• Memory limits: Containers inherit Docker memory limits; RabbitMQ may fail to start if memory is too low
• Disk space: Containers use ephemeral storage; ensure sufficient disk space for container images and logs

Common Patterns:

• Basic Container Setup: Create container → Configure (optional) → Start → Use → Stop
• JUnit Integration: Use @Container (JUnit 5) or @ClassRule (JUnit 4) for automatic lifecycle management
• Try-With-Resources: Use try-with-resources for automatic cleanup (recommended)
• Connection Setup: Get URL → Create ConnectionFactory → Configure → Connect → Use Channel
• Queue Operations: Declare queue → Publish messages → Consume messages → Verify
• Management API: Get HTTP URL → Create HTTP client → Authenticate → Call API endpoints
• Multi-Container Tests: Create network → Add containers to network → Use network aliases for discovery
• SSL Setup: Prepare certificates → Configure container SSL → Configure client SSL → Connect via AMQPS
• Configuration: Create config file → Mount to container → Start container → Verify configuration

Integration Points:

• Works with RabbitMQ Java client (com.rabbitmq:amqp-client) for AMQP operations
• Integrates with JUnit 4 (@ClassRule, @Rule) and JUnit 5 (@Container, @Testcontainers)
• Uses Testcontainers GenericContainer for base container functionality
• Supports Docker Compose for multi-container scenarios (via GenericContainer)
• Compatible with Spring Boot Testcontainers support (auto-configuration)
• Works with any AMQP-compatible client library (not just Java client)

Package Information

• Package Name: org.testcontainers:rabbitmq

• Package Type: maven

• Language: Java

• Installation:

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

  Gradle:

  testImplementation 'org.testcontainers:rabbitmq:1.21.4'

Core Imports

import org.testcontainers.containers.RabbitMQContainer;
import org.testcontainers.utility.DockerImageName;

For SSL configuration:

import org.testcontainers.containers.RabbitMQContainer.SslVerification;
import org.testcontainers.utility.MountableFile;

For RabbitMQ client:

import com.rabbitmq.client.Connection;
import com.rabbitmq.client.ConnectionFactory;
import com.rabbitmq.client.Channel;

For container execution:

import org.testcontainers.containers.ExecResult;

Basic Usage

Minimal Example

import org.testcontainers.containers.RabbitMQContainer;
import com.rabbitmq.client.Connection;
import com.rabbitmq.client.ConnectionFactory;
import com.rabbitmq.client.Channel;

// Create and start RabbitMQ container
try (RabbitMQContainer rabbitmq = new RabbitMQContainer(
        DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))) {
    rabbitmq.start();

    // Get connection details
    String amqpUrl = rabbitmq.getAmqpUrl();
    String username = rabbitmq.getAdminUsername();  // "guest"
    String password = rabbitmq.getAdminPassword();  // "guest"

    // Connect using RabbitMQ Java client
    ConnectionFactory factory = new ConnectionFactory();
    factory.setUri(amqpUrl);
    factory.setUsername(username);
    factory.setPassword(password);

    try (Connection connection = factory.newConnection();
         Channel channel = connection.createChannel()) {
        
        // Use RabbitMQ for testing
        channel.queueDeclare("test-queue", false, false, false, null);
        channel.basicPublish("", "test-queue", null, "Hello".getBytes());
    }
    
    // Container automatically stops and removes when try-with-resources completes
}

With Error Handling

import org.testcontainers.containers.RabbitMQContainer;
import org.testcontainers.utility.DockerImageName;
import com.rabbitmq.client.Connection;
import com.rabbitmq.client.ConnectionFactory;
import com.rabbitmq.client.Channel;

RabbitMQContainer rabbitmq = null;
Connection connection = null;

try {
    rabbitmq = new RabbitMQContainer(
        DockerImageName.parse("rabbitmq:3.7.25-management-alpine"));
    rabbitmq.start();

    ConnectionFactory factory = new ConnectionFactory();
    factory.setUri(rabbitmq.getAmqpUrl());
    factory.setUsername(rabbitmq.getAdminUsername());
    factory.setPassword(rabbitmq.getAdminPassword());
    factory.setConnectionTimeout(5000);
    
    connection = factory.newConnection();
    Channel channel = connection.createChannel();
    
    channel.queueDeclare("test-queue", false, false, false, null);
    channel.basicPublish("", "test-queue", null, "Hello".getBytes());
    
} catch (Exception e) {
    System.err.println("Test failed: " + e.getMessage());
    throw e;
} finally {
    if (connection != null) {
        try {
            connection.close();
        } catch (Exception e) {
            // Log but don't throw
        }
    }
    if (rabbitmq != null) {
        rabbitmq.stop();
    }
}

Custom Credentials

try (RabbitMQContainer rabbitmq = new RabbitMQContainer(
        DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
        .withAdminUser("admin")
        .withAdminPassword("secretpassword")) {
    rabbitmq.start();
    
    // Use with custom credentials
    ConnectionFactory factory = new ConnectionFactory();
    factory.setUri(rabbitmq.getAmqpUrl());
    factory.setUsername(rabbitmq.getAdminUsername());  // "admin"
    factory.setPassword(rabbitmq.getAdminPassword());  // "secretpassword"
    
    Connection connection = factory.newConnection();
    // Use connection for testing
}

JUnit 5 Integration

import org.junit.jupiter.api.Test;
import org.testcontainers.containers.RabbitMQContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.utility.DockerImageName;
import com.rabbitmq.client.ConnectionFactory;
import com.rabbitmq.client.Connection;
import com.rabbitmq.client.Channel;

@Testcontainers
public class RabbitMQIntegrationTest {
    
    @Container
    static RabbitMQContainer rabbitmq = new RabbitMQContainer(
        DockerImageName.parse("rabbitmq:3.7.25-management-alpine"));
    
    @Test
    public void testRabbitMQConnection() throws Exception {
        ConnectionFactory factory = new ConnectionFactory();
        factory.setUri(rabbitmq.getAmqpUrl());
        factory.setUsername(rabbitmq.getAdminUsername());
        factory.setPassword(rabbitmq.getAdminPassword());
        
        try (Connection connection = factory.newConnection();
             Channel channel = connection.createChannel()) {
            
            channel.queueDeclare("test-queue", false, false, false, null);
            channel.basicPublish("", "test-queue", null, "Hello".getBytes());
        }
    }
}

JUnit 4 Integration

import org.junit.ClassRule;
import org.junit.Test;
import org.testcontainers.containers.RabbitMQContainer;
import org.testcontainers.utility.DockerImageName;
import com.rabbitmq.client.ConnectionFactory;
import com.rabbitmq.client.Connection;
import com.rabbitmq.client.Channel;

public class RabbitMQIntegrationTest {
    
    @ClassRule
    public static RabbitMQContainer rabbitmq = new RabbitMQContainer(
        DockerImageName.parse("rabbitmq:3.7.25-management-alpine"));
    
    @Test
    public void testRabbitMQConnection() throws Exception {
        ConnectionFactory factory = new ConnectionFactory();
        factory.setUri(rabbitmq.getAmqpUrl());
        factory.setUsername(rabbitmq.getAdminUsername());
        factory.setPassword(rabbitmq.getAdminPassword());
        
        try (Connection connection = factory.newConnection();
             Channel channel = connection.createChannel()) {
            
            channel.queueDeclare("test-queue", false, false, false, null);
            channel.basicPublish("", "test-queue", null, "Hello".getBytes());
        }
    }
}

Architecture

RabbitMQContainer extends the Testcontainers GenericContainer class, providing:

• Lifecycle Management: Automatic container start/stop with Java try-with-resources or JUnit rules
• Port Mapping: Automatic mapping of RabbitMQ ports (AMQP, AMQPS, HTTP, HTTPS) to random available host ports
• Wait Strategy: Built-in wait strategy that monitors container logs for "Server startup complete" message
• Configuration: Fluent API for configuring credentials, SSL, and custom RabbitMQ configuration files
• Access Methods: Convenience methods to retrieve connection URLs and mapped ports
• Command Execution: Inherited execInContainer() method for executing rabbitmqctl and rabbitmqadmin commands

The container exposes four ports:

• 5672 (AMQP): Default messaging protocol port
• 5671 (AMQPS): Secure AMQP with SSL/TLS
• 15672 (HTTP): Management UI and API
• 15671 (HTTPS): Secure management UI and API

Default configuration uses the official RabbitMQ Docker image with management plugin enabled (rabbitmq:3.7.25-management-alpine) and guest/guest credentials.

Capabilities

Container Creation

Create RabbitMQ containers with default or custom Docker images.

/**
 * Creates a RabbitMQ container using the default official RabbitMQ docker image.
 * @deprecated use RabbitMQContainer(DockerImageName) instead
 */
@Deprecated
public RabbitMQContainer()

/**
 * Creates a RabbitMQ container using a specific docker image.
 * @param dockerImageName The docker image to use
 */
public RabbitMQContainer(String dockerImageName)

/**
 * Creates a RabbitMQ container using a specific DockerImageName.
 * @param dockerImageName The docker image to use
 */
public RabbitMQContainer(DockerImageName dockerImageName)

Usage Examples:

// Recommended: Use DockerImageName for version pinning
RabbitMQContainer container = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"));

// Alternative: String constructor (less type-safe)
RabbitMQContainer container = new RabbitMQContainer("rabbitmq:3.7.25-management-alpine");

// Use specific version
RabbitMQContainer container = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.12-management-alpine"));

Configuration

Container Configuration

Configure RabbitMQ container with custom credentials, SSL/TLS certificates, and configuration files. Includes methods for setting admin username and password, enabling SSL with custom certificates, and mounting custom RabbitMQ configuration files in sysctl or erlang formats.

public RabbitMQContainer withAdminUser(String adminUsername)
public RabbitMQContainer withAdminPassword(String adminPassword)
public String getAdminUsername()
public String getAdminPassword()

public RabbitMQContainer withSSL(
    MountableFile keyFile,
    MountableFile certFile,
    MountableFile caFile,
    SslVerification verify
)

public RabbitMQContainer withRabbitMQConfig(MountableFile rabbitMQConf)
public RabbitMQContainer withRabbitMQConfigSysctl(MountableFile rabbitMQConf)
public RabbitMQContainer withRabbitMQConfigErlang(MountableFile rabbitMQConf)

public enum SslVerification {
    VERIFY_NONE,
    VERIFY_PEER
}

Configuration

Access Methods

Retrieve connection URLs and mapped ports for AMQP, AMQPS, HTTP, and HTTPS endpoints. These methods provide the host and port information needed to connect to the RabbitMQ container from your test code.

public Integer getAmqpPort()
public Integer getAmqpsPort()
public Integer getHttpPort()
public Integer getHttpsPort()

public String getAmqpUrl()
public String getAmqpsUrl()
public String getHttpUrl()
public String getHttpsUrl()

Access Methods

Deprecated Declarative Configuration

Legacy declarative methods for configuring RabbitMQ entities (queues, exchanges, bindings, users, vhosts, policies). These methods are deprecated in favor of using the inherited execInContainer(String...) method to execute rabbitmqadmin or rabbitmqctl commands directly after the container starts.

@Deprecated public RabbitMQContainer withPluginsEnabled(String... pluginNames)
@Deprecated public RabbitMQContainer withQueue(String name)
@Deprecated public RabbitMQContainer withExchange(String name, String type)
@Deprecated public RabbitMQContainer withBinding(String source, String destination)
@Deprecated public RabbitMQContainer withUser(String name, String password)
@Deprecated public RabbitMQContainer withVhost(String name)
@Deprecated public RabbitMQContainer withPolicy(String name, String pattern, Map<String, Object> definition)
@Deprecated public RabbitMQContainer withPermission(String vhost, String user, String configure, String write, String read)

Deprecated API

Inherited Functionality

RabbitMQContainer inherits all methods from GenericContainer<RabbitMQContainer>, including:

• start() - Starts the container (blocks until ready)
• stop() - Stops the container (blocks until stopped)
• execInContainer(String... command) - Executes a command inside the container (recommended for RabbitMQ configuration)
• withEnv(String key, String value) - Sets environment variables
• withCopyFileToContainer(MountableFile file, String path) - Copies files into the container
• getHost() - Gets the container host address (typically "localhost")
• getMappedPort(int originalPort) - Gets the mapped port on the host
• getLogs() - Gets container logs as String
• isRunning() - Checks if container is running
• withStartupTimeout(Duration timeout) - Configures startup timeout
• withReuse(boolean reuse) - Enables container reuse across test runs
• withNetwork(Network network) - Configures container network
• withNetworkAliases(String... aliases) - Sets network aliases for container discovery

For RabbitMQ administration tasks, prefer using execInContainer() to execute rabbitmqctl or rabbitmqadmin commands directly:

// Execute rabbitmqctl command
ExecResult result = container.execInContainer("rabbitmqctl", "list_queues");
System.out.println(result.getStdout());

// Execute rabbitmqadmin command
container.execInContainer("rabbitmqadmin", "declare", "queue", "name=my-queue");

// Check command success
ExecResult result = container.execInContainer("rabbitmqctl", "status");
if (result.getExitCode() != 0) {
    throw new RuntimeException("Command failed: " + result.getStderr());
}

Common Patterns

Container Reuse

// Enable container reuse (requires testcontainers.properties configuration)
RabbitMQContainer container = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withReuse(true);

Network Configuration

import org.testcontainers.containers.Network;

Network network = Network.newNetwork();
RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withNetwork(network)
    .withNetworkAliases("rabbitmq");

Custom Startup Timeout

import java.time.Duration;

RabbitMQContainer container = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withStartupTimeout(Duration.ofMinutes(2));

Debugging Container Issues

RabbitMQContainer container = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"));

try {
    container.start();
} catch (Exception e) {
    // Print container logs for debugging
    System.err.println("Container logs:\n" + container.getLogs());
    throw e;
}

Queue and Exchange Operations via AMQP Client

try (RabbitMQContainer rabbitmq = new RabbitMQContainer(
        DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))) {
    rabbitmq.start();
    
    ConnectionFactory factory = new ConnectionFactory();
    factory.setUri(rabbitmq.getAmqpUrl());
    factory.setUsername(rabbitmq.getAdminUsername());
    factory.setPassword(rabbitmq.getAdminPassword());
    
    try (Connection connection = factory.newConnection();
         Channel channel = connection.createChannel()) {
        
        // Declare exchange
        channel.exchangeDeclare("test-exchange", "topic", true);
        
        // Declare queue
        channel.queueDeclare("test-queue", true, false, false, null);
        
        // Bind queue to exchange
        channel.queueBind("test-queue", "test-exchange", "test.routing.key");
        
        // Publish message
        channel.basicPublish("test-exchange", "test.routing.key", null, 
            "Hello RabbitMQ".getBytes());
    }
}

Virtual Host Management via execInContainer

try (RabbitMQContainer rabbitmq = new RabbitMQContainer(
        DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))) {
    rabbitmq.start();
    
    // Create virtual host
    ExecResult result = rabbitmq.execInContainer(
        "rabbitmqctl", "add_vhost", "test-vhost");
    if (result.getExitCode() != 0) {
        throw new RuntimeException("Failed to create vhost: " + result.getStderr());
    }
    
    // List virtual hosts
    ExecResult listResult = rabbitmq.execInContainer(
        "rabbitmqctl", "list_vhosts");
    System.out.println("Virtual hosts: " + listResult.getStdout());
}