Merge branch 'main' into session-ids

* main: chore: define interfaces for file and project generation (testcontainers#1568) chore(deps): bump mkdocs-material from 8.2.7 to 9.2.6 (testcontainers#1567) chore(deps): bump the all group in /modules/neo4j with 1 update (testcontainers#1562) chore(deps): bump the all group in /modules/clickhouse with 1 update (testcontainers#1563) chore(deps): bump the all group in /modules/localstack with 1 update (testcontainers#1564) Update actions/github-script to 6.4.1 (testcontainers#1561) chore: Update Pipenv to use Python 3.8 (testcontainers#1558) feat: convert NATS example into a module (testcontainers#1559) chore(deps): bump the all group in /modulegen with 1 update (testcontainers#1554) modulegen: use cobra instead of native golang flag (testcontainers#1550)
mdelapenya · Sep 1, 2023 · 3f43bae · 3f43bae
2 parents b0d7e0d + 69a5d38
commit 3f43bae
Show file tree

Hide file tree

Showing 52 changed files with 1,391 additions and 692 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -82,17 +82,6 @@ updates:
  all:
  patterns:
  - '*'
- - package-ecosystem: gomod
- directory: /examples/nats
- schedule:
- interval: monthly
- day: sunday
- open-pull-requests-limit: 3
- rebase-strategy: disabled
- groups:
- all:
- patterns:
- - '*'
  - package-ecosystem: gomod
  directory: /examples/nginx
  schedule:
@@ -247,6 +236,17 @@ updates:
  all:
  patterns:
  - '*'
+ - package-ecosystem: gomod
+ directory: /modules/nats
+ schedule:
+ interval: monthly
+ day: sunday
+ open-pull-requests-limit: 3
+ rebase-strategy: disabled
+ groups:
+ all:
+ patterns:
+ - '*'
  - package-ecosystem: gomod
  directory: /modules/neo4j
  schedule:

diff --git a/.github/workflows/ci-windows.yml b/.github/workflows/ci-windows.yml
@@ -13,11 +13,11 @@ jobs:
  timeout-minutes: 30
  steps:
  - name: Create pending status
- uses: actions/github-script@0.9.0
+ uses: actions/github-script@6.4.1
  with:
  github-token: ${{ secrets.GITHUB_TOKEN }}
  script: |
- github.repos.createStatus({
+ github.rest.repos.createCommitStatus({
  owner: context.repo.owner,
  repo: context.repo.repo,
  sha: context.payload.client_payload.pull_request.head.sha,
@@ -55,12 +55,12 @@ jobs:
  gotestsum --format short-verbose --rerun-fails=5 --packages="./..." --junitfile TEST-unit.xml -- -timeout=30m
 
  - name: Create success status
- uses: actions/github-script@0.9.0
+ uses: actions/github-script@6.4.1
  if: success()
  with:
  github-token: ${{secrets.GITHUB_TOKEN}}
  script: |
- github.repos.createStatus({
+ github.rest.repos.createCommitStatus({
  owner: context.repo.owner,
  repo: context.repo.repo,
  sha: context.payload.client_payload.pull_request.head.sha,
@@ -70,12 +70,12 @@ jobs:
  })
 
  - name: Create failure status
- uses: actions/github-script@0.9.0
+ uses: actions/github-script@6.4.1
  if: failure()
  with:
  github-token: ${{secrets.GITHUB_TOKEN}}
  script: |
- github.repos.createStatus({
+ github.rest.repos.createCommitStatus({
  owner: context.repo.owner,
  repo: context.repo.repo,
  sha: context.payload.client_payload.pull_request.head.sha,

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -96,7 +96,7 @@ jobs:
  matrix:
  go-version: [1.20.x, 1.x]
  platform: [ubuntu-latest, macos-latest]
- module: [artemis, clickhouse, compose, couchbase, k3s, localstack, mariadb, mongodb, mysql, neo4j, postgres, pulsar, redis, redpanda, vault]
+ module: [artemis, clickhouse, compose, couchbase, k3s, localstack, mariadb, mongodb, mysql, nats, neo4j, postgres, pulsar, redis, redpanda, vault]
  uses: ./.github/workflows/ci-test-go.yml
  with:
  go-version: ${{ matrix.go-version }}
@@ -111,7 +111,7 @@ jobs:
  needs: test-modules
  strategy:
  matrix:
- module: [bigtable, cockroachdb, consul, datastore, firestore, nats, nginx, pubsub, spanner, toxiproxy]
+ module: [bigtable, cockroachdb, consul, datastore, firestore, nginx, pubsub, spanner, toxiproxy]
  uses: ./.github/workflows/ci-test-go.yml
  with:
  go-version: "1.20.x"

diff --git a/.vscode/.testcontainers-go.code-workspace b/.vscode/.testcontainers-go.code-workspace
@@ -25,10 +25,6 @@
  "name": "example / firestore",
  "path": "../examples/firestore"
  },
- {
- "name": "example / nats",
- "path": "../examples/nats"
- },
  {
  "name": "example / nginx",
  "path": "../examples/nginx"
@@ -81,6 +77,10 @@
  "name": "module / mysql",
  "path": "../modules/mysql"
  },
+ {
+ "name": "module / nats",
+ "path": "../modules/nats"
+ },
  {
  "name": "module / neo4j",
  "path": "../modules/neo4j"

diff --git a/Pipfile b/Pipfile
@@ -6,10 +6,10 @@ verify_ssl = true
 [dev-packages]
 
 [packages]
-mkdocs = "*"
-mkdocs-codeinclude-plugin = "*"
-mkdocs-material = "*"
-mkdocs-markdownextradata-plugin = "*"
+mkdocs = "==1.5.2"
+mkdocs-codeinclude-plugin = "==0.2.1"
+mkdocs-material = "==9.2.6"
+mkdocs-markdownextradata-plugin = "==0.2.5"
 
 [requires]
-python_version = "3.7"
+python_version = "3.8"
diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/docs/examples/nats.md b/docs/examples/nats.md
diff --git a/docs/modules/index.md b/docs/modules/index.md
@@ -28,12 +28,12 @@ We have provided a command line tool to generate the scaffolding for the code of
 
 ### Command line flags
 
-| Flag  | Type | Required | Description  |
-|------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| -name   | string | Yes | Name of the module, use camel-case when needed. Only alphanumerical characters are allowed (leading character must be a letter).  |
-| -image   | string | Yes | Fully-qualified name of the Docker image to be used by the module (i.e. 'docker.io/org/project:tag')  |
-| -title   | string | No | A variant of the name supporting mixed casing (i.e. 'MongoDB'). Only alphanumerical characters are allowed (leading character must be a letter).  |
-| -as-module | bool | No | If set, the module will be generated as a Go module, under the modules directory. Otherwise, it will be generated as a subdirectory of the examples directory. |
+| Flag | Short | Type | Required | Description |
+|---------|-------|--------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| --name | -n  | string | Yes | Name of the module, use camel-case when needed. Only alphanumerical characters are allowed (leading character must be a letter). |
+| --image | -i  | string | Yes | Fully-qualified name of the Docker image to be used by the module (i.e. 'docker.io/org/project:tag') |
+| --title | -t  | string | No | A variant of the name supporting mixed casing (i.e. 'MongoDB'). Only alphanumerical characters are allowed (leading character must be a letter). |
+
 
 ### What is this tool not doing?
 
@@ -45,13 +45,13 @@ We have provided a command line tool to generate the scaffolding for the code of
 From the [`modulegen` directory]({{repo_url}}/tree/main/modulegen), please run:
 
 ```shell
-go run . --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}
+go run . new example --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}
 ```
 
 or for creating a Go module:
 
 ```shell
-go run . --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE} --as-module
+go run . new module --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}
 ```
 
 ### Adding types and methods to the module

diff --git a/docs/modules/nats.md b/docs/modules/nats.md
@@ -0,0 +1,89 @@
+# NATS
+
+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>
+
+## Introduction
+
+The Testcontainers module for NATS.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the NATS module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/nats
+```
+
+## Usage example
+
+<!--codeinclude-->
+[Creating a NATS container](../../modules/nats/nats_test.go) inside_block:createNATSContainer
+<!--/codeinclude-->
+
+## Module reference
+
+The NATS module exposes one entrypoint function to create the NATS container, and this function receives two parameters:
+
+```golang
+func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*NATSContainer, error)
+```
+
+- `context.Context`, the Go context.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+### Container Options
+
+When starting the NATS container, you can pass options in a variadic way to configure it.
+
+#### Image
+
+If you need to set a different NATS Docker image, you can use `testcontainers.WithImage` with a valid Docker image
+for NATS. E.g. `testcontainers.WithImage("nats:2.9")`.
+
+#### Wait Strategies
+
+If you need to set a different wait strategy for NATS, you can use `testcontainers.WithWaitStrategy` with a valid wait strategy
+for NATS.
+
+!!!info
+ The default deadline for the wait strategy is 60 seconds.
+
+At the same time, it's possible to set a wait strategy and a custom deadline with `testcontainers.WithWaitStrategyAndDeadline`.
+
+#### Docker type modifiers
+
+If you need an advanced configuration for NATS, you can leverage the following Docker type modifiers:
+
+- `testcontainers.WithConfigModifier`
+- `testcontainers.WithHostConfigModifier`
+- `testcontainers.WithEndpointSettingsModifier`
+
+Please read the [Create containers: Advanced Settings](../features/creating_container.md#advanced-settings) documentation for more information.
+
+#### Set username and password
+
+If you need to set different credentials, you can use `WithUsername` and `WithPassword`
+options. By default, the username, the password are not set.
+
+<!--codeinclude-->
+[Define NATS container with credentials](../../modules/nats/nats_test.go) inside_block:withCredentials
+<!--/codeinclude-->
+
+To establish the connection with the NATS container:
+
+<!--codeinclude-->
+[Connect using the credentials](../../modules/nats/nats_test.go) inside_block:connectWithCredentials
+<!--/codeinclude-->
+
+### Container Methods
+
+The NATS container exposes the following methods:
+
+#### ConnectionString
+
+This method returns the connection string to connect to the NATS container, using the default `4222` port.
+It's possible to pass extra parameters to the connection string, in a variadic way.
+
+<!--codeinclude-->
+[Get connection string](../../modules/nats/nats_test.go) inside_block:connectionString
+<!--/codeinclude-->
diff --git a/examples/nats/nats.go b/examples/nats/nats.go
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -69,6 +69,7 @@ nav:
  - modules/mariadb.md
  - modules/mongodb.md
  - modules/mysql.md
+ - modules/nats.md
  - modules/neo4j.md
  - modules/postgres.md
  - modules/pulsar.md
@@ -82,7 +83,6 @@ nav:
  - examples/consul.md
  - examples/datastore.md
  - examples/firestore.md
- - examples/nats.md
  - examples/nginx.md
  - examples/pubsub.md
  - examples/spanner.md

diff --git a/modulegen/cmd/modules/example.go b/modulegen/cmd/modules/example.go
@@ -0,0 +1,25 @@
+package modules
+
+import (
+ "github.com/spf13/cobra"
+
+ "github.com/testcontainers/testcontainers-go/modulegen/internal"
+)
+
+var newExampleCmd = &cobra.Command{
+ Use: "example",
+ Short: "Create a new Example",
+ Long: "Create a new Example",
+ RunE: func(cmd *cobra.Command, args []string) error {
+ return internal.Generate(tcModuleVar, false)
+ },
+}
+
+func init() {
+ newExampleCmd.Flags().StringVarP(&tcModuleVar.Name, nameFlag, "n", "", "Name of the example. Only alphabetical characters are allowed.")
+ newExampleCmd.Flags().StringVarP(&tcModuleVar.NameTitle, titleFlag, "t", "", "(Optional) Title of the example name, used to override the name in the case of mixed casing (Mongodb -> MongoDB). Use camel-case when needed. Only alphabetical characters are allowed.")
+ newExampleCmd.Flags().StringVarP(&tcModuleVar.Image, imageFlag, "i", "", "Fully-qualified name of the Docker image to be used by the example")
+
+ _ = newExampleCmd.MarkFlagRequired(imageFlag)
+ _ = newExampleCmd.MarkFlagRequired(nameFlag)
+}
diff --git a/modulegen/cmd/modules/flags.go b/modulegen/cmd/modules/flags.go
@@ -0,0 +1,7 @@
+package modules
+
+const (
+ imageFlag = "image"
+ nameFlag = "name"
+ titleFlag = "title"
+)