add section in docs describing timeouts

Author: digital88

docs/features/advanced.md

@@ -1,5 +1,35 @@
 # Advanced
 
+## Timeout parameter of APIs
+
+Testcontainers library provides a set of classes and functions, and some of them expect a parameter named `timeout`, `ms`, or similar to be passed from the caller. This parameters are of type `number`, and the unit of measurement for this parameters across all public APIs is the same: millisecond. For example:
+
+```js
+export interface TestContainer {
+  ...
+  withStartupTimeout(ms: number): this; // timeout expected to be passed as milliseconds
+}
+```
+
+The underlying docker APIs may expect different units for timeouts and intervals, and testcontainers library will do the needed conversion under the hood automatically. For example, consider the `stop` method of a container:
+
+```javascript
+const container = await new GenericContainer("alpine").start();
+await container.stop({ timeout: 10_000 }); // testcontainers library expects the timeout to be passed as milliseconds
+```
+
+The Docker API [expects seconds](https://docs.docker.com/reference/api/engine/version/v1.48/#tag/Container/operation/ContainerStop) to be passed to this API call. The 10_000 ms value will be converted to seconds by testontainers library.
+
+Keep in mind that conversion from ms to seconds uses truncation to integer, for example:
+
+```
+5000ms = 5s
+3800ms = 3s
+500ms = 0s
+```
+
+You may also pass a *negative* value to function parameters, but this may lead to unexpedted results.
+
 ## Container Runtime Client
 
 Testcontainers configures an underlying container runtime to perform its tasks. This runtime works automatically with several providers like Docker, Podman, Colima, Rancher Desktop and Testcontainers Desktop. There are too many usage examples to list here, but here are some common examples:

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. The unit of timeout here is **second**:
+If you need to wait for the environment to be downed, you can provide a timeout:
 
 ```javascript
 const environment = await new DockerComposeEnvironment(composeFilePath, composeFile).up();
-await environment.down({ timeout: 10 }); // timeout after 10 seconds
+await environment.down({ timeout: 10_000 }); // 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. The unit of timeout option here is **second**:
+If you need to wait for the container to be stopped, you can provide a timeout:
 
 ```javascript
 const container = await new GenericContainer("alpine").start();
-await container.stop({ timeout: 10 }); // 10 seconds
+await container.stop({ timeout: 10_000 }); // 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:

docs/features/wait-strategies.md

@@ -1,12 +1,12 @@
 # Wait Strategies
 
-Note that the startup timeout of all wait strategies is configurable. The unit of timeout of wait strategies is **millisecond**:
+Note that the startup timeout of all wait strategies is configurable:
 
 ```javascript
 const { GenericContainer } = require("testcontainers");
 
 const container = await new GenericContainer("alpine")
-  .withStartupTimeout(120000) // wait 120 seconds
+  .withStartupTimeout(120_000) // 120 seconds
   .start();
 ```
 
@@ -73,18 +73,18 @@ const { GenericContainer, Wait } = require("testcontainers");
 const container = await new GenericContainer("alpine").withWaitStrategy(Wait.forHealthCheck()).start();
 ```
 
-Define your own health check. The unit of timeouts and intervals here is **millisecond**:
+Define your own health check:
 
 ```javascript
 const { GenericContainer, Wait } = require("testcontainers");
 
 const container = await new GenericContainer("alpine")
   .withHealthCheck({
     test: ["CMD-SHELL", "curl -f http://localhost || exit 1"],
-    interval: 1000,
-    timeout: 3000,
+    interval: 1000, // 1 second
+    timeout: 3000, // 3 seconds
     retries: 5,
-    startPeriod: 1000,
+    startPeriod: 1000, // 1 second
   })
   .withWaitStrategy(Wait.forHealthCheck())
   .start();
@@ -148,7 +148,7 @@ const container = await new GenericContainer("redis")
   .withMethod("POST")
   .withHeaders({ X_CUSTOM_VALUE: "custom" })
   .withBasicCredentials("username", "password")
-  .withReadTimeout(10000)) // timeout after 10 seconds
+  .withReadTimeout(10_000)) // 10 seconds
 ```
 
 ### Use TLS
@@ -186,7 +186,7 @@ This strategy is intended for use with containers that only run briefly and exit
 const { GenericContainer, Wait } = require("testcontainers");
 
 const container = await new GenericContainer("alpine")
-  .withWaitStrategy(Wait.forOneShotStartup()))
+  .withWaitStrategy(Wait.forOneShotStartup())
   .start();
 ```
 
@@ -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. The unit of timeouts here is **millisecond**. For example:
+The composite wait strategy by default will respect each individual wait strategy's startup timeout. For example:
 
 ```javascript
-const w1 = Wait.forListeningPorts().withStartupTimeout(1000); // wait 1 second
-const w2 = Wait.forLogMessage("READY").withStartupTimeout(2000); // wait 2 seconds
+const w1 = Wait.forListeningPorts().withStartupTimeout(1000); // 1 second
+const w2 = Wait.forLogMessage("READY").withStartupTimeout(2000); // 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); // wait 1 second
+const w1 = Wait.forListeningPorts().withStartupTimeout(1000); // 1 second
 const w2 = Wait.forLogMessage("READY");
 
-const composite = Wait.forAll([w1, w2]).withStartupTimeout(2000); // wait 2 seconds
+const composite = Wait.forAll([w1, w2]).withStartupTimeout(2000); // 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 unit of deadline timeout is **millisecond**.
+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.
 
 ```javascript
 const w1 = Wait.forListeningPorts();
 const w2 = Wait.forLogMessage("READY");
-const composite = Wait.forAll([w1, w2]).withDeadline(2000); // wait 2 seconds
+const composite = Wait.forAll([w1, w2]).withDeadline(2000); // 2 seconds
 ```
 
 ## Other startup strategies

packages/testcontainers/src/common/ms.test.ts

@@ -1,7 +1,11 @@
 import { Ms } from "./ms";
 
 describe("Ms", () => {
-  it.for([[10_000, 10_000]])("should return %i ms from %i ms", ([ms1, ms2]) => {
+  it.for([
+    [10_000, 10_000],
+    [-1000, -1000],
+    [0, 0],
+  ])("should return %i ms from %i ms", ([ms1, ms2]) => {
     const t = new Ms(ms1);
     expect(t.value()).toEqual(ms2);
   });
@@ -12,13 +16,19 @@ describe("Ms", () => {
     [1010, 1],
     [1999, 1],
     [10_000, 10],
+    [-10, -0],
+    [-999, -0],
+    [-1010, -1],
+    [-1999, -1],
+    [-10_000, -10],
   ])("should convert %i ms to %i seconds", ([ms, s]) => {
     const t = new Ms(ms);
     expect(t.seconds()).toEqual(s);
   });
   it.for([
     [0, 0],
     [1, 1_000_000],
+    [-1, -1_000_000],
   ])("should convert %i ms to %i ns", ([ms, ns]) => {
     const t = new Ms(ms);
     expect(t.nanos()).toEqual(ns);

packages/testcontainers/src/common/ms.ts

@@ -2,9 +2,7 @@
  * Represents time interval in milliseconds.
  */
 export class Ms {
-  constructor(private readonly milliseconds: number) {
-    if (milliseconds < 0) throw new Error("Negative interval is not supported in this context.");
-  }
+  constructor(private readonly milliseconds: number) {}
   public seconds(): number {
     return Math.trunc(this.milliseconds * 1e-3);
   }