Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: add testcontainers-oss quickstart guides #22120

Merged
merged 6 commits into from
Mar 3, 2025
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
fix: lint
  • Loading branch information
mdelapenya committed Feb 28, 2025
commit b362a21b84b74eb915b2fd82e49af93b43416800
2 changes: 1 addition & 1 deletion content/manuals/testcontainers/benefits.md
Original file line number Diff line number Diff line change
@@ -8,7 +8,7 @@
- /testcontainers/benefits/
---

### Benefits of using Testcontainers:
### Benefits of using Testcontainers

* **On-demand isolated infrastructure provisioning:**
You don't need to have a pre-provisioned integration testing infrastructure.
@@ -34,8 +34,8 @@

* **Automatic clean up:**
The Testcontainers library takes care of removing any created resources (containers, volumes, networks etc.)
automatically after the test execution is complete by using the Ryuk sidecar container.

Check failure on line 37 in content/manuals/testcontainers/benefits.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'Ryuk'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'Ryuk'?", "location": {"path": "content/manuals/testcontainers/benefits.md", "range": {"start": {"line": 37, "column": 65}}}, "severity": "ERROR"}
While starting the required containers, Testcontainers attaches a set of labels to the
created resources (containers, volumes, networks etc) and Ryuk automatically performs

Check failure on line 39 in content/manuals/testcontainers/benefits.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'Ryuk'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'Ryuk'?", "location": {"path": "content/manuals/testcontainers/benefits.md", "range": {"start": {"line": 39, "column": 59}}}, "severity": "ERROR"}
resource clean up by matching those labels.
This works reliably even when the test process exits abnormally (e.g. sending a SIGKILL).

Check warning on line 41 in content/manuals/testcontainers/benefits.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Docker.RecommendedWords] Consider using 'for example' instead of 'e.g.' Raw Output: {"message": "[Docker.RecommendedWords] Consider using 'for example' instead of 'e.g.'", "location": {"path": "content/manuals/testcontainers/benefits.md", "range": {"start": {"line": 41, "column": 66}}}, "severity": "INFO"}
4 changes: 2 additions & 2 deletions content/manuals/testcontainers/getting-started/go.md
Original file line number Diff line number Diff line change
@@ -20,15 +20,15 @@

From the [Go Release Policy](https://go.dev/doc/devel/release#policy):

> Each major Go release is supported until there are two newer major releases. For example, Go 1.5 was supported until the Go 1.7 release, and Go 1.6 was supported until the Go 1.8 release. We fix critical problems, including critical security problems, in supported releases as needed by issuing minor revisions (for example, Go 1.6.1, Go 1.6.2, and so on).

Check warning on line 23 in content/manuals/testcontainers/getting-started/go.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Docker.We] Avoid using first-person plural like 'We'. Raw Output: {"message": "[Docker.We] Avoid using first-person plural like 'We'.", "location": {"path": "content/manuals/testcontainers/getting-started/go.md", "range": {"start": {"line": 23, "column": 191}}}, "severity": "WARNING"}

_Testcontainers for Go_ is tested against those two latest Go releases, therefore we recommend using any of them.

Check warning on line 25 in content/manuals/testcontainers/getting-started/go.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Docker.We] Avoid using first-person plural like 'we'. Raw Output: {"message": "[Docker.We] Avoid using first-person plural like 'we'.", "location": {"path": "content/manuals/testcontainers/getting-started/go.md", "range": {"start": {"line": 25, "column": 83}}}, "severity": "WARNING"}

## Step 1:Install _Testcontainers for Go_

