Skip to content

Commit 5615145

Browse files
mdelapenyamdelapenya
committed
chore: adds quickstarts for tc-go and tc-java
1 parent 0965d94 commit 5615145

File tree

5 files changed

+707
-0
lines changed

5 files changed

+707
-0
lines changed

‎content/manuals/testcontainers/_index.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: Testcontainers OSS
3+
weight: 30
4+
description: Learn how to use Testcontainers OSS to run containers programmatically in your preferred programming language.
5+
keywords: docker APIs, docker, testcontainers documentation, testcontainers, testcontainers oss, testcontainers oss documentation,
6+
docker compose, docker-compose, java, golang, go
7+
params:
8+
sidebar:
9+
group: Open source
10+
grid:
11+
- title: Why use Testcontainers?
12+
description: Understand Testcontainers' key benefits
13+
icon: feature_search
14+
link: /testcontainers/benefits/
15+
- title: Quickstart
16+
description: Learn the key concepts of Testcontainers OSS
17+
icon: explore
18+
link: /testcontainers/getting-started
19+
aliases:
20+
- /testcontainers/
21+
---
22+
23+
Testcontainers is set libraries that provides easy and lightweight APIs for bootstrapping local development and test dependencies with real services wrapped in Docker containers.
24+
Using Testcontainers, you can write tests that depend on the same services you use in production without mocks or in-memory services.
25+
26+
{{< grid >}}
27+
28+
## Want to know more?
29+
30+
- Visit the [Testcontainers website](https://testcontainers.com/getting-started/)

‎content/manuals/testcontainers/benefits.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
description: Key benefits and use cases of Testcontainers OSS
3+
keywords: documentation, docs, docker, testcontainers, containers, uses, benefits
4+
title: Why use Testcontainers?
5+
weight: 10
6+
linkTitle: Why use Testcontainers?
7+
aliases:
8+
- /testcontainers/benefits/
9+
---
10+
11+
### Benefits of using Testcontainers:
12+
13+
* **On-demand isolated infrastructure provisioning:**
14+
You don't need to have a pre-provisioned integration testing infrastructure.
15+
Testcontainers will provide the required services before running your tests.
16+
There will be no test data pollution, even when multiple build pipelines run in parallel
17+
because each pipeline runs with an isolated set of services.
18+
19+
* **Consistent experience on both local and CI environments:**
20+
You can run your integration tests right from your IDE, just like you run unit tests.
21+
No need to push your changes and wait for the CI pipeline to complete.
22+
23+
* **Reliable test setup using wait strategies:**
24+
Docker containers need to be started and fully initialized before using them in your tests.
25+
The Testcontainers library offers several out-of-the-box wait strategies implementations to make sure
26+
the containers (and the application within) are fully initialized.
27+
Testcontainers modules already implement the relevant wait strategies for a given technology,
28+
and you can always implement your own or create a composite strategy if needed.
29+
30+
* **Advanced networking capabilities:**
31+
Testcontainers libraries map the container's ports onto random ports available on the host machine
32+
so that your tests connect reliably to those services. You can even create a (Docker) network and
33+
connect multiple containers together so that they talk to each other via static Docker network aliases.
34+
35+
* **Automatic clean up:**
36+
The Testcontainers library takes care of removing any created resources (containers, volumes, networks etc.)
37+
automatically after the test execution is complete by using the Ryuk sidecar container.
38+
While starting the required containers, Testcontainers attaches a set of labels to the
39+
created resources (containers, volumes, networks etc) and Ryuk automatically performs
40+
resource clean up by matching those labels.
41+
This works reliably even when the test process exits abnormally (e.g. sending a SIGKILL).

‎content/manuals/testcontainers/getting-started/_index.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
description: Learn how to install Testcontainers OSS and run your first container
3+
keywords: testcontainers, testcontainers quickstart, testcontainers oss, testcontainers oss quickstart, testcontainers quickstart,
4+
java, go, golang
5+
title: Testcontainers Quickstart
6+
linkTitle: Testcontainers Quickstart
7+
weight: 20
8+
toc_max: 3
9+
aliases:
10+
- /testcontainers/getting-started/
11+
---
12+
13+
This page contains summary information about Testcontainers OSS.
14+
15+
## Supported languages
16+
17+
Testcontainers provide support for the most popular languages, and Docker sponsors the development of the following Testcontainers implementations:
18+
19+
- [Go](/manuals/testcontainers/getting-started/go.md)
20+
- [Java](/manuals/testcontainers/getting-started/java.md)
21+
22+
The rest are community-driven and maintained by independent contributors.
23+
24+
## Prerequisites
25+
26+
Testcontainers requires a Docker-API compatible container runtime.
27+
During development, Testcontainers is actively tested against recent versions of Docker on Linux, as well as against Docker Desktop on Mac and Windows.
28+
These Docker environments are automatically detected and used by Testcontainers without any additional configuration being necessary.
29+
30+
It is possible to configure Testcontainers to work for other Docker setups, such as a remote Docker host or Docker alternatives.
31+
However, these are not actively tested in the main development workflow, so not all Testcontainers features might be available
32+
and additional manual configuration might be necessary.
33+
34+
If you have further questions about configuration details for your setup or whether it supports running Testcontainers-based tests,
35+
please contact the Testcontainers team and other users from the Testcontainers community on [Slack](https://slack.testcontainers.org/).

‎content/manuals/testcontainers/getting-started/go.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
description: How to install Testcontainers for Go and run your first container
3+
keywords: testcontainers, testcontainers go, testcontainers oss, testcontainers oss go, testcontainers go quickstart
4+
toc_max: 3
5+
title: Go quickstart
6+
linkTitle: Go
7+
aliases:
8+
- /testcontainers/getting-started/go/
9+
weight: 10
10+
---
11+
12+
_Testcontainers for Go_ plays well with the native `go test` framework.
13+
14+
The ideal use case is for integration or end to end tests. It helps you to spin
15+
up and manage the dependencies life cycle via Docker.
16+
17+
## System requirements
18+
19+
### Go version
20+
21+
From the [Go Release Policy](https://go.dev/doc/devel/release#policy):
22+
23+
> 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).
24+
25+
_Testcontainers for Go_ is tested against those two latest Go releases, therefore we recommend using any of them.
26+
27+
## Step 1:Install _Testcontainers for Go_
28+
29+
_Testcontainers for Go_ uses [go mod](https://blog.golang.org/using-go-modules) and you can get it installed via:
30+
31+
```
32+
go get github.com/testcontainers/testcontainers-go
33+
```
34+
35+
## Step 2: Spin up Redis
36+
37+
```go
38+
import (
39+
"context"
40+
"testing"
41+
42+
"github.com/stretchr/testify/require"
43+
44+
"github.com/testcontainers/testcontainers-go"
45+
"github.com/testcontainers/testcontainers-go/wait"
46+
)
47+
48+
func TestWithRedis(t *testing.T) {
49+
ctx := context.Background()
50+
req := testcontainers.ContainerRequest{
51+
Image: "redis:latest",
52+
ExposedPorts: []string{"6379/tcp"},
53+
WaitingFor: wait.ForLog("Ready to accept connections"),
54+
}
55+
redisC, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
56+
ContainerRequest: req,
57+
Started: true,
58+
})
59+
testcontainers.CleanupContainer(t, redisC)
60+
require.NoError(t, err)
61+
}
62+
```
63+
64+
The `testcontainers.ContainerRequest` describes how the Docker container will
65+
look.
66+
67+
* `Image` is the Docker image the container starts from.
68+
* `ExposedPorts` lists the ports to be exposed from the container.
69+
* `WaitingFor` is a field you can use to validate when a container is ready. It
70+
is important to get this set because it helps to know when the container is
71+
ready to receive any traffic. In this case, we check for the logs we know come
72+
from Redis, telling us that it is ready to accept requests.
73+
74+
When you use `ExposedPorts` you have to imagine yourself using `docker run -p
75+
<port>`. When you do so, `dockerd` maps the selected `<port>` from inside the
76+
container to a random one available on your host.
77+
78+
In the previous example, we expose `6379` for `tcp` traffic to the outside. This
79+
allows Redis to be reachable from your code that runs outside the container, but
80+
it also makes parallelization possible because if you add `t.Parallel` to your
81+
tests, and each of them starts a Redis container each of them will be exposed on a
82+
different random port.
83+
84+
`testcontainers.GenericContainer` creates the container. In this example we are
85+
using `Started: true`. It means that the container function will wait for the
86+
container to be up and running. If you set the `Start` value to `false` it won't
87+
start, leaving to you the decision about when to start it.
88+
89+
All the containers must be removed at some point, otherwise they will run until
90+
the host is overloaded. One of the ways we have to clean up is by deferring the
91+
terminated function: `defer testcontainers.TerminateContainer(redisC)` which
92+
automatically handles nil container so is safe to use even in the error case.
93+
94+
> [!TIP]
95+
>
96+
> Look at [features/garbage_collector](/features/garbage_collector/) to know another
97+
> way to clean up resources.
98+
99+
## Step 3: Make your code talk to the container
100+
101+
This is just an example, but usually Go applications that rely on Redis are
102+
using the [redis-go](https://github.com/go-redis/redis) client. This code gets
103+
the endpoint from the container we just started, and it configures the client.
104+
105+
```go
106+
endpoint, err := redisC.Endpoint(ctx, "")
107+
if err != nil {
108+
t.Error(err)
109+
}
110+
111+
client := redis.NewClient(&redis.Options{
112+
Addr: endpoint,
113+
})
114+
115+
_ = client
116+
```
117+
118+
We expose only one port, so the `Endpoint` does not need a second argument set.
119+
120+
> [!TIP]
121+
>
122+
> If you expose more than one port you can specify the one you need as a second
123+
> argument.
124+
125+
In this case it returns: `localhost:<mappedportfor-6379>`.
126+
127+
## Step 4: Run the test
128+
129+
You can run the test via `go test ./...`
130+
131+
## Step 5: Want to go deeper with Redis?
132+
133+
You can find a more elaborated Redis example in our examples section. Please check it out [here](https://golang.testcontainers.org/modules/redis/).

0 commit comments

Comments
 (0)