Updates

Author: cristianrgreco

docs/features/advanced.md

@@ -1,35 +1,5 @@
 # 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:
@@ -69,4 +39,4 @@ const environment = await containerRuntimeClient.compose.up({ ... })
 
 ```js
 const network = await containerRuntimeClient.network.create({ ... })
-```
+```**

packages/testcontainers/src/common/index.ts

@@ -1,8 +1,8 @@
 export { withFileLock } from "./file-lock";
 export { hash } from "./hash";
 export { buildLog, composeLog, containerLog, execLog, log, Logger, pullLog } from "./logger";
-export { Ms } from "./ms";
 export { IntervalRetry, Retry } from "./retry";
 export { streamToString } from "./streams";
+export * from "./time";
 export * from "./type-guards";
 export { RandomUuid, Uuid } from "./uuid";

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

@@ -0,0 +1,25 @@
+import { toNanos, toSeconds } from "./time";
+
+test.for([
+  [0, 0],
+  [10, 0],
+  [999, 0],
+  [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]) => {
+  expect(toSeconds(ms)).toEqual(s);
+});
+
+test.for([
+  [0, 0],
+  [1, 1_000_000],
+  [-1, -1_000_000],
+])("should convert %i ms to %i ns", ([ms, ns]) => {
+  expect(toNanos(ms)).toEqual(ns);
+});

packages/testcontainers/src/common/ms.ts

@@ -0,0 +1,3 @@
+export const toSeconds = (ms: number) => Math.trunc(ms * 1e-3);
+
+export const toNanos = (ms: number) => ms * 1e6;

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

@@ -1,5 +1,6 @@
 import { default as dockerComposeV1, default as v1, v2 as dockerComposeV2, v2 } from "docker-compose";
-import { log, Ms, pullLog } from "../../../common";
+import { log, pullLog } from "../../../common";
+import { toSeconds } from "../../../common/time";
 import { ComposeInfo } from "../types";
 import { defaultComposeOptions } from "./default-compose-options";
 import { ComposeDownOptions, ComposeOptions } from "./types";
@@ -222,7 +223,7 @@ function composeDownCommandOptions(options: ComposeDownOptions): string[] {
     result.push("-v");
   }
   if (options.timeout) {
-    result.push("-t", `${new Ms(options.timeout).seconds()}`);
+    result.push("-t", `${toSeconds(options.timeout)}`);
   }
   return result;
 }

packages/testcontainers/src/common/time.ts

@@ -9,7 +9,7 @@ import Dockerode, {
 } from "dockerode";
 import { IncomingMessage } from "http";
 import { PassThrough, Readable } from "stream";
-import { execLog, log, Ms, streamToString } from "../../../common";
+import { execLog, log, streamToString, toSeconds } from "../../../common";
 import { ContainerClient } from "./container-client";
 import { ContainerCommitOptions, ContainerStatus, ExecOptions, ExecResult } from "./types";
 
@@ -120,8 +120,7 @@ export class DockerContainerClient implements ContainerClient {
 
   async inspect(container: Dockerode.Container): Promise<ContainerInspectInfo> {
     try {
-      const inspectInfo = await container.inspect();
-      return inspectInfo;
+      return await container.inspect();
     } catch (err) {
       log.error(`Failed to inspect container: ${err}`, { containerId: container.id });
       throw err;
@@ -131,8 +130,7 @@ export class DockerContainerClient implements ContainerClient {
   async stop(container: Container, opts?: { timeout: number }): Promise<void> {
     try {
       log.debug(`Stopping container...`, { containerId: container.id });
-      const t = new Ms(opts?.timeout ?? 0).seconds();
-      await container.stop({ t });
+      await container.stop({ t: toSeconds(opts?.timeout ?? 0) });
       log.debug(`Stopped container`, { containerId: container.id });
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
     } catch (err: any) {
@@ -257,8 +255,7 @@ export class DockerContainerClient implements ContainerClient {
   async restart(container: Container, opts?: { timeout: number }): Promise<void> {
     try {
       log.debug(`Restarting container...`, { containerId: container.id });
-      const t = new Ms(opts?.timeout ?? 0).seconds();
-      await container.restart({ t });
+      await container.restart({ t: toSeconds(opts?.timeout ?? 0) });
       log.debug(`Restarted container`, { containerId: container.id });
     } catch (err) {
       log.error(`Failed to restart container: ${err}`, { containerId: container.id });

packages/testcontainers/src/container-runtime/clients/compose/compose-client.ts

@@ -68,8 +68,8 @@ export class DockerComposeEnvironment {
     return this;
   }
 
-  public withStartupTimeout(ms: number): this {
-    this.startupTimeoutMs = ms;
+  public withStartupTimeout(startupTimeoutMs: number): this {
+    this.startupTimeoutMs = startupTimeoutMs;
     return this;
   }
 

packages/testcontainers/src/container-runtime/clients/container/docker-container-client.ts

@@ -2,7 +2,7 @@ import archiver from "archiver";
 import AsyncLock from "async-lock";
 import { Container, ContainerCreateOptions, HostConfig } from "dockerode";
 import { Readable } from "stream";
-import { containerLog, hash, log, Ms } from "../common";
+import { containerLog, hash, log, toNanos } from "../common";
 import { ContainerRuntimeClient, getContainerRuntimeClient, ImageName } from "../container-runtime";
 import { CONTAINER_STATUSES } from "../container-runtime/clients/container/types";
 import { StartedNetwork } from "../network/network";
@@ -398,17 +398,17 @@ export class GenericContainer implements TestContainer {
     this.healthCheck = healthCheck;
     this.createOpts.Healthcheck = {
       Test: healthCheck.test,
-      Interval: healthCheck.interval ? new Ms(healthCheck.interval).nanos() : 0,
-      Timeout: healthCheck.timeout ? new Ms(healthCheck.timeout).nanos() : 0,
+      Interval: healthCheck.interval ? toNanos(healthCheck.interval) : 0,
+      Timeout: healthCheck.timeout ? toNanos(healthCheck.timeout) : 0,
       Retries: healthCheck.retries ?? 0,
-      StartPeriod: healthCheck.startPeriod ? new Ms(healthCheck.startPeriod).nanos() : 0,
+      StartPeriod: healthCheck.startPeriod ? toNanos(healthCheck.startPeriod) : 0,
     };
 
     return this;
   }
 
-  public withStartupTimeout(ms: number): this {
-    this.startupTimeoutMs = ms;
+  public withStartupTimeout(startupTimeoutMs: number): this {
+    this.startupTimeoutMs = startupTimeoutMs;
     return this;
   }