feat: reusable containers

docs/index.rst

@@ -91,7 +91,6 @@ When trying to launch Testcontainers from within a Docker container, e.g., in co
 1. The container has to provide a docker client installation. Either use an image that has docker pre-installed (e.g. the `official docker images <https://hub.docker.com/_/docker>`_) or install the client from within the `Dockerfile` specification.
 2. The container has to have access to the docker daemon which can be achieved by mounting `/var/run/docker.sock` or setting the `DOCKER_HOST` environment variable as part of your `docker run` command.
 
-
 Private Docker registry
 -----------------------
 
@@ -120,6 +119,36 @@ Fetching passwords from cloud providers:
     GCP_PASSWORD = $(gcloud auth print-access-token)
     AZURE_PASSWORD = $(az acr login --name <registry-name> --expose-token --output tsv)
 
+Reusable Containers (Experimental)
+----------------------------------
+
+.. warning::
+    Reusable Containers is still an experimental feature and the behavior can change.
+    Those containers won't stop after the Python process finished.
+
+The Reusable feature keeps the containers running and next executions with the same container configuration will reuse it. To use it, start the container manually by calling `start()` method, do not call `stop()` method directly or indirectly via a `with` statement (context manager), and enable it manually through an opt-in mechanism per environment. To reuse a container, the container configuration must be the same.
+
+Containers that are set up for reuse will not be automatically removed. Thus, if they are not needed anymore, those containers must be removed manually.
+
+Please note, that containers should not be reused in a CI environment.
+
+How to use?
+^^^^^^^^^^^
+
+1. Add :code:`testcontainers.reuse.enable=true` to :code:`~/.testcontainers.properties`
+2. Disable ryuk by setting the environment variable :code:`TESTCONTAINERS_RYUK_DISABLED=true`
+3. Instantiate a container using :code:`with_reuse()` and :code:`start()`
+
+.. doctest::
+
+    >>> from testcontainers.core.container import DockerContainer
+
+    >>> container = DockerContainer("hello-world").with_reuse().start()
+    >>> first_id = container._container.id
+    >>> container = DockerContainer("hello-world").with_reuse().start()
+    >>> second_id == container._container.id
+    >>> print(first_id == second_id)
+    True
 
 Configuration
 -------------

src/testcontainers/core/config.py

@@ -134,6 +134,10 @@ def docker_auth_config(self, value: str) -> None:
     def tc_properties_get_tc_host(self) -> Union[str, None]:
         return self.tc_properties.get("tc.host")
 
+    def tc_properties_testcontainers_reuse_enable(self) -> bool:
+        enabled = self.tc_properties.get("testcontainers.reuse.enable")
+        return enabled == "true"
+
     @property
     def ryuk_privileged(self) -> bool:
         if self._ryuk_privileged is not None:

src/testcontainers/core/container.py

@@ -135,6 +135,7 @@ def __init__(
             self.with_network(network)
 
         self._network_aliases: Optional[list[str]] = None
+        self._reuse: bool = False
         if network_aliases:
             self.with_network_aliases(*network_aliases)
 
@@ -231,6 +232,10 @@ def with_kwargs(self, **kwargs: Any) -> Self:
         self._kwargs = kwargs
         return self
 
+    def with_reuse(self, reuse: bool = True) -> Self:
+        self._reuse = reuse
+        return self
+
     def maybe_emulate_amd64(self) -> Self:
         if is_arm():
             return self.with_kwargs(platform="linux/amd64")
@@ -242,7 +247,11 @@ def waiting_for(self, strategy: WaitStrategy) -> Self:
         return self
 
     def start(self) -> Self:
-        if not c.ryuk_disabled and self.image != c.ryuk_image:
+        if (
+            not c.ryuk_disabled
+            and self.image != c.ryuk_image
+            and not (self._reuse and c.tc_properties_testcontainers_reuse_enable())
+        ):
             logger.debug("Creating Ryuk container")
             Reaper.get_instance()
         logger.info("Pulling image %s", self.image)
@@ -260,7 +269,45 @@ def start(self) -> Self:
             else {}
         )
 