_Testcontainers for Go_ uses [go mod](https://blog.golang.org/using-go-modules) and you can get it installed via:

```
```bash
go get github.com/testcontainers/testcontainers-go
```

@@ -67,21 +67,21 @@
* `Image` is the Docker image the container starts from.
* `ExposedPorts` lists the ports to be exposed from the container.
* `WaitingFor` is a field you can use to validate when a container is ready. It
is important to get this set because it helps to know when the container is

Check failure on line 70 in content/manuals/testcontainers/getting-started/go.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Docker.Spacing] ' ' should have one space. Raw Output: {"message": "[Docker.Spacing] ' ' should have one space.", "location": {"path": "content/manuals/testcontainers/getting-started/go.md", "range": {"start": {"line": 70, "column": 1}}}, "severity": "ERROR"}
ready to receive any traffic. In this case, we check for the logs we know come

Check warning on line 71 in content/manuals/testcontainers/getting-started/go.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Docker.We] Avoid using first-person plural like 'we'. Raw Output: {"message": "[Docker.We] Avoid using first-person plural like 'we'.", "location": {"path": "content/manuals/testcontainers/getting-started/go.md", "range": {"start": {"line": 71, "column": 47}}}, "severity": "WARNING"}

Check warning on line 71 in content/manuals/testcontainers/getting-started/go.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Docker.We] Avoid using first-person plural like 'we'. Raw Output: {"message": "[Docker.We] Avoid using first-person plural like 'we'.", "location": {"path": "content/manuals/testcontainers/getting-started/go.md", "range": {"start": {"line": 71, "column": 69}}}, "severity": "WARNING"}
from Redis, telling us that it is ready to accept requests.

Check warning on line 72 in content/manuals/testcontainers/getting-started/go.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Docker.We] Avoid using first-person plural like 'us'. Raw Output: {"message": "[Docker.We] Avoid using first-person plural like 'us'.", "location": {"path": "content/manuals/testcontainers/getting-started/go.md", "range": {"start": {"line": 72, "column": 23}}}, "severity": "WARNING"}

When you use `ExposedPorts` you have to imagine yourself using `docker run -p
<port>`. When you do so, `dockerd` maps the selected `<port>` from inside the
container to a random one available on your host.

In the previous example, we expose `6379` for `tcp` traffic to the outside. This

Check warning on line 78 in content/manuals/testcontainers/getting-started/go.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Docker.We] Avoid using first-person plural like 'we'. Raw Output: {"message": "[Docker.We] Avoid using first-person plural like 'we'.", "location": {"path": "content/manuals/testcontainers/getting-started/go.md", "range": {"start": {"line": 78, "column": 26}}}, "severity": "WARNING"}

Check warning on line 78 in content/manuals/testcontainers/getting-started/go.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Docker.SentenceLength] Write short, concise sentences. (<=40 words) Raw Output: {"message": "[Docker.SentenceLength] Write short, concise sentences. (\u003c=40 words)", "location": {"path": "content/manuals/testcontainers/getting-started/go.md", "range": {"start": {"line": 78, "column": 77}}}, "severity": "WARNING"}
allows Redis to be reachable from your code that runs outside the container, but
it also makes parallelization possible because if you add `t.Parallel` to your

Check failure on line 80 in content/manuals/testcontainers/getting-started/go.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'parallelization'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'parallelization'?", "location": {"path": "content/manuals/testcontainers/getting-started/go.md", "range": {"start": {"line": 80, "column": 15}}}, "severity": "ERROR"}
tests, and each of them starts a Redis container each of them will be exposed on a
different random port.

`testcontainers.GenericContainer` creates the container. In this example we are

Check warning on line 84 in content/manuals/testcontainers/getting-started/go.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Docker.We] Avoid using first-person plural like 'we'. Raw Output: {"message": "[Docker.We] Avoid using first-person plural like 'we'.", "location": {"path": "content/manuals/testcontainers/getting-started/go.md", "range": {"start": {"line": 84, "column": 74}}}, "severity": "WARNING"}
using `Started: true`. It means that the container function will wait for the
container to be up and running. If you set the `Start` value to `false` it won't
start, leaving to you the decision about when to start it.
@@ -93,7 +93,7 @@

> [!TIP]
>
> Look at [features/garbage_collector](/features/garbage_collector/) to know another
> Look at [features/garbage_collector](https://golang.testcontainers.org/features/garbage_collector/) to know another
> way to clean up resources.

## Step 3: Make your code talk to the container
6 changes: 3 additions & 3 deletions content/manuals/testcontainers/getting-started/java.md
Original file line number Diff line number Diff line change
@@ -8,11 +8,11 @@
weight: 20
---

- [JUnit 4 Quickstart](#junit-4-quickstart)

Check failure on line 11 in content/manuals/testcontainers/getting-started/java.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'JUnit'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'JUnit'?", "location": {"path": "content/manuals/testcontainers/getting-started/java.md", "range": {"start": {"line": 11, "column": 4}}}, "severity": "ERROR"}
- [JUnit 5 Quickstart](#junit-5-quickstart)

Check failure on line 12 in content/manuals/testcontainers/getting-started/java.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'JUnit'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'JUnit'?", "location": {"path": "content/manuals/testcontainers/getting-started/java.md", "range": {"start": {"line": 12, "column": 4}}}, "severity": "ERROR"}
- [Spock Quickstart](#spock-quickstart)

## JUnit 4 Quickstart

Check failure on line 15 in content/manuals/testcontainers/getting-started/java.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'JUnit'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'JUnit'?", "location": {"path": "content/manuals/testcontainers/getting-started/java.md", "range": {"start": {"line": 15, "column": 4}}}, "severity": "ERROR"}

It's easy to add Testcontainers to your project - let's walk through a quick example to see how.

@@ -84,7 +84,7 @@
.withExposedPorts(6379);
```

The `@Rule` annotation tells JUnit to notify this field about various events in the test lifecycle.

Check failure on line 87 in content/manuals/testcontainers/getting-started/java.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'JUnit'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'JUnit'?", "location": {"path": "content/manuals/testcontainers/getting-started/java.md", "range": {"start": {"line": 87, "column": 30}}}, "severity": "ERROR"}
In this case, our rule object is a Testcontainers `GenericContainer`, configured to use a specific Redis image from Docker Hub, and configured to expose a port.

If we run our test as-is, then regardless of the actual test outcome, we'll see logs showing us that Testcontainers:
@@ -97,7 +97,7 @@

### Step 3: Make sure our code can talk to the container

Before Testcontainers, we might have hardcoded an address like `localhost:6379` into our tests.

Check failure on line 100 in content/manuals/testcontainers/getting-started/java.md

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'hardcoded'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'hardcoded'?", "location": {"path": "content/manuals/testcontainers/getting-started/java.md", "range": {"start": {"line": 100, "column": 38}}}, "severity": "ERROR"}

Testcontainers uses *randomized ports* for each container it starts, but makes it easy to obtain the actual port at runtime.
We can do this in our test `setUp` method, to set up our component under test:
@@ -117,7 +117,7 @@
> not work on your current or future CI environment. As such, **avoid hard-coding** the address, and use
> `getHost()` instead.

### Step 4: Run the tests!
### Step 4: Run the tests

That's it!

@@ -282,7 +282,7 @@
current environment. Set `disabledWithoutDocker` to `true`.
* Enable parallel container initialization instead of sequential (by default). Set `parallel` to `true`.

### Step 5: Run the tests!
### Step 5: Run the tests

That's it!

@@ -431,7 +431,7 @@
> not work on your current or future CI environment. As such, **avoid hard-coding** the address, and use
> `containerIpAddress` instead.

### Step 4: Run the tests!
### Step 4: Run the tests

That's it!

Loading
Oops, something went wrong.