Skip to content

Commit 92a6764

Browse files
cristianrgrecocristianrgreco
committed
Update quickstart docs
1 parent 574c47b commit 92a6764

File tree

1 file changed

+114
-28
lines changed

1 file changed

+114
-28
lines changed

‎docs/quickstart.md‎

Lines changed: 114 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -8,31 +8,32 @@ npm install testcontainers --save-dev
88

99
## Example
1010

11-
### JavaScript
11+
As an example, let's spin up and test a Redis container.
1212

13-
Let's spin up and use a Redis container:
13+
First, let's install the dependencies:
1414

15-
```javascript
16-
const redis = require("async-redis");
17-
const { GenericContainer } = require("testcontainers");
15+
```bash
16+
npm install redis
17+
```
18+
19+
Using your favorite testing library, let's now create a test:
20+
21+
```ts
22+
import { createClient, RedisClientType } from "redis";
23+
import { GenericContainer, StartedTestContainer } from "testcontainers";
1824

1925
describe("Redis", () => {
20-
let container;
21-
let redisClient;
26+
let container: StartedTestContainer;
27+
let redisClient: RedisClientType;
2228

2329
beforeAll(async () => {
24-
container = await new GenericContainer("redis")
25-
.withExposedPorts(6379)
26-
.start();
27-
28-
redisClient = redis.createClient(
29-
container.getMappedPort(6379),
30-
container.getHost(),
31-
);
30+
container = await new GenericContainer("redis").withExposedPorts(6379).start();
31+
redisClient = createClient({ url: `redis://${container.getHost()}:${container.getMappedPort(6379)}` });
32+
await redisClient.connect();
3233
});
3334

3435
afterAll(async () => {
35-
await redisClient.quit();
36+
await redisClient.disconnect();
3637
await container.stop();
3738
});
3839

@@ -43,19 +44,104 @@ describe("Redis", () => {
4344
});
4445
```
4546

46-
### TypeScript
47+
Run the test, and after a few seconds, it passes!
48+
49+
Why did it take a few seconds? Because your container runtime likely had to pull the image first. If you run the test again, it'll likely pass much faster.
4750

48-
Testcontainers is built with TypeScript and offers first-class support for TypeScript users:
51+
It would be nice to see what Testcontainers is doing while the test is running. You can enable all debug logging by setting the `DEBUG` environment variable. For example:
4952

50-
```typescript
51-
import {
52-
TestContainer,
53-
StartedTestContainer,
54-
StoppedTestContainer,
55-
GenericContainer
56-
} from "testcontainers";
53+
```bash
54+
DEBUG=testcontainers* npm test
55+
```
56+
57+
If we run the test again, we'll see a lot of debug output:
5758

58-
const container: TestContainer = new GenericContainer("alpine");
59-
const startedContainer: StartedTestContainer = await container.start();
60-
const stoppedContainer: StoppedTestContainer = await startedContainer.stop();
6159
```
60+
[DEBUG] Checking container runtime strategy "UnixSocketStrategy"...
61+
[TRACE] Fetching Docker info...
62+
[TRACE] Fetching remote container runtime socket path...
63+
[TRACE] Resolving host...
64+
[TRACE] Fetching Compose info...
65+
[TRACE] Looking up host IPs...
66+
[TRACE] Initialising clients...
67+
[TRACE] Container runtime info:
68+
[DEBUG] Container runtime strategy "UnixSocketStrategy" works
69+
[DEBUG] Checking if image exists "redis:latest"...
70+
[DEBUG] Checked if image exists "redis:latest"
71+
[DEBUG] Pulling image "redis:latest"...
72+
[DEBUG] Executing Docker credential provider "docker-credential-desktop.exe"
73+
[DEBUG] Auth config found for registry "https://index.docker.io/v1/": CredsStore
74+
[redis:latest] {"status":"Pulling from library/redis","id":"latest"}
75+
[redis:latest] {"status":"Pulling fs layer","progressDetail":{},"id":"6e909acdb790"}
76+
...
77+
[redis:latest] {"status":"Status: Downloaded newer image for redis:latest"}
78+
[DEBUG] Pulled image "redis:latest"
79+
[DEBUG] Acquiring lock file "/tmp/testcontainers-node.lock"...
80+
[DEBUG] Acquired lock file "/tmp/testcontainers-node.lock"
81+
[DEBUG] Listing containers...
82+
[DEBUG] Listed containers
83+
[DEBUG] Creating new Reaper for session "4c81d4efc176" with socket path "/var/run/docker.sock"...
84+
[DEBUG] Checking if image exists "testcontainers/ryuk:0.11.0"...
85+
[DEBUG] Checked if image exists "testcontainers/ryuk:0.11.0"
86+
[DEBUG] Image "testcontainers/ryuk:0.11.0" already exists
87+
[DEBUG] Creating container for image "testcontainers/ryuk:0.11.0"...
88+
[DEBUG] [11a9d12ea231] Created container for image "testcontainers/ryuk:0.11.0"
89+
[INFO] [11a9d12ea231] Starting container for image "testcontainers/ryuk:0.11.0"...
90+
[DEBUG] [11a9d12ea231] Starting container...
91+
[DEBUG] [11a9d12ea231] Started container
92+
[INFO] [11a9d12ea231] Started container for image "testcontainers/ryuk:0.11.0"
93+
[DEBUG] [11a9d12ea231] Fetching container logs...
94+
[DEBUG] [11a9d12ea231] Demuxing stream...
95+
[DEBUG] [11a9d12ea231] Demuxed stream
96+
[DEBUG] [11a9d12ea231] Fetched container logs
97+
[DEBUG] [11a9d12ea231] Waiting for container to be ready...
98+
[DEBUG] [11a9d12ea231] Waiting for log message "/.*Started.*/"...
99+
[DEBUG] [11a9d12ea231] Fetching container logs...
100+
[11a9d12ea231] time=2025-03-24T12:10:17.130Z level=INFO msg=starting connection_timeout=1m0s reconnection_timeout=10s request_timeout=10s shutdown_timeout=10m0s remove_retries=10 retry_offset=-1s changes_retry_interval=1s port=8080 verbose=false
101+
[11a9d12ea231] time=2025-03-24T12:10:17.130Z level=INFO msg=Started address=[::]:8080
102+
[11a9d12ea231] time=2025-03-24T12:10:17.130Z level=INFO msg="client processing started"
103+
[DEBUG] [11a9d12ea231] Demuxing stream...
104+
[DEBUG] [11a9d12ea231] Demuxed stream
105+
[DEBUG] [11a9d12ea231] Fetched container logs
106+
[DEBUG] [11a9d12ea231] Log wait strategy complete
107+
[INFO] [11a9d12ea231] Container is ready
108+
[DEBUG] [11a9d12ea231] Connecting to Reaper (attempt 1) on "localhost:32774"...
109+
[DEBUG] [11a9d12ea231] Connected to Reaper
110+
[DEBUG] Releasing lock file "/tmp/testcontainers-node.lock"...
111+
[DEBUG] Released lock file "/tmp/testcontainers-node.lock"
112+
[DEBUG] Creating container for image "redis:latest"...
113+
[11a9d12ea231] time=2025-03-24T12:10:17.145Z level=INFO msg="client connected" address=172.17.0.1:40446 clients=1
114+
[11a9d12ea231] time=2025-03-24T12:10:17.145Z level=INFO msg="adding filter" type=label values="[org.testcontainers.session-id=4c81d4efc176]"
115+
[936d82e9964e] Created container for image "redis:latest"
116+
[936d82e9964e] Starting container for image "redis:latest"...
117+
[936d82e9964e] Starting container...
118+
[936d82e9964e] Started container
119+
[936d82e9964e] Started container for image "redis:latest"
120+
[936d82e9964e] Fetching container logs...
121+
[936d82e9964e] Demuxing stream...
122+
[936d82e9964e] Demuxed stream
123+
[936d82e9964e] Fetched container logs
124+
[936d82e9964e] Waiting for container to be ready...
125+
[936d82e9964e] Waiting for host port 32775...
126+
[936d82e9964e] Waiting for internal port 6379...
127+
[936d82e9964e] 1:C 24 Mar 2025 12:10:17.419 * oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
128+
[936d82e9964e] 1:C 24 Mar 2025 12:10:17.419 * Redis version=7.4.2, bits=64, commit=00000000, modified=0, pid=1, just started
129+
[936d82e9964e] 1:C 24 Mar 2025 12:10:17.419 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf
130+
[936d82e9964e] 1:M 24 Mar 2025 12:10:17.419 * monotonic clock: POSIX clock_gettime
131+
[936d82e9964e] 1:M 24 Mar 2025 12:10:17.419 * Running mode=standalone, port=6379.
132+
[936d82e9964e] 1:M 24 Mar 2025 12:10:17.420 * Server initialized
133+
[936d82e9964e] 1:M 24 Mar 2025 12:10:17.420 * Ready to accept connections tcp
134+
[DEBUG] [936d82e9964e] Host port 32775 ready
135+
[DEBUG] [936d82e9964e] Host port wait strategy complete
136+
[DEBUG] [936d82e9964e] Internal port 6379 ready
137+
[INFO] [936d82e9964e] Container is ready
138+
[INFO] [936d82e9964e] Stopping container...
139+
[DEBUG] [936d82e9964e] Stopping container...
140+
[936d82e9964e] 1:signal-handler (1742818217) Received SIGTERM scheduling shutdown...
141+
[DEBUG] [936d82e9964e] Stopped container
142+
[DEBUG] [936d82e9964e] Removing container...
143+
[DEBUG] [936d82e9964e] Removed container
144+
[INFO] [936d82e9964e] Stopped container
145+
```
146+
147+
These logs are very useful for debugging when a container isn't working as expected. You can see there are logs from the Testcontainers library, as well as logs emitted from all Testcontainers-managed containers.

0 commit comments

Comments
 (0)