Merge branch 'main' into release-11.0.0

Author: cristianrgreco

docs/features/compose.md

@@ -140,11 +140,11 @@ const environment = await new DockerComposeEnvironment(composeFilePath, composeF
 await environment.down();
 ```
 
-If you need to wait for the environment to be downed, you can provide a timeout:
+If you need to wait for the environment to be downed, you can provide a timeout. The unit of timeout here is **second**:
 
 ```javascript
 const environment = await new DockerComposeEnvironment(composeFilePath, composeFile).up();
-await environment.down({ timeout: 10000 }); // ms
+await environment.down({ timeout: 10 }); // timeout after 10 seconds
 ```
 
 Volumes created by the environment are removed when stopped. This is configurable:

docs/features/containers.md

@@ -334,11 +334,11 @@ const container = await new GenericContainer("alpine").start();
 await container.stop();
 ```
 
-If you need to wait for the container to be stopped, you can provide a timeout:
+If you need to wait for the container to be stopped, you can provide a timeout. The unit of timeout option here is **second**:
 
 ```javascript
 const container = await new GenericContainer("alpine").start();
-await container.stop({ timeout: 10000 }); // ms
+await container.stop({ timeout: 10 }); // 10 seconds
 ```
 
 You can disable automatic removal of the container, which is useful for debugging, or if for example you want to copy content from the container once it has stopped:
@@ -583,6 +583,35 @@ const container = await new GenericContainer("alpine")
   .start();
 ```
 
+## SocatContainer as a TCP proxy
+
+`SocatContainer` enables any TCP port of another container to be exposed publicly.
+
+```javascript
+const network = await new Network().start();
+
+const container = await new GenericContainer("testcontainers/helloworld:1.2.0")
+  .withExposedPorts(8080)
+  .withNetwork(network)
+  .withNetworkAliases("helloworld")
+  .start();
+
+const socat = await new SocatContainer()
+  .withNetwork(network)
+  .withTarget(8081, "helloworld", 8080)
+  .start();
+
+const socatUrl = `http://${socat.getHost()}:${socat.getMappedPort(8081)}`;
+
+const response = await fetch(`${socatUrl}/ping`);
+
+expect(response.status).toBe(200);
+expect(await response.text()).toBe("PONG");
+```
+
+The example above starts a `testcontainers/helloworld` container and a `socat` container. 
+The `socat` container is configured to forward traffic from port `8081` to the `testcontainers/helloworld` container on port `8080`.
+
 ## Running commands
 
 To run a command inside an already started container, use the exec method. 
@@ -605,7 +634,6 @@ The following options can be provided to modify the command execution:
 
 3. **`env`:** A map of environment variables to set inside the container.
 
-
 ```javascript
 const container = await new GenericContainer("alpine")
   .withCommand(["sleep", "infinity"])
@@ -621,8 +649,6 @@ const { output, stdout, stderr, exitCode } = await container.exec(["echo", "hell
 });
 ```
 
-
-
 ## Streaming logs
 
 Logs can be consumed either from a started container:

docs/features/wait-strategies.md

@@ -1,12 +1,12 @@
 # Wait Strategies
 
-Note that the startup timeout of all wait strategies is configurable:
+Note that the startup timeout of all wait strategies is configurable. The unit of timeout of wait strategies is **millisecond**:
 
 ```javascript
 const { GenericContainer } = require("testcontainers");
 
 const container = await new GenericContainer("alpine")
-  .withStartupTimeout(120000) // wait 120s
+  .withStartupTimeout(120000) // wait 120 seconds
   .start();
 ```
 
@@ -73,7 +73,7 @@ const { GenericContainer, Wait } = require("testcontainers");
 const container = await new GenericContainer("alpine").withWaitStrategy(Wait.forHealthCheck()).start();
 ```
 
-Define your own health check:
+Define your own health check. The unit of timeouts and intervals here is **millisecond**:
 
 ```javascript
 const { GenericContainer, Wait } = require("testcontainers");
@@ -148,21 +148,21 @@ const container = await new GenericContainer("redis")
   .withMethod("POST")
   .withHeaders({ X_CUSTOM_VALUE: "custom" })
   .withBasicCredentials("username", "password")
-  .withReadTimeout(10000))
+  .withReadTimeout(10000)) // timeout after 10 seconds
 ```
 
 ### Use TLS
 
 ```javascript
 .withWaitStrategy(Wait.forHttp("/health", 8443)
-  .useTls())
+  .usingTls())
 ```
 
 #### Insecure TLS
 
 ```javascript
 .withWaitStrategy(Wait.forHttp("/health", 8443)
-  .useTls()
+  .usingTls()
   .insecureTls())
 ```
 
@@ -202,11 +202,11 @@ const container = await new GenericContainer("alpine")
   .start();
 ```
 
-The composite wait strategy by default will respect each individual wait strategy's startup timeout. For example:
+The composite wait strategy by default will respect each individual wait strategy's startup timeout. The unit of timeouts here is **millisecond**. For example:
 
 ```javascript
-const w1 = Wait.forListeningPorts().withStartupTimeout(1000);
-const w2 = Wait.forLogMessage("READY").withStartupTimeout(2000);
+const w1 = Wait.forListeningPorts().withStartupTimeout(1000); // wait 1 second
+const w2 = Wait.forLogMessage("READY").withStartupTimeout(2000); // wait 2 seconds
 
 const composite = Wait.forAll([w1, w2]);
 
@@ -217,21 +217,21 @@ expect(w2.getStartupTimeout()).toBe(2000);
 The startup timeout of inner wait strategies that have not defined their own startup timeout can be set by setting the startup timeout on the composite:
 
 ```javascript
-const w1 = Wait.forListeningPorts().withStartupTimeout(1000);
+const w1 = Wait.forListeningPorts().withStartupTimeout(1000); // wait 1 second
 const w2 = Wait.forLogMessage("READY");
 
-const composite = Wait.forAll([w1, w2]).withStartupTimeout(2000);
+const composite = Wait.forAll([w1, w2]).withStartupTimeout(2000); // wait 2 seconds
 
 expect(w1.getStartupTimeout()).toBe(1000);
 expect(w2.getStartupTimeout()).toBe(2000);
 ```
 
-The startup timeout of all wait strategies can be controlled by setting a deadline on the composite. In this case, the composite will throw unless all inner wait strategies have resolved before the deadline.
+The startup timeout of all wait strategies can be controlled by setting a deadline on the composite. In this case, the composite will throw unless all inner wait strategies have resolved before the deadline. The unit of deadline timeout is **millisecond**.
 
 ```javascript
 const w1 = Wait.forListeningPorts();
 const w2 = Wait.forLogMessage("READY");
-const composite = Wait.forAll([w1, w2]).withDeadline(2000);
+const composite = Wait.forAll([w1, w2]).withDeadline(2000); // wait 2 seconds
 ```
 
 ## Other startup strategies
@@ -248,7 +248,7 @@ const {
 
 class ReadyAfterDelayWaitStrategy extends StartupCheckStrategy {
   public checkStartupState(dockerClient: Dockerode, containerId: string): Promise<StartupStatus> {
-    return new Promise((resolve) => setTimeout(() => resolve("SUCCESS"), 3000));
+    return new Promise((resolve) => setTimeout(() => resolve("SUCCESS"), 3000)); // after 3 seconds
   }
 }
 

docs/modules/postgresql.md

@@ -25,3 +25,18 @@ npm install @testcontainers/postgresql --save-dev
 <!--codeinclude-->
 [Set username:](../../packages/modules/postgresql/src/postgresql-container.test.ts) inside_block:setUsername
 <!--/codeinclude-->
+
+### Using Snapshots
+
+This example shows the usage of the postgres module's Snapshot feature to give each test a clean database without having
+to recreate the database container on every test or run heavy scripts to clean your database. This makes the individual
+tests very modular, since they always run on a brand-new database.
+
+!!!tip
+    You should never pass the `"postgres"` system database as the container database name if you want to use snapshots. 
+    The Snapshot logic requires dropping the connected database and using the system database to run commands, which will
+    not work if the database for the container is set to `"postgres"`.
+
+<!--codeinclude-->
+[Test with a reusable Postgres container](../../packages/modules/postgresql/src/postgresql-container-snapshot.test.ts) inside_block:createAndRestoreFromSnapshot
+<!--/codeinclude-->

docs/quickstart.md

@@ -0,0 +1,52 @@
+# Global setup
+
+If you have a lot of tests that require the same container, you might not want to spin up one per test.
+
+In this case a common pattern is to set the container up globally, and reuse it in your tests. Here's an example using Vitest:
+
+```ts
+// setup.js
+
+import { createClient, RedisClientType } from "redis";
+import { GenericContainer, StartedTestContainer } from "testcontainers";
+
+export async function setup() {
+  globalThis.redisContainer = await new GenericContainer("redis")
+    .withExposedPorts(6379)
+    .start();
+  
+  globalThis.redisClient = createClient({ 
+    url: `redis://${redisContainer.getHost()}:${redisContainer.getMappedPort(6379)}` 
+  });
+  
+  await globalThis.redisClient.connect();
+}
+
+export async function teardown() {
+  await globalThis.redisClient.disconnect();
+  await globalThis.redisContainer.stop();
+}
+```
+
+```ts
+// vite.config.js
+
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  test: {
+    setupFiles: "./setup.js",
+  }
+});
+```
+
+And to reference the container/client in your tests:
+
+```ts
+it("should set and retrieve a value from Redis", async () => {
+  await globalThis.redisClient.set("key", "test-value");
+  const result = await globalThis.redisClient.get("key");
+  
+  expect(result).toBe("test-value");
+});
+```

docs/quickstart/global-setup.md

@@ -0,0 +1,21 @@
+# Install
+
+Install the Testcontainers dependency.
+
+## NPM
+
+```bash
+npm install testcontainers --save-dev
+```
+
+## Yarn
+
+```bash
+yarn add testcontainers --dev
+```
+
+## PNPM
+
+```bash
+pnpm add testcontainers --save-dev
+```