Skip to content

Commit 593e3cd

Browse files
committed
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)
2 parents cae44db + 2740634 commit 593e3cd

File tree

18 files changed

+581
-46
lines changed

18 files changed

+581
-46
lines changed

docs/features/common_functional_options.md

Lines changed: 72 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,12 @@ func (g *TestLogConsumer) Accept(l Log) {
188188
}
189189
```
190190

191+
#### WithLogConsumerConfig
192+
193+
- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="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+
191197
#### WithLogger
192198

193199
- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>
@@ -214,14 +220,36 @@ func TestHandler(t *testing.T) {
214220

215221
Please read the [Following Container Logs](/features/follow_logs) documentation for more information about creating log consumers.
216222

223+
#### WithAlwaysPull
224+
225+
- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="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 <a href="https://github.com/testcontainers/testcontainers-go"><span class="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 <a href="https://github.com/testcontainers/testcontainers-go"><span class="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+
217243
#### Wait Strategies
218244

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.
220246

221247
!!!info
222248
The default deadline for the wait strategy is 60 seconds.
223249

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`.
225253

226254
#### Startup Commands
227255

@@ -282,6 +310,24 @@ In the case you need to retrieve the network name, you can simply read it from t
282310
!!!warning
283311
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.
284312

313+
#### WithNetworkByName
314+
315+
- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="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 <a href="https://github.com/testcontainers/testcontainers-go"><span class="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+
285331
#### WithNewNetwork
286332

287333
- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><span class="tc-version">:material-tag: v0.27.0</span></a>
@@ -335,3 +381,27 @@ ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3",
335381

336382
!!!warning
337383
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 <a href="https://github.com/testcontainers/testcontainers-go"><span class="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.
390+
391+
```golang
392+
ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3",
393+
testcontainers.WithName("my-container-name"),
394+
)
395+
```
396+
397+
!!!warning
398+
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 <a href="https://github.com/testcontainers/testcontainers-go"><span class="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.
406+
407+

docs/modules/index.md

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -204,9 +204,16 @@ In order to simplify the creation of the container for a given module, `Testcont
204204
- `testcontainers.WithTmpfs`: a function that adds tmpfs mounts to the container.
205205
- `testcontainers.WithHostPortAccess`: a function that enables the container to access a port that is already running in the host.
206206
- `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.
207208
- `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.
210217
- `testcontainers.WithStartupCommand`: a function that sets the execution of a command when the container starts.
211218
- `testcontainers.WithAfterReadyCommand`: a function that sets the execution of a command right after the container is ready (its wait strategy is satisfied).
212219
- `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
217224
- `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.
218225
- `testcontainers.CustomizeRequest`: a function that merges the default options with the ones provided by the user. Recommended for completely customizing the container request.
219226
- `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.
220233

221234
### Update Go dependencies in the modules
222235

docs/modules/redpanda.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ E.g. `WithSuperusers("superuser-1", "superuser-2")`.
9999
100100
- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>
101101
102-
The `WithEnableSASL()` option enables SASL scram sha authentication. By default, no authentication (plaintext) is used.
102+
The `WithEnableSASL()` option enables SASL scram sha 256 authentication. By default, no authentication (plaintext) is used.
103103
When setting an authentication method, make sure to add users as well and authorize them using the `WithSuperusers()` option.
104104
105105
#### WithEnableKafkaAuthorization

