Add TESTCONTAINERS_RYUK_VERBOSE setting

docs/configuration.md

@@ -32,15 +32,16 @@ Configuration of the Docker daemon:
 
 Configuration of Testcontainers and its behaviours:
 
-| Variable                              | Example                    | Description                              |
-| ------------------------------------- | -------------------------- | ---------------------------------------- |
-| TESTCONTAINERS_HOST_OVERRIDE          | tcp://docker:2375          | Docker's host on which ports are exposed |
-| TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE | /var/run/docker.sock       | Path to Docker's socket used by ryuk     |
-| TESTCONTAINERS_RYUK_PRIVILEGED        | true                       | Run ryuk as a privileged container       |
-| TESTCONTAINERS_RYUK_DISABLED          | true                       | Disable ryuk                             |
-| TESTCONTAINERS_RYUK_PORT              | 65515                      | Set ryuk host port (not recommended)     |
-| TESTCONTAINERS_SSHD_PORT              | 65515                      | Set SSHd host port (not recommended)     |
-| TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX  | mycompany.com/registry     | Set default image registry               |
-| RYUK_CONTAINER_IMAGE                  | testcontainers/ryuk:0.11.0 | Custom image for ryuk                    |
-| SSHD_CONTAINER_IMAGE                  | testcontainers/sshd:1.1.0  | Custom image for SSHd                    |
-| TESTCONTAINERS_REUSE_ENABLE           | true                       | Enable reusable containers               |
+| Variable                              | Example                    | Description                                  |
+| ------------------------------------- | -------------------------- | -------------------------------------------- |
+| TESTCONTAINERS_HOST_OVERRIDE          | tcp://docker:2375          | Docker's host on which ports are exposed     |
+| TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE | /var/run/docker.sock       | Path to Docker's socket used by ryuk         |
+| TESTCONTAINERS_RYUK_PRIVILEGED        | true                       | Run ryuk as a privileged container           |
+| TESTCONTAINERS_RYUK_DISABLED          | true                       | Disable ryuk                                 |
+| TESTCONTAINERS_RYUK_PORT              | 65515                      | Set ryuk host port (not recommended)         |
+| TESTCONTAINERS_SSHD_PORT              | 65515                      | Set SSHd host port (not recommended)         |
+| TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX  | mycompany.com/registry     | Set default image registry                   |
+| RYUK_CONTAINER_IMAGE                  | testcontainers/ryuk:0.11.0 | Custom image for ryuk                        |
+| SSHD_CONTAINER_IMAGE                  | testcontainers/sshd:1.1.0  | Custom image for SSHd                        |
+| TESTCONTAINERS_REUSE_ENABLE           | true                       | Enable reusable containers                   |
+| TESTCONTAINERS_RYUK_VERBOSE           | true                       | Sets RYUK_VERBOSE env var in ryuk container  |

packages/testcontainers/src/reaper/reaper.test.ts

@@ -0,0 +1,45 @@
+import { ContainerRuntimeClient, getContainerRuntimeClient } from "../container-runtime";
+import { FindReaperContainerFn, Reaper } from "./reaper";
+
+// FindReaperContainerFn is used in each test to intentionally 'fail' to find reaper container.
+// Failing this check will trigger re-creation of new reaper container, which is needed for testing.
+// Otherwise `getReaperFn` will always get a reference to already running reaper container,
+// which is not desired in the context of unit testing.
+
+let getReaperFn: (client: ContainerRuntimeClient, findReaperContainerFn?: FindReaperContainerFn) => Promise<Reaper>;
+
+describe("Reaper", { timeout: 120_000 }, () => {
+  beforeEach(async () => {
+    // This code will reset global variable `reaper` before each test.
+    // The variable is used to store reference to reaper container,
+    // it must be 'fresh' instance of reaper before any test is run.
+    getReaperFn = (await import("./reaper")).getReaper;
+  });
+
+  afterEach(() => {
+    vi.resetModules();
+  });
+
+  it("should create Reaper container without RYUK_VERBOSE env var by default", async () => {
+    const client = await getContainerRuntimeClient();
+    const reaper = await getReaperFn(client, async () => undefined);
+    expect(reaper.containerId).toBeTruthy(); // will fail if TESTCONTAINERS_RYUK_DISABLED=true
+    const reaperContainer = client.container.getById(reaper.containerId);
+    const reaperContainerEnv = (await reaperContainer.inspect()).Config.Env;
+    expect(reaperContainerEnv).not.toContain("RYUK_VERBOSE=true");
+    expect(reaperContainerEnv).not.toContain("RYUK_VERBOSE=false");
+  });
+
+  it("should propagate TESTCONTAINERS_RYUK_VERBOSE into Reaper container", async () => {
+    vitest.stubEnv("TESTCONTAINERS_RYUK_VERBOSE", "true");
+    try {
+      const client = await getContainerRuntimeClient();
+      const reaper = await getReaperFn(client, async () => undefined);
+      expect(reaper.containerId).toBeTruthy(); // will fail if TESTCONTAINERS_RYUK_DISABLED=true
+      const reaperContainer = client.container.getById(reaper.containerId);
+      expect((await reaperContainer.inspect()).Config.Env).toContain("RYUK_VERBOSE=true");
+    } finally {
+      vitest.unstubAllEnvs();
+    }
+  });
+});

packages/testcontainers/src/reaper/reaper.ts

@@ -3,7 +3,7 @@ import { Socket } from "net";
 import { IntervalRetry, log, RandomUuid, withFileLock } from "../common";
 import { ContainerRuntimeClient, ImageName } from "../container-runtime";
 import { GenericContainer } from "../generic-container/generic-container";
