0
# Testcontainers Utility
1
2
Core utility class providing global Testcontainers configuration and host-container integration capabilities, particularly for exposing host services to containers.
3
4
## Capabilities
5
6
### Host Port Exposure
7
8
Enable containers to access services running on the host machine by exposing specific host ports to containers.
9
10
```java { .api }
11
/**
12
* Main utility class for Testcontainers global configuration
13
*/
14
public class Testcontainers {
15
16
/**
17
* Expose specific host ports to containers
18
* @param ports Host port numbers to expose
19
*/
20
public static void exposeHostPorts(int... ports);
21
22
/**
23
* Expose host ports with custom port mapping
24
* @param ports Map of host port to container port mappings
25
*/
26
public static void exposeHostPorts(Map<Integer, Integer> ports);
27
}
28
```
29
30
**Usage Examples:**
31
32
```java
33
import org.testcontainers.Testcontainers;
34
import org.testcontainers.containers.GenericContainer;
35
import org.testcontainers.utility.DockerImageName;
36
37
class HostIntegrationTest {
38
39
@Test
40
void testContainerAccessingHostService() {
41
// Start a local service on port 8080 (e.g., Spring Boot app)
42
// ...
43
44
// Expose host port 8080 to containers
45
Testcontainers.exposeHostPorts(8080);
46
47
try (GenericContainer<?> container = new GenericContainer<>(DockerImageName.parse("appropriate-test-image"))
48
.withCommand("curl", "http://host.testcontainers.internal:8080/api/health")) {
49
50
container.start();
51
52
// Container can now access host service on port 8080
53
// via host.testcontainers.internal:8080
54
String logs = container.getLogs();
55
assertThat(logs).contains("200 OK");
56
}
57
}
58
59
@Test
60
void testMultipleHostPorts() {
61
// Expose multiple host ports
62
Testcontainers.exposeHostPorts(8080, 9090, 3000);
63
64
try (GenericContainer<?> container = new GenericContainer<>("test-image")) {
65
container.start();
66
// Container can access host services on ports 8080, 9090, and 3000
67
// via host.testcontainers.internal:{port}
68
}
69
}
70
71
@Test
72
void testCustomPortMapping() {
73
// Map host ports to different container ports
74
Map<Integer, Integer> portMapping = Map.of(
75
8080, 80, // Host port 8080 -> Container port 80
76
9090, 90 // Host port 9090 -> Container port 90
77
);
78
79
Testcontainers.exposeHostPorts(portMapping);
80
81
try (GenericContainer<?> container = new GenericContainer<>("test-image")) {
82
container.start();
83
// Container accesses host:8080 via host.testcontainers.internal:80
84
// Container accesses host:9090 via host.testcontainers.internal:90
85
}
86
}
87
}
88
```
89
90
### Integration Patterns
91
92
Common patterns for integrating containerized tests with host services and external dependencies.
93
94
**Database on Host, Application in Container:**
95
96
```java
97
@Test
98
void testAppWithHostDatabase() {
99
// Start PostgreSQL on host (port 5432)
100
// ...
101
102
// Expose PostgreSQL port to container
103
Testcontainers.exposeHostPorts(5432);
104
105
try (GenericContainer<?> app = new GenericContainer<>("my-app:latest")
106
.withEnv("DB_HOST", "host.testcontainers.internal")
107
.withEnv("DB_PORT", "5432")
108
.withExposedPorts(8080)) {
109
110
app.start();
111
112
// Application container connects to PostgreSQL on host
113
String appUrl = "http://" + app.getHost() + ":" + app.getMappedPort(8080);
114
// ... test application behavior
115
}
116
}
117
```
118
119
**Mock Service on Host:**
120
121
```java
122
@Test
123
void testWithMockService() {
124
// Start mock HTTP server on host
125
MockWebServer mockServer = new MockWebServer();
126
mockServer.start(8089);
127
128
// Expose mock server port
129
Testcontainers.exposeHostPorts(8089);
130
131
try (GenericContainer<?> client = new GenericContainer<>("api-client:latest")
132
.withEnv("API_BASE_URL", "http://host.testcontainers.internal:8089")) {
133
134
client.start();
135
136
// Container makes requests to mock server on host
137
// ... verify interactions
138
} finally {
139
mockServer.shutdown();
140
}
141
}
142
```
143
144
**Development Environment Integration:**
145
146
```java
147
@Test
148
void testWithDevelopmentServices() {
149
// Expose common development ports
150
Testcontainers.exposeHostPorts(
151
3000, // React dev server
152
8080, // Spring Boot
153
5432, // PostgreSQL
154
6379 // Redis
155
);
156
157
try (GenericContainer<?> integration = new GenericContainer<>("integration-test:latest")
158
.withEnv("FRONTEND_URL", "http://host.testcontainers.internal:3000")
159
.withEnv("API_URL", "http://host.testcontainers.internal:8080")
160
.withEnv("DB_HOST", "host.testcontainers.internal")
161
.withEnv("REDIS_HOST", "host.testcontainers.internal")) {
162
163
integration.start();
164
165
// Integration test container can access all development services
166
// ... run comprehensive integration tests
167
}
168
}
169
```
170
171
## Important Notes
172
173
**Host Access Hostname:**
174
- Containers access host services via `host.testcontainers.internal`
175
- This hostname is automatically configured when `exposeHostPorts()` is called
176
- Works across different Docker environments (Docker Desktop, Linux, etc.)
177
178
**Port Binding:**
179
- Host ports must be actually bound/listening before calling `exposeHostPorts()`
180
- Ports are exposed globally for all containers created after the call
181
- Multiple calls to `exposeHostPorts()` are cumulative
182
183
**Security Considerations:**
184
- Only expose necessary ports to minimize attack surface
185
- Be cautious when exposing host services in CI/CD environments
186
- Consider using container-to-container networking when possible
187
188
## Types
189
190
```java { .api }
191
/**
192
* Exception thrown when host port exposure fails
193
*/
194
public class HostPortExposureException extends RuntimeException {
195
public HostPortExposureException(String message);
196
public HostPortExposureException(String message, Throwable cause);
197
}
198
```