Merge branch 'main' into refactor-timeouts

Author: cristianrgreco

docs/features/compose.md

@@ -41,6 +41,17 @@ const environment = await new DockerComposeEnvironment(composeFilePath, composeF
   .up();
 ```
 
+### With a default wait strategy
+
+By default Testcontainers uses the "listening ports" wait strategy for all containers. If you'd like to override
+the default wait strategy for all services, you can do so:
+
+```javascript
+const environment = await new DockerComposeEnvironment(composeFilePath, composeFile)
+  .withDefaultWaitStrategy(Wait.forHealthCheck())
+  .up();
+```
+
 ### With a pull policy
 
 Testcontainers will automatically pull an image if it doesn't exist. This is configurable:

docs/features/containers.md

@@ -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

@@ -155,14 +155,14 @@ const container = await new GenericContainer("redis")
 
 ```javascript
 .withWaitStrategy(Wait.forHttp("/health", 8443)
-  .useTls())
+  .usingTls())
 ```
 
 #### Insecure TLS
 
 ```javascript
 .withWaitStrategy(Wait.forHttp("/health", 8443)
-  .useTls()
+  .usingTls()
   .insecureTls())
 ```
 

docs/modules/clickhouse.md

@@ -0,0 +1,55 @@
+# ClickHouse Module
+
+[ClickHouse](https://clickhouse.com/) is a column-oriented database management system for online analytical processing (OLAP) that allows users to generate analytical reports using SQL queries in real-time.
+
+## Install
+
+```bash
+npm install @testcontainers/clickhouse --save-dev
+```
+
+## Examples
+
+<!--codeinclude-->
+[Connect and execute query:](../../packages/modules/clickhouse/src/clickhouse-container.test.ts) inside_block:connectWithOptions
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Connect using URL and execute query:](../../packages/modules/clickhouse/src/clickhouse-container.test.ts) inside_block:connectWithUrl
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Connect with username and password and execute query:](../../packages/modules/clickhouse/src/clickhouse-container.test.ts) inside_block:connectWithUsernameAndPassword
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Set database:](../../packages/modules/clickhouse/src/clickhouse-container.test.ts) inside_block:setDatabase
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Set username:](../../packages/modules/clickhouse/src/clickhouse-container.test.ts) inside_block:setUsername
+<!--/codeinclude-->
+
+### Connection Methods
+
+The module provides several methods to connect to the ClickHouse container:
+
+1. `getClientOptions()` - Returns a configuration object suitable for `@clickhouse/client`:
+   ```typescript
+   {
+     url: string; // HTTP URL with host and port
+     username: string; // Container username
+     password: string; // Container password
+     database: string; // Container database
+   }
+   ```
+2. `getConnectionUrl()` - Returns a complete HTTP URL including credentials and database:
+   ```
+   http://[username[:password]@][host[:port]]/database
+   ```
+3. `getHttpUrl()` - Returns the base HTTP URL without credentials:
+   ```
+   http://[host[:port]]
+   ```
+
+These methods can be used with the `@clickhouse/client` package or any other ClickHouse client.

docs/modules/etcd.md

@@ -0,0 +1,19 @@
+# Etcd Module
+
+[Etcd](https://etcd.io/) is a strongly consistent, distributed key-value store that provides a reliable way to store data that needs to be accessed by a distributed system or cluster of machines.
+
+## Install
+
+```bash
+npm install @testcontainers/etcd --save-dev
+```
+
+## Examples
+
+<!--codeinclude-->
+[Read and write key-value pairs:](../../packages/modules/etcd/src/etcd-container.test.ts) inside_block:readWrite
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Subscribe to key changes:](../../packages/modules/etcd/src/etcd-container.test.ts) inside_block:subscribe
+<!--/codeinclude-->

docs/modules/neo4j.md

@@ -21,3 +21,7 @@ npm install @testcontainers/neo4j --save-dev
 <!--codeinclude-->
 [Configure APOC:](../../packages/modules/neo4j/src/neo4j-container.test.ts) inside_block:apoc
 <!--/codeinclude-->
+
+<!--codeinclude-->
+[Configure other supported plugins:](../../packages/modules/neo4j/src/neo4j-container.test.ts) inside_block:pluginsList
+<!--/codeinclude-->

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/modules/redis.md

@@ -11,21 +11,37 @@ npm install @testcontainers/redis --save-dev
 ## Examples
 
 <!--codeinclude-->
+
 [Start container:](../../packages/modules/redis/src/redis-container.test.ts) inside_block:startContainer
+
 <!--/codeinclude-->
 
 <!--codeinclude-->
+
 [Connect redis client to container:](../../packages/modules/redis/src/redis-container.test.ts) inside_block:simpleConnect
+
 <!--/codeinclude-->
 
 <!--codeinclude-->
+
 [Start container with password authentication:](../../packages/modules/redis/src/redis-container.test.ts) inside_block:startWithCredentials
+
 <!--/codeinclude-->
 
 <!--codeinclude-->
+
 [Define volume for persistent/predefined data:](../../packages/modules/redis/src/redis-container.test.ts) inside_block:persistentData
+
 <!--/codeinclude-->
 
 <!--codeinclude-->
+
+[Start container with redis/redis-stack-server image:](../../packages/modules/redis/src/redis-container.test.ts) inside_block:startWithRedisStack
+
+<!--/codeinclude-->
+
+<!--codeinclude-->
+
 [Execute a command inside the container:](../../packages/modules/redis/src/redis-container.test.ts) inside_block:executeCommand
+
 <!--/codeinclude-->

docs/quickstart/global-setup.md

@@ -19,7 +19,7 @@ export async function setup() {
     url: `redis://${redisContainer.getHost()}:${redisContainer.getMappedPort(6379)}` 
   });
 
-  await redisClient.connect();
+  await globalThis.redisClient.connect();
 }
 
 export async function teardown() {

docs/quickstart/logging.md

@@ -132,4 +132,4 @@ If we run the test again, we'll see a lot of debug output:
 [INFO] [936d82e9964e] Stopped container
 ```
 
-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.
+These logs are 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.