0
# Testcontainers RabbitMQ
1

2
Testcontainers RabbitMQ module provides a specialized container implementation for integration testing with RabbitMQ message brokers. It enables developers to easily spin up throwaway RabbitMQ container instances for JUnit tests, supporting both AMQP and AMQPS protocols along with HTTP and HTTPS management interfaces.
3

4
## Package Information
5

6
- **Package Name**: org.testcontainers:rabbitmq
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to `build.gradle`: `testImplementation "org.testcontainers:rabbitmq:1.21.3"`
10
- **Installation**: Add to `pom.xml`: `<groupId>org.testcontainers</groupId><artifactId>rabbitmq</artifactId><version>1.21.3</version>`
11

12
## Core Imports
13

14
```java
15
import org.testcontainers.containers.RabbitMQContainer;
16
import org.testcontainers.utility.DockerImageName;
17
import org.testcontainers.utility.MountableFile;
18
```
19

20
For SSL configuration:
21

22
```java
23
import org.testcontainers.containers.RabbitMQContainer.SslVerification;
24
```
25

26
For testing utilities:
27

28
```java
29
import org.testcontainers.containers.RabbitMQTestImages;
30
```
31

32
## Basic Usage
33

34
```java
35
import org.testcontainers.containers.RabbitMQContainer;
36
import org.testcontainers.containers.RabbitMQTestImages;
37
import com.rabbitmq.client.Connection;
38
import com.rabbitmq.client.ConnectionFactory;
39

40
@Test
41
public void testRabbitMQ() {
42
    try (RabbitMQContainer container = new RabbitMQContainer(RabbitMQTestImages.RABBITMQ_IMAGE)) {
43
        container.start();
44
        
45
        // Get connection details
46
        String amqpUrl = container.getAmqpUrl();
47
        String adminUser = container.getAdminUsername();
48
        String adminPassword = container.getAdminPassword();
49
        
50
        // Create AMQP connection
51
        ConnectionFactory factory = new ConnectionFactory();
52
        factory.setUri(amqpUrl);
53
        factory.setUsername(adminUser);
54
        factory.setPassword(adminPassword);
55
        
56
        try (Connection connection = factory.newConnection()) {
57
            // Use the connection for testing
58
            assertThat(connection.isOpen()).isTrue();
59
        }
60
    }
61
}
62
```
63

64
## Architecture
65

66
The RabbitMQContainer extends Testcontainers' GenericContainer with RabbitMQ-specific functionality:
67

68
- **Container Management**: Automatic lifecycle management for RabbitMQ Docker containers
69
- **Port Mapping**: Exposes standard RabbitMQ ports with dynamic host port mapping
70
- **Protocol Support**: AMQP (5672), AMQPS (5671), HTTP (15672), HTTPS (15671)
71
- **SSL Configuration**: Custom certificate support for secure connections
72
- **Credential Management**: Configurable admin credentials with environment variable injection
73
- **Configuration Files**: Support for both sysctl and Erlang format configuration files
74
- **Declarative Setup**: Programmatic RabbitMQ entity creation during container startup
75

76
## Capabilities
77

78
### Container Creation and Configuration
79

80
Core container instantiation and basic configuration options.
81

82
```java { .api }
83
// Constructors
84
public RabbitMQContainer(DockerImageName dockerImageName);
85
public RabbitMQContainer(String dockerImageName);
86
@Deprecated
87
public RabbitMQContainer();
88

89
// Basic configuration
90
public RabbitMQContainer withAdminUser(String adminUsername);
91
public RabbitMQContainer withAdminPassword(String adminPassword);
92
```
93

94
### Connection Information Access
95

96
Methods to retrieve connection details and URLs for different protocols.
97

98
```java { .api }
99
// Credential access
100
public String getAdminUsername();
101
public String getAdminPassword();
102

103
// Port access
104
public Integer getAmqpPort();
105
public Integer getAmqpsPort();
106
public Integer getHttpPort();
107
public Integer getHttpsPort();
108

109
// URL generation
110
public String getAmqpUrl();
111
public String getAmqpsUrl();
112
public String getHttpUrl();
113
public String getHttpsUrl();
114
```
115

116
### SSL/TLS Configuration
117

118
SSL certificate configuration for secure connections.
119

