Implement withAutoRemove #905 (#939)

Author: digital88

docs/features/containers.md

@@ -348,6 +348,26 @@ const container = await new GenericContainer("alpine").start();
 await container.stop({ remove: false });
 ```
 
+Alternatively, you can disable automatic removal while configuring the container:
+
+```javascript
+const container = await new GenericContainer("alpine")
+  .withAutoRemove(false)
+  .start();
+
+await container.stop()
+```
+
+The value specified to `.withAutoRemove()` can be overridden by `.stop()`:
+
+```javascript
+const container = await new GenericContainer("alpine")
+  .withAutoRemove(false)
+  .start();
+
+await container.stop({ remove: true }) // The container is stopped *AND* removed
+```
+
 Volumes created by the container are removed when stopped. This is configurable:
 
 ```javascript

packages/testcontainers/src/docker-compose-environment/docker-compose-environment.ts

@@ -168,7 +168,8 @@ export class DockerComposeEnvironment {
             inspectResult,
             boundPorts,
             containerName,
-            waitStrategy
+            waitStrategy,
+            true
           );
         })
       )

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

@@ -518,6 +518,34 @@ describe("GenericContainer", { timeout: 180_000 }, () => {
     expect(await getRunningContainerNames()).not.toContain(container.getName());
   });
 
+  it("should stop but not remove the container", async () => {
+    const container = await new GenericContainer("cristianrgreco/testcontainer:1.1.14")
+      .withName(`container-${new RandomUuid().nextUuid()}`)
+      .withAutoRemove(false)
+      .start();
+
+    const stopped = await container.stop();
+    const dockerode = (await getContainerRuntimeClient()).container.dockerode;
+    expect(stopped.getId()).toBeTruthy();
+    const lowerLevelContainer = dockerode.getContainer(stopped.getId());
+    expect((await lowerLevelContainer.inspect()).State.Status).toEqual("exited");
+  });
+
+  it("should stop and override .withAutoRemove", async () => {
+    const container = await new GenericContainer("cristianrgreco/testcontainer:1.1.14")
+      .withName(`container-${new RandomUuid().nextUuid()}`)
+      .withAutoRemove(false)
+      .start();
+
+    await container.stop({ remove: true });
+
+    const stopped = await container.stop();
+    const dockerode = (await getContainerRuntimeClient()).container.dockerode;
+    expect(stopped.getId()).toBeTruthy();
+    const lowerLevelContainer = dockerode.getContainer(stopped.getId());
+    await expect(lowerLevelContainer.inspect()).rejects.toThrow(/404/); // Error: (HTTP code 404) no such container
+  });
+
   it("should build a target stage", async () => {
     const context = path.resolve(fixtures, "docker-multi-stage");
     const firstContainer = await GenericContainer.fromDockerfile(context).withTarget("first").build();

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

@@ -51,6 +51,7 @@ export class GenericContainer implements TestContainer {
   protected environment: Record<string, string> = {};
   protected exposedPorts: PortWithOptionalBinding[] = [];
   protected reuse = false;
+  protected autoRemove = true;
   protected networkMode?: string;
   protected networkAliases: string[] = [];
   protected pullPolicy: ImagePullPolicy = PullPolicy.defaultPolicy();
@@ -160,7 +161,8 @@ export class GenericContainer implements TestContainer {
       inspectResult,
       boundPorts,
       inspectResult.Name,
-      this.waitStrategy
+      this.waitStrategy,
+      this.autoRemove
     );
   }
 
@@ -228,7 +230,8 @@ export class GenericContainer implements TestContainer {
       inspectResult,
       boundPorts,
       inspectResult.Name,
-      this.waitStrategy
+      this.waitStrategy,
+      this.autoRemove
     );
 
     if (this.containerStarted) {
@@ -439,6 +442,11 @@ export class GenericContainer implements TestContainer {
     return this;
   }
 
+  public withAutoRemove(autoRemove: boolean): this {
+    this.autoRemove = autoRemove;
+    return this;
+  }
+
   public withPullPolicy(pullPolicy: ImagePullPolicy): this {
     this.pullPolicy = pullPolicy;
     return this;

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

@@ -24,7 +24,8 @@ export class StartedGenericContainer implements StartedTestContainer {
     private inspectResult: ContainerInspectInfo,
     private boundPorts: BoundPorts,
     private readonly name: string,
-    private readonly waitStrategy: WaitStrategy
+    private readonly waitStrategy: WaitStrategy,
+    private readonly autoRemove: boolean
   ) {}
 
   protected containerIsStopping?(): Promise<void>;
@@ -105,7 +106,7 @@ export class StartedGenericContainer implements StartedTestContainer {
       await this.containerIsStopping();
     }
 
-    const resolvedOptions: StopOptions = { remove: true, timeout: 0, removeVolumes: true, ...options };
+    const resolvedOptions: StopOptions = { remove: this.autoRemove, timeout: 0, removeVolumes: true, ...options };
     await client.container.stop(this.container, { timeout: resolvedOptions.timeout });
     if (resolvedOptions.remove) {
       await client.container.remove(this.container, { removeVolumes: resolvedOptions.removeVolumes });

packages/testcontainers/src/test-container.ts

@@ -42,6 +42,7 @@ export interface TestContainer {
   withUser(user: string): this;
   withPullPolicy(pullPolicy: ImagePullPolicy): this;
   withReuse(): this;
+  withAutoRemove(autoRemove: boolean): this;
   withCopyFilesToContainer(filesToCopy: FileToCopy[]): this;
   withCopyDirectoriesToContainer(directoriesToCopy: DirectoryToCopy[]): this;
   withCopyContentToContainer(contentsToCopy: ContentToCopy[]): this;

packages/testcontainers/src/utils/test-helper.ts

@@ -44,6 +44,16 @@ export const getRunningContainerNames = async (): Promise<string[]> => {
     .map((containerName) => containerName.replace("/", ""));
 };
 
+export const getStoppedContainerNames = async (): Promise<string[]> => {
+  const dockerode = (await getContainerRuntimeClient()).container.dockerode;
+  const containers = await dockerode.listContainers({ all: true });
+  return containers
+    .filter((container) => container.State === "exited")
+    .map((container) => container.Names)
+    .reduce((result, containerNames) => [...result, ...containerNames], [])
+    .map((containerName) => containerName.replace("/", ""));
+};
+
 export const getContainerIds = async (): Promise<string[]> => {
   const dockerode = (await getContainerRuntimeClient()).container.dockerode;
   const containers = await dockerode.listContainers({ all: true });