Skip to content

Commit

Permalink
feat: prepare modules for the new API (#2610)
Browse files Browse the repository at this point in the history
* feat: define new API for modules using Run

It will force the image to be passed

* chore: update module generator

* docs: update module generation

* fixup: modulegen

* docs: update module pages

* fix: lint

* fix: more lint

* fix: update test assertions

* docs: update reference
  • Loading branch information
mdelapenya authored Jul 4, 2024
1 parent a32fe92 commit 8e4728b
Show file tree
Hide file tree
Showing 183 changed files with 1,016 additions and 799 deletions.
8 changes: 4 additions & 4 deletions docs/features/common_functional_options.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Using the `WithImageSubstitutors` options, you could define your own substitutio
If you need to either pass additional environment variables to a container or override them, you can use `testcontainers.WithEnv` for example:

```golang
postgres, err = postgresModule.RunContainer(ctx, testcontainers.WithEnv(map[string]string{"POSTGRES_INITDB_ARGS": "--no-sync"}))
postgres, err = postgresModule.Run(ctx, "postgres:15-alpine", testcontainers.WithEnv(map[string]string{"POSTGRES_INITDB_ARGS": "--no-sync"}))
```

#### WithHostPortAccess
Expand All @@ -32,7 +32,7 @@ postgres, err = postgresModule.RunContainer(ctx, testcontainers.WithEnv(map[stri
If you need to access a port that is already running in the host, you can use `testcontainers.WithHostPortAccess` for example:

```golang
postgres, err = postgresModule.RunContainer(ctx, testcontainers.WithHostPortAccess(8080))
postgres, err = postgresModule.Run(ctx, "postgres:15-alpine", testcontainers.WithHostPortAccess(8080))
```

To understand more about this feature, please read the [Exposing host ports to the container](/features/networking/#exposing-host-ports-to-the-container) documentation.
Expand Down Expand Up @@ -70,7 +70,7 @@ useful context instead of appearing out of band.
```golang
func TestHandler(t *testing.T) {
logger := TestLogger(t)
_, err := postgresModule.RunContainer(ctx, testcontainers.WithLogger(logger))
_, err := postgresModule.Run(ctx, "postgres:15-alpine", testcontainers.WithLogger(logger))
require.NoError(t, err)
// Do something with container.
}
Expand Down Expand Up @@ -150,7 +150,7 @@ Please read the [Create containers: Advanced Settings](/features/creating_contai
This option will merge the customized request into the module's own `ContainerRequest`.

```go
container, err := RunContainer(ctx,
container, err := Run(ctx, "postgres:13-alpine",
/* Other module options */
testcontainers.CustomizeRequest(testcontainers.GenericContainerRequest{
ContainerRequest: testcontainers.ContainerRequest{
Expand Down
9 changes: 5 additions & 4 deletions docs/modules/artemis.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,13 +26,14 @@ go get github.com/testcontainers/testcontainers-go/modules/artemis

## Module reference

The Artemis module exposes one entrypoint function to create the Artemis container, and this function receives two parameters:
The Artemis module exposes one entrypoint function to create the Artemis container, and this function receives three parameters:

```golang
func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*Container, error)
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
```

- `context.Context`, the Go context.
- `string`, the Docker image to use.
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.

### Container Options
Expand All @@ -41,8 +42,8 @@ When starting the Artemis container, you can pass options in a variadic way to c

#### Image

If you need to set a different Artemis Docker image, you can use `testcontainers.WithImage` with a valid Docker image
for Artemis. E.g. `testcontainers.WithImage("docker.io/apache/activemq-artemis:2.30.0")`.
If you need to set a different Artemis Docker image, you can set a valid Docker image as the second argument in the `Run` function.
E.g. `Run(context.Background(), "docker.io/apache/activemq-artemis:2.30.0")`.

{% include "../features/common_functional_options.md" %}

Expand Down
9 changes: 5 additions & 4 deletions docs/modules/azurite.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/azurite

## Module reference

The Azurite module exposes one entrypoint function to create the Azurite container, and this function receives two parameters:
The Azurite module exposes one entrypoint function to create the Azurite container, and this function receives three parameters:

```golang
func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*AzuriteContainer, error)
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*AzuriteContainer, error)
```

- `context.Context`, the Go context.
- `string`, the Docker image to use.
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.

### Default Credentials
Expand All @@ -45,8 +46,8 @@ When starting the Azurite container, you can pass options in a variadic way to c

#### Image

If you need to set a different Azurite Docker image, you can use `testcontainers.WithImage` with a valid Docker image
for Azurite. E.g. `testcontainers.WithImage("mcr.microsoft.com/azure-storage/azurite:3.28.0")`.
If you need to set a different Azurite Docker image, you can set a valid Docker image as the second argument in the `Run` function.
E.g. `Run(context.Background(), "mcr.microsoft.com/azure-storage/azurite:3.28.0")`.

{% include "../features/common_functional_options.md" %}

Expand Down
9 changes: 5 additions & 4 deletions docs/modules/cassandra.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/cassandra

## Module reference

The Cassandra module exposes one entrypoint function to create the Cassandra container, and this function receives two parameters:
The Cassandra module exposes one entrypoint function to create the Cassandra container, and this function receives three parameters:

```golang
func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*CassandraContainer, error)
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*CassandraContainer, error)
```

- `context.Context`, the Go context.
- `string`, the Docker image to use.
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.

### Container Options
Expand All @@ -37,8 +38,8 @@ When starting the Cassandra container, you can pass options in a variadic way to

#### Image

If you need to set a different Cassandra Docker image, you can use `testcontainers.WithImage` with a valid Docker image
for Cassandra. E.g. `testcontainers.WithImage("cassandra:4.1.3")`.
If you need to set a different Cassandra Docker image, you can set a valid Docker image as the second argument in the `Run` function.
E.g. `Run(context.Background(), "cassandra:4.1.3")`.

{% include "../features/common_functional_options.md" %}

Expand Down
9 changes: 5 additions & 4 deletions docs/modules/chroma.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,14 @@ go get github.com/testcontainers/testcontainers-go/modules/chroma

## Module reference

The Chroma module exposes one entrypoint function to create the Chroma container, and this function receives two parameters:
The Chroma module exposes one entrypoint function to create the Chroma container, and this function receives three parameters:

```golang
func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*ChromaContainer, error)
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*ChromaContainer, error)
```

- `context.Context`, the Go context.
- `string`, the Docker image to use.
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.

### Container Options
Expand All @@ -42,8 +43,8 @@ When starting the Chroma container, you can pass options in a variadic way to co

#### Image

If you need to set a different Chroma Docker image, you can use `testcontainers.WithImage` with a valid Docker image
for Chroma. E.g. `testcontainers.WithImage("chromadb/chroma:0.4.24")`.
If you need to set a different Chroma Docker image, you can set a valid Docker image as the second argument in the `Run` function.
E.g. `Run(context.Background(), "chromadb/chroma:0.4.24")`.

{% include "../features/common_functional_options.md" %}

Expand Down
9 changes: 5 additions & 4 deletions docs/modules/clickhouse.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/clickhouse

## Module reference

The ClickHouse module exposes one entrypoint function to create the ClickHouse container, and this function receives two parameters:
The ClickHouse module exposes one entrypoint function to create the ClickHouse container, and this function receives three parameters:

```golang
func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*ClickHouseContainer, error)
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*ClickHouseContainer, error)
```

- `context.Context`, the Go context.
- `string`, the Docker image to use.
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.

### Container Ports
Expand All @@ -45,8 +46,8 @@ When starting the ClickHouse container, you can pass options in a variadic way t

#### Image

If you need to set a different ClickHouse Docker image, you can use `testcontainers.WithImage` with a valid Docker image
for ClickHouse. E.g. `testcontainers.WithImage("clickhouse/clickhouse-server:23.3.8.21-alpine")`.
If you need to set a different ClickHouse Docker image, you can set a valid Docker image as the second argument in the `Run` function.
E.g. `Run(context.Background(), "clickhouse/clickhouse-server:23.3.8.21-alpine")`.

{% include "../features/common_functional_options.md" %}

Expand Down
9 changes: 5 additions & 4 deletions docs/modules/cockroachdb.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/cockroachdb

## Module reference

The CockroachDB module exposes one entrypoint function to create the CockroachDB container, and this function receives two parameters:
The CockroachDB module exposes one entrypoint function to create the CockroachDB container, and this function receives three parameters:

```golang
func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*CockroachDBContainer, error)
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*CockroachDBContainer, error)
```

- `context.Context`, the Go context.
- `string`, the Docker image to use.
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.

!!!warning
Expand All @@ -40,8 +41,8 @@ When starting the CockroachDB container, you can pass options in a variadic way

#### Image

If you need to set a different CockroachDB Docker image, you can use `testcontainers.WithImage` with a valid Docker image
for CockroachDB. E.g. `testcontainers.WithImage("cockroachdb/cockroach:latest-v23.1")`.
If you need to set a different CockroachDB Docker image, you can set a valid Docker image as the second argument in the `Run` function.
E.g. `Run(context.Background(), "cockroachdb/cockroach:latest-v23.1")`.

{% include "../features/common_functional_options.md" %}

Expand Down
9 changes: 5 additions & 4 deletions docs/modules/consul.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/consul

## Module reference

The Consul module exposes one entrypoint function to create the Consul container, and this function receives two parameters:
The Consul module exposes one entrypoint function to create the Consul container, and this function receives three parameters:

```golang
func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*ConsulContainer, error)
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*ConsulContainer, error)
```

- `context.Context`, the Go context.
- `string`, the Docker image to use.
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.

### Container Options
Expand All @@ -37,8 +38,8 @@ When starting the Consul container, you can pass options in a variadic way to co

#### Image

If you need to set a different Consul Docker image, you can use `testcontainers.WithImage` with a valid Docker image
for Consul. E.g. `testcontainers.WithImage("docker.io/hashicorp/consul:1.15")`.
If you need to set a different Consul Docker image, you can set a valid Docker image as the second argument in the `Run` function.
E.g. `Run(context.Background(), "docker.io/hashicorp/consul:1.15")`.

{% include "../features/common_functional_options.md" %}

Expand Down
17 changes: 6 additions & 11 deletions docs/modules/couchbase.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/couchbase

## Module Reference

The Couchbase module exposes one entrypoint function to create the Couchbase container, and this function receives two parameters:
The Couchbase module exposes one entrypoint function to create the Couchbase container, and this function receives three parameters:

```golang
func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*CouchbaseContainer, error)
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*CouchbaseContainer, error)
```

- `context.Context`, the Go context.
- `string`, the Docker image to use.
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.

Once the container is started, it will perform the following operations, **in this particular order**:
Expand Down Expand Up @@ -64,14 +65,8 @@ When starting the Couchbase container, you can pass options in a variadic way to

#### Image

If you need to set a different Couchbase Docker image, you can use `testcontainers.WithImage` with a valid Docker image
for Couchbase. E.g. `testcontainers.WithImage("docker.io/couchbase:6.5.1")`.

By default, the container will use the following Docker image:

<!--codeinclude-->
[Default Docker image](../../modules/couchbase/couchbase.go) inside_block:defaultImage
<!--/codeinclude-->
If you need to set a different Couchbase Docker image, you can set a valid Docker image as the second argument in the `Run` function.
E.g. `Run(context.Background(), "docker.io/couchbase:6.5.1")`.

You can find the Docker images that are currently tested in this module, for the Enterprise and Community editions, in the following list:

Expand All @@ -84,7 +79,7 @@ You can find the Docker images that are currently tested in this module, for the
#### Credentials

If you need to change the default credentials for the admin user, you can use `WithAdminCredentials(user, password)` with a valid username and password.
When the password has less than 6 characters, the container won't be created and the `RunContainer` function will throw an error.
When the password has less than 6 characters, the container won't be created and the `New` function will throw an error.
!!!info
In the case this optional function is not called, the default username is `Administrator` and the default password is `password`.
Expand Down
9 changes: 5 additions & 4 deletions docs/modules/dolt.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/dolt

## Module reference

The Dolt module exposes one entrypoint function to create the Dolt container, and this function receives two parameters:
The Dolt module exposes one entrypoint function to create the Dolt container, and this function receives three parameters:

```golang
func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*DoltContainer, error)
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*DoltContainer, error)
```

- `context.Context`, the Go context.
- `string`, the Docker image to use.
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.

### Container Options
Expand All @@ -37,8 +38,8 @@ When starting the Dolt container, you can pass options in a variadic way to conf

#### Image

If you need to set a different Dolt Docker image, you can use `testcontainers.WithImage` with a valid Docker image
for Dolt. E.g. `testcontainers.WithImage("dolthub/dolt-sql-server:1.32.4")`.
If you need to set a different Dolt Docker image, you can set a valid Docker image as the second argument in the `Run` function.
E.g. `Run(context.Background(), "dolthub/dolt-sql-server:1.32.4")`.

{% include "../features/common_functional_options.md" %}

Expand Down
11 changes: 6 additions & 5 deletions docs/modules/elasticsearch.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/elasticsearch

## Module reference

The Elasticsearch module exposes one entrypoint function to create the Elasticsearch container, and this function receives two parameters:
The Elasticsearch module exposes one entrypoint function to create the Elasticsearch container, and this function receives three parameters:

```golang
func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*ElasticsearchContainer, error)
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*ElasticsearchContainer, error)
```

- `context.Context`, the Go context.
- `string`, the Docker image to use.
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.

### Container Options
Expand All @@ -37,8 +38,8 @@ When starting the Elasticsearch container, you can pass options in a variadic wa

#### Image

If you need to set a different Elasticsearch Docker image, you can use `testcontainers.WithImage` with a valid Docker image
for Elasticsearch. E.g. `testcontainers.WithImage("docker.elastic.co/elasticsearch/elasticsearch:8.0.0")`.
If you need to set a different Elasticsearch Docker image, you can set a valid Docker image as the second argument in the `Run` function.
E.g. `Run(context.Background(), "docker.elastic.co/elasticsearch/elasticsearch:8.0.0")`.

{% include "../features/common_functional_options.md" %}

Expand Down Expand Up @@ -66,7 +67,7 @@ The Elasticsearch container exposes its settings in order to configure the clien
[Create an HTTP client](../../modules/elasticsearch/elasticsearch_test.go) inside_block:createHTTPClient
<!--/codeinclude-->

The `esContainer` instance is obtained from the `elasticsearch.RunContainer` function.
The `esContainer` instance is obtained from the `elasticsearch.New` function.

In the case you configured the Elasticsearch container to set up a password, you'll need to add the `Authorization` header to the request. You can use the `SetBasicAuth` method from the HTTP request to generate the header value.
Expand Down
4 changes: 2 additions & 2 deletions docs/modules/gcloud.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,8 +97,8 @@ When starting any of the GCloud containers, you can pass options in a variadic w

#### Image

If you need to set a different GCloud Docker image, you can use `testcontainers.WithImage` with a valid Docker image
for GCloud. E.g. `testcontainers.WithImage("gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators")`.
If you need to set a different GCloud Docker image, you can set a valid Docker image as the second argument in the `RunXXX` function (`RunBigQuery, RunDatastore`, ...).
E.g. `RunXXX(context.Background(), "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators")`.

{% include "../features/common_functional_options.md" %}

Expand Down
9 changes: 5 additions & 4 deletions docs/modules/inbucket.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,14 @@ go get github.com/testcontainers/testcontainers-go/modules/inbucket

## Module reference

The Inbucket module exposes one entrypoint function to create the Inbucket container, and this function receives two parameters:
The Inbucket module exposes one entrypoint function to create the Inbucket container, and this function receives three parameters:

```golang
func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*InbucketContainer, error)
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*InbucketContainer, error)
```

- `context.Context`, the Go context.
- `string`, the Docker image to use.
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.

### Container Options
Expand All @@ -37,8 +38,8 @@ When starting the Inbucket container, you can pass options in a variadic way to

#### Image

If you need to set a different Inbucket Docker image, you can use `testcontainers.WithImage` with a valid Docker image
for Inbucket. E.g. `testcontainers.WithImage("inbucket/inbucket:sha-2d409bb")`.
If you need to set a different Inbucket Docker image, you can set a valid Docker image as the second argument in the `Run` function.
E.g. `Run(context.Background(), "inbucket/inbucket:sha-2d409bb")`.

{% include "../features/common_functional_options.md" %}

Expand Down
Loading

0 comments on commit 8e4728b

Please sign in to comment.