120
```java { .api }
121
public RabbitMQContainer withSSL(
122
    MountableFile keyFile,
123
    MountableFile certFile,
124
    MountableFile caFile,
125
    SslVerification verify
126
);
127

128
public RabbitMQContainer withSSL(
129
    MountableFile keyFile,
130
    MountableFile certFile,
131
    MountableFile caFile,
132
    SslVerification verify,
133
    boolean failIfNoCert
134
);
135

136
public RabbitMQContainer withSSL(
137
    MountableFile keyFile,
138
    MountableFile certFile,
139
    MountableFile caFile,
140
    SslVerification verify,
141
    boolean failIfNoCert,
142
    int verificationDepth
143
);
144
```
145

146
### Configuration File Management
147

148
Custom RabbitMQ configuration file support.
149

150
```java { .api }
151
// Generic config (delegates to sysctl format)
152
public RabbitMQContainer withRabbitMQConfig(MountableFile rabbitMQConf);
153

154
// Sysctl format (RabbitMQ >= 3.7)
155
public RabbitMQContainer withRabbitMQConfigSysctl(MountableFile rabbitMQConf);
156

157
// Erlang format
158
public RabbitMQContainer withRabbitMQConfigErlang(MountableFile rabbitMQConf);
159
```
160

161
### Container Lifecycle Management
162

163
Inherited methods from GenericContainer for container lifecycle management.
164

165
```java { .api }
166
// Container lifecycle
167
public void start();
168
public void stop();
169
public void close();
170
public boolean isRunning();
171

172
// Container interaction
173
public String getLogs();
174
public ExecResult execInContainer(String... command) throws IOException, InterruptedException;
175
```
176

177
### Deprecated Declarative Configuration
178

179
Legacy methods for programmatic RabbitMQ entity creation. **Use `execInContainer()` instead.**
180

181
```java { .api }
182
// Plugin management
183
@Deprecated
184
public RabbitMQContainer withPluginsEnabled(String... pluginNames);
185

186
// Queue management
187
@Deprecated
188
public RabbitMQContainer withQueue(String name);
189
@Deprecated
190
public RabbitMQContainer withQueue(String vhost, String name);
191
@Deprecated
192
public RabbitMQContainer withQueue(String name, boolean autoDelete, boolean durable, Map<String, Object> arguments);
193
@Deprecated
194
public RabbitMQContainer withQueue(String vhost, String name, boolean autoDelete, boolean durable, Map<String, Object> arguments);
195

196
// Exchange management
197
@Deprecated
198
public RabbitMQContainer withExchange(String name, String type);
199
@Deprecated
200
public RabbitMQContainer withExchange(String vhost, String name, String type);
201
@Deprecated
202
public RabbitMQContainer withExchange(String name, String type, boolean autoDelete, boolean internal, boolean durable, Map<String, Object> arguments);
203
@Deprecated
204
public RabbitMQContainer withExchange(String vhost, String name, String type, boolean autoDelete, boolean internal, boolean durable, Map<String, Object> arguments);
205

206
// Binding management
207
@Deprecated
208
public RabbitMQContainer withBinding(String source, String destination);
209
@Deprecated
210
public RabbitMQContainer withBinding(String vhost, String source, String destination);
211
@Deprecated
212
public RabbitMQContainer withBinding(String source, String destination, Map<String, Object> arguments, String routingKey, String destinationType);
213
@Deprecated
214
public RabbitMQContainer withBinding(String vhost, String source, String destination, Map<String, Object> arguments, String routingKey, String destinationType);
215

216
// User and permission management
217
@Deprecated
218
public RabbitMQContainer withUser(String name, String password);
219
@Deprecated
220
public RabbitMQContainer withUser(String name, String password, Set<String> tags);
221
@Deprecated
222
public RabbitMQContainer withPermission(String vhost, String user, String configure, String write, String read);
223

224
// Virtual host management
225
@Deprecated
226
public RabbitMQContainer withVhost(String name);
227
@Deprecated
228
public RabbitMQContainer withVhost(String name, boolean tracing);
229
@Deprecated
230
public RabbitMQContainer withVhostLimit(String vhost, String name, int value);
231

232
// Policy management
233
@Deprecated
234
public RabbitMQContainer withPolicy(String name, String pattern, Map<String, Object> definition);
235
@Deprecated
236
public RabbitMQContainer withPolicy(String vhost, String name, String pattern, Map<String, Object> definition);
237
@Deprecated
238
public RabbitMQContainer withPolicy(String name, String pattern, Map<String, Object> definition, int priority, String applyTo);
239
@Deprecated
240
public RabbitMQContainer withOperatorPolicy(String name, String pattern, Map<String, Object> definition);
241
@Deprecated
242
public RabbitMQContainer withOperatorPolicy(String name, String pattern, Map<String, Object> definition, int priority, String applyTo);
243

244
// Parameter management
245
@Deprecated
246
public RabbitMQContainer withParameter(String component, String name, String value);
247
```
248