-import { LABEL_TESTCONTAINERS_SESSION_ID } from "../utils/labels";
+import { LABEL_TESTCONTAINERS_RYUK, LABEL_TESTCONTAINERS_SESSION_ID } from "../utils/labels";
 import { Wait } from "../wait-strategies/wait";
 
 export const REAPER_IMAGE = process.env["RYUK_CONTAINER_IMAGE"]
@@ -16,19 +16,28 @@ export interface Reaper {
   addSession(sessionId: string): void;
 
   addComposeProject(projectName: string): void;
+
+  get containerId(): string;
 }
 
+// see reaper.test.ts for context of this export usage.
+export type FindReaperContainerFn = (client: ContainerRuntimeClient) => Promise<ContainerInfo | undefined>;
+
 let reaper: Reaper;
 let sessionId: string;
 
-export async function getReaper(client: ContainerRuntimeClient): Promise<Reaper> {
+export async function getReaper(
+  client: ContainerRuntimeClient,
+  findReaperContainerFn?: FindReaperContainerFn
+): Promise<Reaper> {
   if (reaper) {
     return reaper;
   }
 
   reaper = await withFileLock("testcontainers-node.lock", async () => {
-    const reaperContainer = await findReaperContainer(client);
-    sessionId = reaperContainer?.Labels["org.testcontainers.session-id"] ?? new RandomUuid().nextUuid();
+    const findReaperFn = findReaperContainerFn ?? findReaperContainerDefault;
+    const reaperContainer = await findReaperFn(client);
+    sessionId = reaperContainer?.Labels[LABEL_TESTCONTAINERS_SESSION_ID] ?? new RandomUuid().nextUuid();
 
     if (process.env.TESTCONTAINERS_RYUK_DISABLED === "true") {
       return new DisabledReaper(sessionId);
@@ -43,10 +52,10 @@ export async function getReaper(client: ContainerRuntimeClient): Promise<Reaper>
   return reaper;
 }
 
-async function findReaperContainer(client: ContainerRuntimeClient): Promise<ContainerInfo | undefined> {
+async function findReaperContainerDefault(client: ContainerRuntimeClient): Promise<ContainerInfo | undefined> {
   const containers = await client.container.list();
   return containers.find(
-    (container) => container.State === "running" && container.Labels["org.testcontainers.ryuk"] === "true"
+    (container) => container.State === "running" && container.Labels[LABEL_TESTCONTAINERS_RYUK] === "true"
   );
 }
 
@@ -60,7 +69,7 @@ async function useExistingReaper(reaperContainer: ContainerInfo, sessionId: stri
 
   const socket = await connectToReaperSocket(host, reaperPort, reaperContainer.Id);
 
-  return new RyukReaper(sessionId, socket);
+  return new RyukReaper(sessionId, socket, reaperContainer.Id);
 }
 
 async function createNewReaper(sessionId: string, remoteSocketPath: string): Promise<Reaper> {
@@ -76,6 +85,8 @@ async function createNewReaper(sessionId: string, remoteSocketPath: string): Pro
     .withBindMounts([{ source: remoteSocketPath, target: "/var/run/docker.sock" }])
     .withLabels({ [LABEL_TESTCONTAINERS_SESSION_ID]: sessionId })
     .withWaitStrategy(Wait.forLogMessage(/.*Started.*/));
+  if (process.env["TESTCONTAINERS_RYUK_VERBOSE"])
+    container.withEnvironment({ RYUK_VERBOSE: process.env["TESTCONTAINERS_RYUK_VERBOSE"] });
 
   if (process.env.TESTCONTAINERS_RYUK_PRIVILEGED === "true") {
     container.withPrivilegedMode();
@@ -89,7 +100,7 @@ async function createNewReaper(sessionId: string, remoteSocketPath: string): Pro
     startedContainer.getId()
   );
 
-  return new RyukReaper(sessionId, socket);
+  return new RyukReaper(sessionId, socket, startedContainer.getId());
 }
 
 async function connectToReaperSocket(host: string, port: number, containerId: string): Promise<Socket> {
@@ -135,9 +146,14 @@ async function connectToReaperSocket(host: string, port: number, containerId: st
 class RyukReaper implements Reaper {
   constructor(
     public readonly sessionId: string,
-    private readonly socket: Socket
+    private readonly socket: Socket,
+    private readonly id: string
   ) {}
 
+  get containerId() {
+    return this.id;
+  }
+
   addComposeProject(projectName: string): void {
     this.socket.write(`label=com.docker.compose.project=${projectName}\r\n`);
   }
@@ -153,4 +169,8 @@ class DisabledReaper implements Reaper {
   addComposeProject(): void {}
 
   addSession(): void {}
+
+  get containerId() {
+    return "";
+  }
 }

packages/testcontainers/src/utils/labels.ts

@@ -6,6 +6,7 @@ export const LABEL_TESTCONTAINERS_VERSION = "org.testcontainers.version";
 export const LABEL_TESTCONTAINERS_SESSION_ID = "org.testcontainers.session-id";
 export const LABEL_TESTCONTAINERS_SSHD = "org.testcontainers.sshd";
 export const LABEL_TESTCONTAINERS_CONTAINER_HASH = "org.testcontainers.container-hash";
+export const LABEL_TESTCONTAINERS_RYUK = "org.testcontainers.ryuk";
 
 export function createLabels(): Record<string, string> {
   return {