-        self._container = docker_client.create(
+        if self._reuse and not c.tc_properties_testcontainers_reuse_enable():
+            logging.warning(
+                "Reuse was requested (`with_reuse`) but the environment does not "
+                + "support the reuse of containers. To enable container reuse, add "
+                + "'testcontainers.reuse.enable=true' to '~/.testcontainers.properties'."
+            )
+
+        if self._reuse and c.tc_properties_testcontainers_reuse_enable():
+            # NOTE: ideally the docker client would return the full container create
+            # request which could be used to generate the hash.
+            args = [  # Docker run arguments
+                self.image,
+                self._command,
+                self.env,
+                self.ports,
+                self._name,
+                self.volumes,
+                str(tuple(sorted(self._kwargs.values()))) if self._kwargs else None,
+            ]
+            hash_ = str(zlib.crc32(pickle.dumps(args)))
+            container = docker_client.find_container_by_hash(hash_)
+            if container is not None:
+                if container.status != "running":
+                    container.start()
+                    logger.info("Existing container started: %s", container.id)
+                self._container = container
+                logger.info("Container is already running: %s", container.id)
+            else:
+                self._start(network_kwargs, hash_)
+        else:
+            self._start(network_kwargs)
+
+        if self._network and self._container:
+            self._network.connect(self._container.id, self._network_aliases)
+        return self
+
+    def _start(self, network_kwargs: dict[Any, Any], hash_: Optional[str] = None) -> Self:
+        docker_client = self.get_docker_client()
+        self._container = docker_client.run(
             self.image,
             command=self._command,
             environment=self.env,
@@ -269,6 +316,7 @@ def start(self) -> Self:
             # dict is invariant: expanding fields explicitly lets mypy verify each value type.
             volumes={host: {"bind": mount["bind"], "mode": mount["mode"]} for host, mount in self.volumes.items()},
             tmpfs=self.tmpfs,
+            labels={"hash": hash_} if hash_ is not None else {},
             **{**network_kwargs, **self._kwargs},
         )
 

src/testcontainers/core/docker_client.py

@@ -479,6 +479,12 @@ def get_container_inspect_info(self, container_id: str) -> ContainerInspectInfo:
         container = self.client.containers.get(container_id)
         return ContainerInspectInfo.from_dict(container.attrs)
 
+    def find_container_by_hash(self, hash_: str) -> Union[Container, None]:
+        for container in self.client.containers.list(all=True):
+            if container.labels.get("hash", None) == hash_:
+                return container
+        return None
+
 
 def get_docker_host() -> Optional[str]:
     host = c.tc_properties_get_tc_host() or os.getenv("DOCKER_HOST") or _get_docker_host_from_context()

tests/core/test_reusable_containers.py

@@ -0,0 +1,135 @@
+from time import sleep
+
+from docker.models.containers import Container
+
+from testcontainers.core.config import testcontainers_config
+from testcontainers.core.container import DockerContainer
+from testcontainers.core.docker_client import DockerClient
+from testcontainers.core.waiting_utils import wait_for_logs
+from testcontainers.core.container import Reaper
+
+
+def test_docker_container_reuse_default():
+    # Make sure Ryuk cleanup is not active from previous test runs
+    Reaper.delete_instance()
+
+    container = DockerContainer("hello-world").start()
+    wait_for_logs(container, "Hello from Docker!")
+
+    assert container._reuse == False
+    assert testcontainers_config.tc_properties_testcontainers_reuse_enable() == False
+    assert Reaper._socket is not None
+
+    container.stop()
+    containers = DockerClient().client.containers.list(all=True)
+    assert container._container is not None
+    assert container._container.id not in [container.id for container in containers]
+
+
+def test_docker_container_with_reuse_reuse_disabled(caplog):
+    # Make sure Ryuk cleanup is not active from previous test runs
+    Reaper.delete_instance()
+
+    container = DockerContainer("hello-world").with_reuse().start()
+    wait_for_logs(container, "Hello from Docker!")
+
+    assert container._reuse == True
+    assert testcontainers_config.tc_properties_testcontainers_reuse_enable() == False
+    assert ("Reuse was requested (`with_reuse`) but the environment does not support the ") in caplog.text
+    assert Reaper._socket is not None
+
+    container.stop()
+    containers = DockerClient().client.containers.list(all=True)
+    assert container._container is not None
+    assert container._container.id not in [container.id for container in containers]
+
+
+def test_docker_container_without_reuse_reuse_enabled(monkeypatch):
+    # Make sure Ryuk cleanup is not active from previous test runs
+    Reaper.delete_instance()
+
+    tc_properties_mock = testcontainers_config.tc_properties | {"testcontainers.reuse.enable": "true"}
+    monkeypatch.setattr(testcontainers_config, "tc_properties", tc_properties_mock)
+
+    container = DockerContainer("hello-world").start()
+    wait_for_logs(container, "Hello from Docker!")
+
+    assert container._reuse == False
+    assert testcontainers_config.tc_properties_testcontainers_reuse_enable() == True
+    assert Reaper._socket is not None
+
+    container.stop()
+    containers = DockerClient().client.containers.list(all=True)
+    assert container._container is not None
+    assert container._container.id not in [container.id for container in containers]
+
+
+def test_docker_container_with_reuse_reuse_enabled(monkeypatch):
+    # Make sure Ryuk cleanup is not active from previous test runs
+    Reaper.delete_instance()
+
+    tc_properties_mock = testcontainers_config.tc_properties | {"testcontainers.reuse.enable": "true"}
+    monkeypatch.setattr(testcontainers_config, "tc_properties", tc_properties_mock)
+
+    container = DockerContainer("hello-world").with_reuse().start()
+    wait_for_logs(container, "Hello from Docker!")
+
+    assert Reaper._socket is None
+
+    containers = DockerClient().client.containers.list(all=True)
+    assert container._container is not None
+    assert container._container.id in [container.id for container in containers]
+
+    # Cleanup after keeping container alive (with_reuse)
+    container.stop()
+
+
+def test_docker_container_with_reuse_reuse_enabled_same_id(monkeypatch):
+    # Make sure Ryuk cleanup is not active from previous test runs
+    Reaper.delete_instance()
+
+    tc_properties_mock = testcontainers_config.tc_properties | {"testcontainers.reuse.enable": "true"}
+    monkeypatch.setattr(testcontainers_config, "tc_properties", tc_properties_mock)
+
+    container_1 = DockerContainer("hello-world").with_reuse().start()
+    assert container_1._container is not None
+    id_1 = container_1._container.id
+    container_2 = DockerContainer("hello-world").with_reuse().start()
+    assert container_2._container is not None
+    id_2 = container_2._container.id
+    assert Reaper._socket is None
+    assert id_1 == id_2
+    # Cleanup after keeping container alive (with_reuse)
+    container_1.stop()
+    # container_2.stop() is not needed since it is the same as container_1
+
+
+def test_docker_container_labels_hash_default():
+    # w/out reuse
+    with DockerContainer("hello-world") as container:
+        assert container._container is not None
+        assert "hash" not in container._container.labels.keys()
+
+
+def test_docker_container_labels_hash(monkeypatch):
+    tc_properties_mock = testcontainers_config.tc_properties | {"testcontainers.reuse.enable": "true"}
+    monkeypatch.setattr(testcontainers_config, "tc_properties", tc_properties_mock)
+    expected_hash = "380705419"
+    with DockerContainer("hello-world").with_reuse() as container:
+        assert container._container is not None
+        assert container._container.labels["hash"] == expected_hash
+
+
+def test_docker_client_find_container_by_hash_not_existing():
+    with DockerContainer("hello-world"):
+        assert DockerClient().find_container_by_hash("foo") == None
+
+
+def test_docker_client_find_container_by_hash_existing(monkeypatch):
+    tc_properties_mock = testcontainers_config.tc_properties | {"testcontainers.reuse.enable": "true"}
+    monkeypatch.setattr(testcontainers_config, "tc_properties", tc_properties_mock)
+    with DockerContainer("hello-world").with_reuse() as container:
+        assert container._container is not None
+        hash_ = container._container.labels["hash"]
+        found_container = DockerClient().find_container_by_hash(hash_)
+        assert isinstance(found_container, Container)