modules/etcd/etcd.go

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,9 @@ func (c *EtcdContainer) Terminate(ctx context.Context, opts ...testcontainers.Te
6060
// Run creates an instance of the etcd container type
6161
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*EtcdContainer, error) {
6262
req := testcontainers.ContainerRequest{
63-
Image: img,
64-
Cmd: []string{},
63+
Image: img,
64+
ExposedPorts: []string{clientPort, peerPort},
65+
Cmd: []string{},
6566
}
6667

6768
genericContainerReq := testcontainers.GenericContainerRequest{

modules/k3s/k3s_test.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -146,7 +146,7 @@ func Test_WithManifestOption(t *testing.T) {
146146
k3sContainer, err := k3s.Run(ctx,
147147
"rancher/k3s:v1.27.1-k3s1",
148148
k3s.WithManifest("nginx-manifest.yaml"),
149-
testcontainers.WithWaitStrategy(wait.ForExec([]string{"kubectl", "wait", "pod", "nginx", "--for=condition=Ready"})),
149+
testcontainers.WithAdditionalWaitStrategy(wait.ForExec([]string{"kubectl", "wait", "pod", "nginx", "--for=condition=Ready"})),
150150
)
151151
testcontainers.CleanupContainer(t, k3sContainer)
152152
require.NoError(t, err)

modules/localstack/examples_test.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ func ExampleRun_legacyMode() {
101101
ctx,
102102
"localstack/localstack:0.10.0",
103103
testcontainers.WithEnv(map[string]string{"SERVICES": "s3,sqs"}),
104-
testcontainers.WithWaitStrategy(wait.ForLog("Ready.").WithStartupTimeout(5*time.Minute).WithOccurrence(1)),
104+
testcontainers.WithAdditionalWaitStrategy(wait.ForLog("Ready.").WithStartupTimeout(5*time.Minute).WithOccurrence(1)),
105105
)
106106
defer func() {
107107
if err := testcontainers.TerminateContainer(ctr); err != nil {

modules/mongodb/examples_test.go

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@ import (
1111

1212
"github.com/testcontainers/testcontainers-go"
1313
"github.com/testcontainers/testcontainers-go/modules/mongodb"
14-
"github.com/testcontainers/testcontainers-go/wait"
1514
)
1615

1716
func ExampleRun() {
@@ -89,7 +88,6 @@ func ExampleRun_withCredentials() {
8988
"mongo:6",
9089
mongodb.WithUsername("root"),
9190
mongodb.WithPassword("password"),
92-
testcontainers.WithWaitStrategy(wait.ForLog("Waiting for connections")),
9391
)
9492
defer func() {
9593
if err := testcontainers.TerminateContainer(ctr); err != nil {

modules/mssql/mssql_test.go

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ func TestMSSQLServerWithMissingEulaOption(t *testing.T) {
5050
t.Run("empty", func(t *testing.T) {
5151
ctr, err := mssql.Run(ctx,
5252
"mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04",
53-
testcontainers.WithWaitStrategy(
53+
testcontainers.WithAdditionalWaitStrategy(
5454
wait.ForLog("The SQL Server End-User License Agreement (EULA) must be accepted")),
5555
)
5656
testcontainers.CleanupContainer(t, ctr)
@@ -61,7 +61,7 @@ func TestMSSQLServerWithMissingEulaOption(t *testing.T) {
6161
ctr, err := mssql.Run(ctx,
6262
"mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04",
6363
testcontainers.WithEnv(map[string]string{"ACCEPT_EULA": "yes"}),
64-
testcontainers.WithWaitStrategy(
64+
testcontainers.WithAdditionalWaitStrategy(
6565
wait.ForLog("The SQL Server End-User License Agreement (EULA) must be accepted")),
6666
)
6767
testcontainers.CleanupContainer(t, ctr)

modules/postgres/examples_test.go

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,9 @@ import (
55
"fmt"
66
"log"
77
"path/filepath"
8-
"time"
98

109
"github.com/testcontainers/testcontainers-go"
1110
"github.com/testcontainers/testcontainers-go/modules/postgres"
12-
"github.com/testcontainers/testcontainers-go/wait"
1311
)
1412

1513
func ExampleRun() {
@@ -27,10 +25,7 @@ func ExampleRun() {
2725
postgres.WithDatabase(dbName),
2826
postgres.WithUsername(dbUser),
2927
postgres.WithPassword(dbPassword),
30-
testcontainers.WithWaitStrategy(
31-
wait.ForLog("database system is ready to accept connections").
32-
WithOccurrence(2).
33-
WithStartupTimeout(5*time.Second)),
28+
postgres.BasicWaitStrategies(),
3429
)
3530
defer func() {
3631
if err := testcontainers.TerminateContainer(postgresContainer); err != nil {

modules/postgres/postgres_test.go

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,7 @@ func TestContainerWithWaitForSQL(t *testing.T) {
155155
postgres.WithDatabase(dbname),
156156
postgres.WithUsername(user),
157157
postgres.WithPassword(password),
158-
testcontainers.WithWaitStrategy(wait.ForSQL(nat.Port(port), "postgres", dbURL)),
158+
testcontainers.WithAdditionalWaitStrategy(wait.ForSQL(nat.Port(port), "postgres", dbURL)),
159159
)
160160
testcontainers.CleanupContainer(t, ctr)
161161
require.NoError(t, err)
@@ -168,7 +168,7 @@ func TestContainerWithWaitForSQL(t *testing.T) {
168168
postgres.WithDatabase(dbname),
169169
postgres.WithUsername(user),
170170
postgres.WithPassword(password),
171-
testcontainers.WithWaitStrategy(wait.ForSQL(nat.Port(port), "postgres", dbURL).WithStartupTimeout(time.Second*5).WithQuery("SELECT 10")),
171+
testcontainers.WithAdditionalWaitStrategy(wait.ForSQL(nat.Port(port), "postgres", dbURL).WithStartupTimeout(time.Second*5).WithQuery("SELECT 10")),
172172
)
173173
testcontainers.CleanupContainer(t, ctr)
174174
require.NoError(t, err)
@@ -181,7 +181,7 @@ func TestContainerWithWaitForSQL(t *testing.T) {
181181
postgres.WithDatabase(dbname),
182182
postgres.WithUsername(user),
183183
postgres.WithPassword(password),
184-
testcontainers.WithWaitStrategy(wait.ForSQL(nat.Port(port), "postgres", dbURL).WithStartupTimeout(time.Second*5).WithQuery("SELECT 'a' from b")),
184+
testcontainers.WithAdditionalWaitStrategy(wait.ForSQL(nat.Port(port), "postgres", dbURL).WithStartupTimeout(time.Second*5).WithQuery("SELECT 'a' from b")),
185185
)
186186
testcontainers.CleanupContainer(t, ctr)
187187
require.Error(t, err)
@@ -225,7 +225,7 @@ func TestWithSSL(t *testing.T) {
225225
postgres.WithDatabase(dbname),
226226
postgres.WithUsername(user),
227227
postgres.WithPassword(password),
228-
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)),
229229
postgres.WithSSLCert(caCert.CertPath, serverCerts.CertPath, serverCerts.KeyPath),
230230
)
231231

@@ -255,7 +255,7 @@ func TestSSLValidatesKeyMaterialPath(t *testing.T) {
255255
postgres.WithDatabase(dbname),
256256
postgres.WithUsername(user),
257257
postgres.WithPassword(password),
258-
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)),
259259
postgres.WithSSLCert("", "", ""),
260260
)
261261

0 commit comments

Comments
 (0)