You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Merge branch 'main' into feature/reusable-couchbase-containers
* main:
feat: support adding wait strategies as functional option (testcontainers#3161)
fix(etcd): expose ports for the etcd nodes (testcontainers#3162)
fix(wait): no port to wait for (testcontainers#3158)
feat: add more functional options for customising containers (testcontainers#3156)
docs(redpanda): update sasl authentication option to use scram sha 256 (testcontainers#3126)
- Not available until the next release of testcontainers-go <ahref="https://github.com/testcontainers/testcontainers-go"><spanclass="tc-version">:material-tag: main</span></a>
194
+
195
+
If you need to set the log consumer config for the container, you can use `testcontainers.WithLogConsumerConfig`. This option completely replaces the existing log consumer config, including the log consumers and the log production options.
196
+
191
197
#### WithLogger
192
198
193
199
- Since testcontainers-go <ahref="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><spanclass="tc-version">:material-tag: v0.29.0</span></a>
Please read the [Following Container Logs](/features/follow_logs) documentation for more information about creating log consumers.
216
222
223
+
#### WithAlwaysPull
224
+
225
+
- Not available until the next release of testcontainers-go <ahref="https://github.com/testcontainers/testcontainers-go"><spanclass="tc-version">:material-tag: main</span></a>
226
+
227
+
If you need to pull the image before starting the container, you can use `testcontainers.WithAlwaysPull()`.
228
+
229
+
#### WithImagePlatform
230
+
231
+
- Not available until the next release of testcontainers-go <ahref="https://github.com/testcontainers/testcontainers-go"><spanclass="tc-version">:material-tag: main</span></a>
232
+
233
+
If you need to set the platform for a container, you can use `testcontainers.WithImagePlatform(platform string)`.
234
+
235
+
#### LifecycleHooks
236
+
237
+
- Not available until the next release of testcontainers-go <ahref="https://github.com/testcontainers/testcontainers-go"><spanclass="tc-version">:material-tag: main</span></a>
238
+
239
+
If you need to set the lifecycle hooks for the container, you can use `testcontainers.WithLifecycleHooks`, which replaces the existing lifecycle hooks with the new ones.
240
+
241
+
You can also use `testcontainers.WithAdditionalLifecycleHooks`, which appends the new lifecycle hooks to the existing ones.
242
+
217
243
#### Wait Strategies
218
244
219
-
If you need to set a different wait strategy for the container, you can use `testcontainers.WithWaitStrategy` with a valid wait strategy.
245
+
If you need to set a different wait strategy for the container, replacing the existing one, you can use `testcontainers.WithWaitStrategy` with a valid wait strategy.
220
246
221
247
!!!info
222
248
The default deadline for the wait strategy is 60 seconds.
223
249
224
-
At the same time, it's possible to set a wait strategy and a custom deadline with `testcontainers.WithWaitStrategyAndDeadline`.
250
+
At the same time, it's possible to replace the wait strategy with a new one and a custom deadline, using `testcontainers.WithWaitStrategyAndDeadline`.
251
+
252
+
Finally, you can also append a wait strategy to the existing wait strategy, using `testcontainers.WithAdditionalWaitStrategy` and `testcontainers.WithAdditionalWaitStrategyAndDeadline`.
225
253
226
254
#### Startup Commands
227
255
@@ -282,6 +310,24 @@ In the case you need to retrieve the network name, you can simply read it from t
282
310
!!!warning
283
311
This option is not checking whether the network exists or not. If you use a network that doesn't exist, the container will start in the default Docker network, as in the default behavior.
284
312
313
+
#### WithNetworkByName
314
+
315
+
- Not available until the next release of testcontainers-go <ahref="https://github.com/testcontainers/testcontainers-go"><spanclass="tc-version">:material-tag: main</span></a>
316
+
317
+
If you want to attach your containers to an already existing Docker network by its name, you can use the `network.WithNetworkName(aliases []string, networkName string)` option, which receives an alias as parameter and the network name, attaching the container to it, and setting the network alias for that network.
318
+
319
+
!!!warning
320
+
In case the network name is `bridge`, no aliases are set. This is because network-scoped alias is supported only for containers in user defined networks.
321
+
322
+
#### WithBridgeNetwork
323
+
324
+
- Not available until the next release of testcontainers-go <ahref="https://github.com/testcontainers/testcontainers-go"><spanclass="tc-version">:material-tag: main</span></a>
325
+
326
+
If you want to attach your containers to the `bridge` network, you can use the `network.WithBridgeNetwork()` option.
327
+
328
+
!!!warning
329
+
The `bridge` network is the default network for Docker. It's not a user defined network, so it doesn't support network-scoped aliases.
330
+
285
331
#### WithNewNetwork
286
332
287
333
- Since testcontainers-go <ahref="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><spanclass="tc-version">:material-tag: v0.27.0</span></a>
Reusing a container is experimental and the API is subject to change for a more robust implementation that is not based on container names.
384
+
385
+
#### WithName
386
+
387
+
- Not available until the next release of testcontainers-go <ahref="https://github.com/testcontainers/testcontainers-go"><spanclass="tc-version">:material-tag: main</span></a>
388
+
389
+
If you need to set the name of the container, you can use the `testcontainers.WithName` option.
This option is not checking whether the container name is already in use. If you use a name that is already in use, an error is returned.
399
+
At the same time, we discourage using this option as it might lead to unexpected behavior, but we understand that in some cases it might be useful.
400
+
401
+
#### WithNoStart
402
+
403
+
- Not available until the next release of testcontainers-go <ahref="https://github.com/testcontainers/testcontainers-go"><spanclass="tc-version">:material-tag: main</span></a>
404
+
405
+
If you need to prevent the container from being started after creation, you can use the `testcontainers.WithNoStart` option.
Copy file name to clipboardExpand all lines: docs/modules/index.md
+15-2Lines changed: 15 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -204,9 +204,16 @@ In order to simplify the creation of the container for a given module, `Testcont
204
204
-`testcontainers.WithTmpfs`: a function that adds tmpfs mounts to the container.
205
205
-`testcontainers.WithHostPortAccess`: a function that enables the container to access a port that is already running in the host.
206
206
-`testcontainers.WithLogConsumers`: a function that sets the log consumers for the container request.
207
+
-`testcontainers.WithLogConsumerConfig`: a function that sets the log consumer config for the container request.
207
208
-`testcontainers.WithLogger`: a function that sets the logger for the container request.
208
-
-`testcontainers.WithWaitStrategy`: a function that sets the wait strategy for the container request.
209
-
-`testcontainers.WithWaitStrategyAndDeadline`: a function that sets the wait strategy for the container request with a deadline.
209
+
-`testcontainers.WithLifecycleHooks`: a function that sets the lifecycle hooks for the container request.
210
+
-`testcontainers.WithAdditionalLifecycleHooks`: a function that appends lifecycle hooks to the existing ones for the container request.
211
+
-`testcontainers.WithAlwaysPull`: a function that pulls the image before starting the container.
212
+
-`testcontainers.WithImagePlatform`: a function that sets the image platform for the container request.
213
+
-`testcontainers.WithWaitStrategy`: a function that replaces the wait strategy for the container request.
214
+
-`testcontainers.WithAdditionalWaitStrategy`: a function that appends the wait strategy for the container request.
215
+
-`testcontainers.WithWaitStrategyAndDeadline`: a function that replaces the wait strategy for the container request with a deadline.
216
+
-`testcontainers.WithAdditionalWaitStrategyAndDeadline`: a function that appends the wait strategy for the container request with a deadline.
210
217
-`testcontainers.WithStartupCommand`: a function that sets the execution of a command when the container starts.
211
218
-`testcontainers.WithAfterReadyCommand`: a function that sets the execution of a command right after the container is ready (its wait strategy is satisfied).
212
219
-`testcontainers.WithDockerfile`: a function that sets the build from a Dockerfile for the container request.
@@ -217,6 +224,12 @@ In order to simplify the creation of the container for a given module, `Testcont
217
224
-`testcontainers.WithEndpointSettingsModifier`: a function that sets the endpoint settings Docker type for the container request. Please see [Advanced Settings](../features/creating_container.md#advanced-settings) for more information.
218
225
-`testcontainers.CustomizeRequest`: a function that merges the default options with the ones provided by the user. Recommended for completely customizing the container request.
219
226
-`testcontainers.WithReuseByName`: a function that marks a container to be reused if it exists or create a new one if it doesn't.
227
+
-`testcontainers.WithName`: a function that sets the name of the container.
228
+
-`testcontainers.WithNoStart`: a function that prevents the container from being started after creation, so it must be started manually.
229
+
-`network.WithNetwork`: a function that sets the network and the network aliases for the container request, reusing an already existing network.
230
+
-`network.WithNetworkName`: a function that sets the network aliases for an already existing network, by its name.
231
+
-`network.WithBridgeNetwork`: a function that sets the container to be attached to the `bridge` network.
232
+
-`network.WithNewNetwork`: a function that sets the network aliases for a throw-away network for the container request.
testcontainers.WithWaitStrategy(wait.ForLog("database system is ready to accept connections").WithOccurrence(2).WithStartupTimeout(5*time.Second)),
228
+
testcontainers.WithAdditionalWaitStrategy(wait.ForLog("database system is ready to accept connections").WithOccurrence(2).WithStartupTimeout(5*time.Second)),
testcontainers.WithWaitStrategy(wait.ForLog("database system is ready to accept connections").WithOccurrence(2).WithStartupTimeout(5*time.Second)),
258
+
testcontainers.WithAdditionalWaitStrategy(wait.ForLog("database system is ready to accept connections").WithOccurrence(2).WithStartupTimeout(5*time.Second)),
0 commit comments