Enable/disable container reuse with an environment variable

This commit introduces `TESTCONTAINERS_REUSE_ENABLE` environment variable to enable or disable the container re-use feature globally.
If `TESTCONTAINERS_REUSE_ENABLE` is not declared, the feature stays enabled by default to maintain backward compatibility.

Author: juliette

docs/configuration.md

@@ -43,3 +43,4 @@ Configuration of Testcontainers and its behaviours:
 | TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX  | mycompany.com/registry    | Set default image registry               |
 | RYUK_CONTAINER_IMAGE                  | testcontainers/ryuk:0.5.1 | Custom image for ryuk                    |
 | SSHD_CONTAINER_IMAGE                  | testcontainers/sshd:1.1.0 | Custom image for SSHd                    |
+| TESTCONTAINERS_REUSE_ENABLE           | true                      | Enable reusable containers               |

docs/features/containers.md

@@ -365,6 +365,9 @@ const container2 = await new GenericContainer("alpine")
 expect(container1.getId()).toBe(container2.getId());
 ```
 
+Container re-use can be enabled or disabled globally by setting the `TESTCONTAINERS_REUSE_ENABLE` environment variable to `true` or `false`.
+If this environment variable is not declared, the feature is enabled by default.
+
 ## Creating a custom container
 
 You can create your own Generic Container as follows:

packages/testcontainers/src/generic-container/generic-container-reuse.test.ts

@@ -4,6 +4,10 @@ import { checkContainerIsHealthy } from "../utils/test-helper";
 describe("GenericContainer reuse", () => {
   jest.setTimeout(180_000);
 
+  afterEach(() => {
+    process.env.TESTCONTAINERS_REUSE_ENABLE = undefined;
+  });
+
   it("should not reuse the container by default", async () => {
     const container = await new GenericContainer("cristianrgreco/testcontainer:1.1.14")
       .withName("there_can_only_be_one")
@@ -63,26 +67,54 @@ describe("GenericContainer reuse", () => {
     }
   });
 
-  it("should reuse the container", async () => {
-    const container1 = await new GenericContainer("cristianrgreco/testcontainer:1.1.14")
-      .withName("there_can_only_be_one")
-      .withExposedPorts(8080)
-      .withReuse()
-      .start();
-    await checkContainerIsHealthy(container1);
+  it("should not reuse the container when TESTCONTAINERS_REUSE_ENABLE is set to false", async () => {
+    process.env.TESTCONTAINERS_REUSE_ENABLE = "false";
 
-    const container2 = await new GenericContainer("cristianrgreco/testcontainer:1.1.14")
+    const container = await new GenericContainer("cristianrgreco/testcontainer:1.1.14")
       .withName("there_can_only_be_one")
       .withExposedPorts(8080)
       .withReuse()
       .start();
-    await checkContainerIsHealthy(container2);
-
-    expect(container1.getId()).toBe(container2.getId());
+    await checkContainerIsHealthy(container);
 
-    await container1.stop();
+    try {
+      await expect(() =>
+        new GenericContainer("cristianrgreco/testcontainer:1.1.14")
+          .withName("there_can_only_be_one")
+          .withExposedPorts(8080)
+          .withReuse()
+          .start()
+      ).rejects.toThrowError();
+    } finally {
+      await container.stop();
+    }
   });
 
+  it.each(["true", undefined])(
+    "should reuse the container when TESTCONTAINERS_REUSE_ENABLE is set to %s",
+    async (reuseEnable: string | undefined) => {
+      process.env.TESTCONTAINERS_REUSE_ENABLE = reuseEnable;
+
+      const container1 = await new GenericContainer("cristianrgreco/testcontainer:1.1.14")
+        .withName("there_can_only_be_one")
+        .withExposedPorts(8080)
+        .withReuse()
+        .start();
+      await checkContainerIsHealthy(container1);
+
+      const container2 = await new GenericContainer("cristianrgreco/testcontainer:1.1.14")
+        .withName("there_can_only_be_one")
+        .withExposedPorts(8080)
+        .withReuse()
+        .start();
+      await checkContainerIsHealthy(container2);
+
+      expect(container1.getId()).toBe(container2.getId());
+
+      await container1.stop();
+    }
+  );
+
   it("should create a new container when an existing reusable container has stopped and is removed", async () => {
     const container1 = await new GenericContainer("cristianrgreco/testcontainer:1.1.14")
       .withName("there_can_only_be_one")

packages/testcontainers/src/generic-container/generic-container.ts

@@ -100,7 +100,7 @@ export class GenericContainer implements TestContainer {
 
     this.createOpts.Labels = { ...createLabels(), ...this.createOpts.Labels };
 
-    if (this.reuse) {
+    if (process.env.TESTCONTAINERS_REUSE_ENABLE !== "false" && this.reuse) {
       return this.reuseOrStartContainer(client);
     }