Skip to content

Commit

Permalink
docs: use Go testable examples in modules (#1603)
Browse files Browse the repository at this point in the history 
* fix: rename vault container in tests

* chore: adjust comment in template

* docs(vault): use RunContainer example in usage section

* docs: update vault docs

* docs: add RunContainer example for redpanda

* docs: add RunContainer example for redis

* docs: document creating networks

* docs: add RunContainer example for pulsar

* docs: add RunContainer example for postgres

* docs: add RunContainer example for neo4j

* docs: add RunContainer example for nats

* docs: update quickstart to not use testing libraries

* docs: add RunContainer example for mysql

* docs: add RunContainer example for mongo

* docs: add RunContainer example for mariadb

* chore: use logger to print out hostname external reason

* docs: document new Go examples file

* docs: add RunContainer example for localstack

* chore: convert k3s test into a testable example

* chore: convert mongodb test into testable example

* fix: handle errors in example tests for elasticsearch

* fix: do not deprecate used fields

They are not directly called, but the customisers are populating their values

* chore: convert couchbase test into testable example

* chore: convert clickhouse test into testable example

* docs: adjust artemis docs

* chore: simplify postgres example

* fix: lint

* chore(deps): bump github.com/hashicorp/vault-client-go in /modules/vault (#1566)

* chore(deps): bump github.com/hashicorp/vault-client-go in /modules/vault

Bumps [github.com/hashicorp/vault-client-go](https://github.com/hashicorp/vault-client-go) from 0.2.0 to 0.3.3.
- [Release notes](https://github.com/hashicorp/vault-client-go/releases)
- [Changelog](https://github.com/hashicorp/vault-client-go/blob/main/CHANGELOG.md)
- [Commits](hashicorp/vault-client-go@v0.2.0...v0.3.3)

---
updated-dependencies:
- dependency-name: github.com/hashicorp/vault-client-go
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

* up

* Update vault_test.go

* Update vault_test.go

* Update vault_test.go

* Update vault_test.go

* Update vault_test.go

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Manuel de la Peña <mdelapenya@gmail.com>

* ci(lint): enable gocritic linter (#1605)

Signed-off-by: Matthieu MOREL <matthieu.morel35@gmail.com>

* ci(lint): enable errorlint linter (#1604)

* ci(lint): enable errorlint linter

Signed-off-by: Matthieu MOREL <matthieu.morel35@gmail.com>

* Apply suggestions from code review

Co-authored-by: Manuel de la Peña <social.mdelapenya@gmail.com>

---------

Signed-off-by: Matthieu MOREL <matthieu.morel35@gmail.com>
Co-authored-by: Manuel de la Peña <social.mdelapenya@gmail.com>

* fix: handle errors

* chore(pulsar): create/remove the network properly

* chore: better container logs on errors during startup

* Revert "chore: better container logs on errors during startup"

This reverts commit 0e28881.

* chore: better container logs on errors during startup

* fix: do not wrap error but print it

* fix: avoid polluting default wait strategies in pulsar

---------

Signed-off-by: dependabot[bot] <support@github.com>
Signed-off-by: Matthieu MOREL <matthieu.morel35@gmail.com>
Co-authored-by: Matthieu MOREL <matthieu.morel35@gmail.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
  • Loading branch information
@mdelapenya @mmorel-35 @dependabot
3 people authored Sep 11, 2023
1 parent 3ee91d5 commit 58f1778
Show file tree
Hide file tree
Showing 62 changed files with 1,236 additions and 677 deletions.
13 changes: 13 additions & 0 deletions docs/features/creating_networks.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# How to create a network

Apart from creating containers, `Testcontainers for Go` also allows you to create networks. This is useful when you need to connect multiple containers to the same network.

## Usage example

<!--codeinclude-->
[Creating a network](../../network_test.go) inside_block:createNetwork
<!--/codeinclude-->

<!--codeinclude-->
[Creating a network with IPAM](../../network_test.go) inside_block:withIPAM
<!--/codeinclude-->
16 changes: 11 additions & 5 deletions docs/modules/artemis.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,11 @@ go get github.com/testcontainers/testcontainers-go/modules/artemis
## Usage example

<!--codeinclude-->
[Creating and connecting to an Artemis container](../../modules/artemis/example_test.go) inside_block:ExampleRunContainer
[Creating to an Artemis container](../../modules/artemis/examples_test.go) inside_block:runArtemisContainer
<!--/codeinclude-->

<!--codeinclude-->
[Connecting to an Artemis container](../../modules/artemis/examples_test.go) inside_block:connectToArtemisContainer
<!--/codeinclude-->

## Module reference
Expand Down Expand Up @@ -58,7 +62,7 @@ If you need to change the default admin credentials (i.e. `artemis:artemis`) use
[With credentials](../../modules/artemis/artemis_test.go) inside_block:withCredentials
<!--/codeinclude-->

#### Anonymous Login
#### Enable Anonymous login

If you need to enable anonymous logins (which are disabled by default) use `WithAnonymousLogin`.

Expand All @@ -71,7 +75,9 @@ If you need to enable anonymous logins (which are disabled by default) use `With
If you need to pass custom arguments to the `artemis create` command, use `WithExtraArgs`.
The default is `--http-host 0.0.0.0 --relax-jolokia`.
Setting this value will override the default.
See the documentation on `artemis create` for available options.

!!!info
Please see the documentation on `artemis create` for the available options here: [https://activemq.apache.org/components/artemis/documentation/latest/using-server.html#options](https://activemq.apache.org/components/artemis/documentation/latest/using-server.html#options)

<!--codeinclude-->
[With Extra Arguments](../../modules/artemis/artemis_test.go) inside_block:withExtraArgs
Expand All @@ -96,15 +102,15 @@ The Artemis container exposes the following methods:
User returns the administrator username.

<!--codeinclude-->
[Retrieving the Administrator User](../../modules/artemis/example_test.go) inside_block:containerUser
[Retrieving the Administrator User](../../modules/artemis/examples_test.go) inside_block:containerUser
<!--/codeinclude-->

#### Password

Password returns the administrator password.

<!--codeinclude-->
[Retrieving the Administrator Password](../../modules/artemis/example_test.go) inside_block:containerPassword
[Retrieving the Administrator Password](../../modules/artemis/examples_test.go) inside_block:containerPassword
<!--/codeinclude-->

#### BrokerEndpoint
Expand Down
56 changes: 30 additions & 26 deletions docs/modules/clickhouse.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,7 @@ go get github.com/testcontainers/testcontainers-go/modules/clickhouse
## Usage example

<!--codeinclude-->

[Test for a ClickHouse container](../../modules/clickhouse/clickhouse_test.go)inside_block:customInitialization

[Test for a ClickHouse container](../../modules/clickhouse/examples_test.go) inside_block:runClickHouseContainer
<!--/codeinclude-->

## Module reference
Expand All @@ -33,6 +31,14 @@ func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomize
- `context.Context`, the Go context.
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.

### Container Ports

Here you can find the list with the default ports used by the ClickHouse container.

<!--codeinclude-->
[Container Ports](../../modules/clickhouse/clickhouse.go) inside_block:containerPorts
<!--/codeinclude-->

### Container Options

When starting the ClickHouse container, you can pass options in a variadic way to configure it.
Expand Down Expand Up @@ -65,13 +71,7 @@ Please read the [Create containers: Advanced Settings](../features/creating_cont
#### Set username, password and database name

If you need to set a different database, and its credentials, you can use `WithUsername`, `WithPassword`, `WithDatabase`
options.

<!--codeinclude-->

[Custom Database initialization](../../modules/clickhouse/clickhouse_test.go) inside_block:customInitialization

<!--/codeinclude-->
options. E.g. `WithUsername("user")`, `WithPassword("password")`, `WithDatabase("db")`.

!!!info
The default values for the username is `default`, for password is `clickhouse` and for the default database name is `clickhouse`.
Expand All @@ -84,42 +84,46 @@ it will run any `*.sql` files, run any executable `*.sh` scripts, and source any
initialization before starting the service.

<!--codeinclude-->

[Include init scripts](../../modules/clickhouse/clickhouse_test.go) inside_block:withInitScripts
<!--/codeinclude-->

<!--codeinclude-->
[Init script content](../../modules/clickhouse/testdata/init-db.sh)
<!--/codeinclude-->

#### Custom configuration

If you need to set a custom configuration, the module provides the `WithConfigFile` option to pass the path to a custom configuration file in XML format.

<!--codeinclude-->
[XML config file](../../modules/clickhouse/testdata/config.xml)
<!--/codeinclude-->

[Init script content](../../modules/clickhouse/testdata/init-db.sh)
In the case you want to pass a YAML configuration file, you can use the `WithYamlConfigFile` option.

<!--codeinclude-->
[YAML config file](../../modules/clickhouse/testdata/config.yaml)
<!--/codeinclude-->

### Container Methods

The ClickHouse container exposes the following methods:

#### ConnectionString

This method returns the dsn connection string to connect to the ClickHouse container, using the default configs.
It's possible to pass extra parameters to the connection string, e.g. `dial_timeout=300ms` or `skip_verify=false`, in a variadic way.
#### ConnectionHost

e.g. `clickhouse://default:pass@localhost:9000?dial_timeout=300ms&skip_verify=false`
This method returns the host and port of the ClickHouse container, using the default, native `9000/tcp` port. E.g. `localhost:9000`

<!--codeinclude-->

[Get connection string](../../modules/clickhouse/clickhouse_test.go) inside_block:connectionString

[Get connection host](../../modules/clickhouse/clickhouse_test.go) inside_block:connectionHost
<!--/codeinclude-->

#### ConnectionHost
#### ConnectionString

This method returns the host & port of the ClickHouse container.
This method returns the dsn connection string to connect to the ClickHouse container, using the default, native `9000/tcp` port obtained from the `ConnectionHost` method.
It's possible to pass extra parameters to the connection string, e.g. `dial_timeout=300ms` or `skip_verify=false`, in a variadic way.

e.g. `localhost:9000`
e.g. `clickhouse://default:pass@localhost:9000?dial_timeout=300ms&skip_verify=false`

<!--codeinclude-->

[Get connection host](../../modules/clickhouse/clickhouse_test.go) inside_block:connectionHost

[Get connection string](../../modules/clickhouse/clickhouse_test.go) inside_block:connectionString
<!--/codeinclude-->
35 changes: 15 additions & 20 deletions docs/modules/couchbase.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ go get github.com/testcontainers/testcontainers-go/modules/couchbase
## Usage example

<!--codeinclude-->
[Start Couchbase](../../modules/couchbase/couchbase_test.go) inside_block:withBucket
[Creating a Couchbase container](../../modules/couchbase/examples_test.go) inside_block:runCouchbaseContainer
<!--/codeinclude-->

## Module Reference
Expand Down Expand Up @@ -49,6 +49,11 @@ Once the container is started, it will perform the following operations, **in th

### Container Ports

Here you can find the list with the default ports used by the Couchbase container. The Management ports (`MGMT_PORT` and `MGMT_SSL_PORT`) and the Service ports for `kv`, `query` and `search` are exposed by default.

!!!tip
You can export the service ports for Analytics and Eventing by using the `WithServiceAnalytics` and `WithServiceEventing` optional functions.

<!--codeinclude-->
[Container Ports](../../modules/couchbase/couchbase.go) inside_block:containerPorts
<!--/codeinclude-->
Expand All @@ -68,6 +73,12 @@ By default, the container will use the following Docker image:
[Default Docker image](../../modules/couchbase/couchbase.go) inside_block:defaultImage
<!--/codeinclude-->

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

<!--codeinclude-->
[Docker images](../../modules/couchbase/couchbase_test.go) inside_block:dockerImages
<!--/codeinclude-->

#### Wait Strategies

If you need to set a different wait strategy for Couchbase, you can use `testcontainers.WithWaitStrategy` with a valid wait strategy
Expand All @@ -94,12 +105,12 @@ If you need to change the default credentials for the admin user, you can use `W
When the password has less than 6 characters, the container won't be created and the `RunContainer` function will throw an error.

!!!info
The default username is `Administrator` and the default password is `password`.
In the case this optional function is not called, the default username is `Administrator` and the default password is `password`.

#### Buckets

When creating a new Couchbase container, you can create one or more buckets. The module provides with a `WithBuckets` function that accepts an array of buckets to be created.
To create a new bucket, the module exposes a `NewBucket` function, where you can pass the bucket name.
When creating a new Couchbase container, you can create one or more buckets. The module exposes a `WithBuckets` optional function that accepts an slice of buckets to be created.
To create a new bucket, the module also exposes a `NewBucket` function, where you can pass the bucket name.

It's possible to customize a newly created bucket, using the following options:

Expand Down Expand Up @@ -131,33 +142,17 @@ By default, the container will start with the following services: `kv`, `n1ql`,
When running the Enterprise Edition of Couchbase Server, the module provides two functions to enable or disable services:
`WithServiceAnalytics` and `WithServiceEventing`. Else, it will throw an error and the container won't be created.

<!--codeinclude-->
[Docker images](../../modules/couchbase/couchbase_test.go) inside_block:dockerImages
<!--/codeinclude-->

### Container Methods

#### ConnectionString

The `ConnectionString` method returns the connection string to connect to the Couchbase container instance.
It returns a string with the format `couchbase://<host>:<port>`.

<!--codeinclude-->
[Connect to Couchbase](../../modules/couchbase/couchbase_test.go) inside_block:connectToCluster
<!--/codeinclude-->

#### Username

The `Username` method returns the username of the Couchbase administrator.

<!--codeinclude-->
[Connect to Couchbase using Credentials](../../modules/couchbase/couchbase_test.go) inside_block:getCredentials
<!--/codeinclude-->

#### Password

The `Password` method returns the password of the Couchbase administrator.

<!--codeinclude-->
[Connect to Couchbase using Credentials](../../modules/couchbase/couchbase_test.go) inside_block:getCredentials
<!--/codeinclude-->
4 changes: 3 additions & 1 deletion docs/modules/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,14 @@ We have provided a command line tool to generate the scaffolding for the code of
- a Go package named after the module, in lowercase
- a Go file for the creation of the container, using a dedicated struct in which the image flag is set as Docker image.
- a Go test file for running a simple test for your container, consuming the above struct.
- a Go examples file for running the example in the docs site, also adding them to [https://pkg.go.dev](https://pkg.go.dev).
- a Makefile to run the tests in a consistent manner
- a markdown file in the docs/modules directory including the snippets for both the creation of the container and a simple test. By default, this generated file will contain all the documentation for the module, including:
- the version of _Testcontainers for Go_ in which the module was added.
- a short introduction to the module.
- a section for adding the module to the project dependencies.
- a section for a usage example.
- a section for a usage example, including:
- a snippet for creating the container, from the `examples_test.go` file in the Go module.
- a section for the module reference, including:
- the entrypoint function for creating the container.
- the options for creating the container.
Expand Down
2 changes: 1 addition & 1 deletion docs/modules/k3s.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ go get github.com/testcontainers/testcontainers-go/modules/k3s
## Usage example

<!--codeinclude-->
[Test for a K3s container](../../modules/k3s/k3s_test.go) inside_block: k3sRunContainer
[Test for a K3s container](../../modules/k3s/k3s_test.go) inside_block:runK3sContainer
<!--/codeinclude-->

## Module reference
Expand Down
Loading

0 comments on commit 58f1778

Please sign in to comment.