249
## Types
250

251
```java { .api }
252
// SSL verification options
253
public enum SslVerification {
254
    VERIFY_NONE("verify_none"),  // No SSL peer verification
255
    VERIFY_PEER("verify_peer")   // Verify SSL peer certificates
256
}
257

258
// Test image constants
259
public interface RabbitMQTestImages {
260
    DockerImageName RABBITMQ_IMAGE = DockerImageName.parse("rabbitmq:3.7.25-management-alpine");
261
}
262

263
// Container execution result
264
interface ExecResult {
265
    String getStdout();
266
    String getStderr();
267
    int getExitCode();
268
}
269
```
270

271
## Usage Examples
272

273
### Custom Credentials
274

275
```java
276
@Test
277
public void testWithCustomCredentials() {
278
    try (RabbitMQContainer container = new RabbitMQContainer(RabbitMQTestImages.RABBITMQ_IMAGE)
279
            .withAdminUser("admin")
280
            .withAdminPassword("secret123")) {
281
        container.start();
282
        
283
        assertEquals("admin", container.getAdminUsername());
284
        assertEquals("secret123", container.getAdminPassword());
285
    }
286
}
287
```
288

289
### SSL Configuration
290

291
```java
292
@Test
293
public void testWithSSL() {
294
    MountableFile keyFile = MountableFile.forClasspathResource("ssl/server.key");
295
    MountableFile certFile = MountableFile.forClasspathResource("ssl/server.crt");
296
    MountableFile caFile = MountableFile.forClasspathResource("ssl/ca.crt");
297
    
298
    try (RabbitMQContainer container = new RabbitMQContainer(RabbitMQTestImages.RABBITMQ_IMAGE)
299
            .withSSL(keyFile, certFile, caFile, SslVerification.VERIFY_PEER)) {
300
        container.start();
301
        
302
        String amqpsUrl = container.getAmqpsUrl();
303
        assertTrue(amqpsUrl.startsWith("amqps://"));
304
    }
305
}
306
```
307

308
### Modern Entity Management (Recommended)
309

310
```java
311
@Test
312
public void testWithModernConfiguration() throws Exception {
313
    try (RabbitMQContainer container = new RabbitMQContainer(RabbitMQTestImages.RABBITMQ_IMAGE)) {
314
        container.start();
315
        
316
        // Use execInContainer for RabbitMQ configuration
317
        container.execInContainer("rabbitmq-plugins", "enable", "rabbitmq_management");
318
        container.execInContainer("rabbitmqadmin", "declare", "queue", "name=test-queue");
319
        container.execInContainer("rabbitmqadmin", "declare", "exchange", "name=test-exchange", "type=direct");
320
        container.execInContainer("rabbitmqadmin", "declare", "binding", 
321
            "source=test-exchange", "destination=test-queue");
322
        
323
        // Verify configuration
324
        ExecResult result = container.execInContainer("rabbitmqctl", "list_queues");
325
        assertTrue(result.getStdout().contains("test-queue"));
326
    }
327
}
328
```
329

330
### Custom Configuration File
331

332
```java
333
@Test
334
public void testWithCustomConfig() {
335
    MountableFile configFile = MountableFile.forClasspathResource("rabbitmq-custom.conf");
336
    
337
    try (RabbitMQContainer container = new RabbitMQContainer(RabbitMQTestImages.RABBITMQ_IMAGE)
338
            .withRabbitMQConfigSysctl(configFile)) {
339
        container.start();
340
        
341
        // Container will use the custom configuration
342
    }
343
}
344
```