From 8a5b26c4a84581587f76d18ae421f855ea0db2b2 Mon Sep 17 00:00:00 2001 From: osher Date: Tue, 22 Oct 2024 14:28:12 +0300 Subject: [PATCH 1/7] Docs - make withWaitStrategy easier to find MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I believe this is a far more important feature than to be left on the advanced features page alone. I was looking for it, and wished it was more obvious to find 🙂 I hope you accept this contribution :) --- docs/features/containers.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/features/containers.md b/docs/features/containers.md index 43bbbb0ce..93710b276 100644 --- a/docs/features/containers.md +++ b/docs/features/containers.md @@ -202,6 +202,27 @@ const container = await new GenericContainer("alpine") .start(); ``` +### With a wait strategy + +A wait strategy will resolve the call to `.start()` only when a start condition is met. This allows you to ensure the container can perform its work before resolving. + +There are many built-in wait strategies, supporting varying conditions, [see here](../wait-strategies). + +A strategy can be a single condition or a composition of a few conditions. Here is an example of the latter: + +```javascript +import { GenericContainer, Wait } from "testcontainers"; + +const container = await new GenericContainer("my-upstream-service") + .withExposedPorts(3000) + .withWaitStrategy(Wait.forAll([ + Wait.forListeningPorts(), + Wait.forLogMessage(/server started on port/), + Wait.forHealthCheck(), + ])) + .start(); +``` + ### With default log driver May be necessary when the driver of your docker host does not support reading logs, and you want to use the [log output wait strategy](../wait-strategies#log-output). From de594498362d38780be16ee6b8813c0bce1ec186 Mon Sep 17 00:00:00 2001 From: osher Date: Tue, 22 Oct 2024 14:33:42 +0300 Subject: [PATCH 2/7] Refine link to [Wait Strategies] page --- docs/features/containers.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/features/containers.md b/docs/features/containers.md index 93710b276..e5447b837 100644 --- a/docs/features/containers.md +++ b/docs/features/containers.md @@ -5,6 +5,7 @@ Create and start any container using a Generic Container: ```javascript + const { GenericContainer } = require("testcontainers"); const container = await new GenericContainer("alpine").start(); @@ -206,7 +207,7 @@ const container = await new GenericContainer("alpine") A wait strategy will resolve the call to `.start()` only when a start condition is met. This allows you to ensure the container can perform its work before resolving. -There are many built-in wait strategies, supporting varying conditions, [see here](../wait-strategies). +There are many built-in wait strategies, supporting varying conditions, see [wait Strategies](../wait-strategies). A strategy can be a single condition or a composition of a few conditions. Here is an example of the latter: From 4bfd21bb91967d5416cd56c6ccaba271ddfe6924 Mon Sep 17 00:00:00 2001 From: osher Date: Tue, 22 Oct 2024 14:35:51 +0300 Subject: [PATCH 3/7] Docs - add header for wait-strategies page --- docs/features/wait-strategies.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/features/wait-strategies.md b/docs/features/wait-strategies.md index e396229c8..da402f057 100644 --- a/docs/features/wait-strategies.md +++ b/docs/features/wait-strategies.md @@ -1,5 +1,9 @@ # Wait Strategies +A wait strategy will resolve the call to `container.start()` only after a condition is met. This allows you to ensure the container can perform its work before resolving. + +There are many built-in wait strategies, supporting varying conditions, which are listed below. + Note that the startup timeout of all wait strategies is configurable: ```javascript From b16d3fd557cbdf3441a7ff6c738def261555db5e Mon Sep 17 00:00:00 2001 From: osher Date: Tue, 22 Oct 2024 14:38:12 +0300 Subject: [PATCH 4/7] Docs - containers/wait-strategies - improve order of text --- docs/features/containers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/containers.md b/docs/features/containers.md index e5447b837..00ea184ab 100644 --- a/docs/features/containers.md +++ b/docs/features/containers.md @@ -207,8 +207,6 @@ const container = await new GenericContainer("alpine") A wait strategy will resolve the call to `.start()` only when a start condition is met. This allows you to ensure the container can perform its work before resolving. -There are many built-in wait strategies, supporting varying conditions, see [wait Strategies](../wait-strategies). - A strategy can be a single condition or a composition of a few conditions. Here is an example of the latter: ```javascript @@ -224,6 +222,8 @@ const container = await new GenericContainer("my-upstream-service") .start(); ``` +There are many built-in wait strategies, supporting varying conditions. For more info - see [wait Strategies](../wait-strategies). + ### With default log driver May be necessary when the driver of your docker host does not support reading logs, and you want to use the [log output wait strategy](../wait-strategies#log-output). From 24f47c793340f195e955a3120af3a9775cc1c4f2 Mon Sep 17 00:00:00 2001 From: osher Date: Wed, 23 Oct 2024 10:48:04 +0300 Subject: [PATCH 5/7] Remove unecessary empty line --- docs/features/containers.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/features/containers.md b/docs/features/containers.md index 00ea184ab..a77e0d8ee 100644 --- a/docs/features/containers.md +++ b/docs/features/containers.md @@ -5,7 +5,6 @@ Create and start any container using a Generic Container: ```javascript - const { GenericContainer } = require("testcontainers"); const container = await new GenericContainer("alpine").start(); From 518571202dfcccc64803b2520d0b01afc9199281 Mon Sep 17 00:00:00 2001 From: osher Date: Wed, 23 Oct 2024 10:52:13 +0300 Subject: [PATCH 6/7] Containers / Wait Strategies - add clarification on custom strategies --- docs/features/containers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/containers.md b/docs/features/containers.md index a77e0d8ee..ac3d7bce7 100644 --- a/docs/features/containers.md +++ b/docs/features/containers.md @@ -221,7 +221,7 @@ const container = await new GenericContainer("my-upstream-service") .start(); ``` -There are many built-in wait strategies, supporting varying conditions. For more info - see [wait Strategies](../wait-strategies). +There are many built-in wait strategies, supporting varying conditions, or you can write your own. For more info - see [wait Strategies](../wait-strategies). ### With default log driver From 5cc8bb512abb79d1c2ecf522784d31db35e9209a Mon Sep 17 00:00:00 2001 From: osher Date: Wed, 23 Oct 2024 10:54:00 +0300 Subject: [PATCH 7/7] wait-strategies - fix title of Custom wait strategies --- docs/features/wait-strategies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/wait-strategies.md b/docs/features/wait-strategies.md index da402f057..077d799a5 100644 --- a/docs/features/wait-strategies.md +++ b/docs/features/wait-strategies.md @@ -238,7 +238,7 @@ const w2 = Wait.forLogMessage("READY"); const composite = Wait.forAll([w1, w2]).withDeadline(2000); ``` -## Other startup strategies +## Custom Wait Strategies If these options do not meet your requirements, you can subclass `StartupCheckStrategy` and use `Dockerode`, which is the underlying Docker client used by Testcontainers: