Merge remote-tracking branch 'testcontainers/main' into reusable_containers

Author: matthiasschaub

.github/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "4.12.0"
+    ".": "4.13.0"
 }

.github/workflows/ci-core.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [4.13.0](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.12.0...testcontainers-v4.13.0) (2025-08-27)
+
+
+### Features
+
+* **azurite:** Enhance connection string generation for network and local access ([#859](https://github.com/testcontainers/testcontainers-python/issues/859)) ([b21e5e3](https://github.com/testcontainers/testcontainers-python/commit/b21e5e38075ddbd71fb4f97e843abc104dec6beb))
+* **core:** add enhanced wait strategies ([#855](https://github.com/testcontainers/testcontainers-python/issues/855)) ([60d21f8](https://github.com/testcontainers/testcontainers-python/commit/60d21f875f49f52e170b0714e8790080a6cb4c71))
+* **core:** DockerCompose: support list of env_files ([#847](https://github.com/testcontainers/testcontainers-python/issues/847)) ([fe206eb](https://github.com/testcontainers/testcontainers-python/commit/fe206eb48ee9e18623761926900bfc33a8a869a7))
+
+
+### Bug Fixes
+
+* assert-in-get_container_host_ip-before-start ([#862](https://github.com/testcontainers/testcontainers-python/issues/862)) ([fc4155e](https://github.com/testcontainers/testcontainers-python/commit/fc4155eb70509ba236fff771c2f8973667acb098))
+* **core:** improper reading of .testcontainers.properties ([#863](https://github.com/testcontainers/testcontainers-python/issues/863)) ([350f246](https://github.com/testcontainers/testcontainers-python/commit/350f246a3b6367d727046b8967a63d1c055cf324))
+* **core:** Make TC_POOLING_INTERVAL/sleep_time a float ([#839](https://github.com/testcontainers/testcontainers-python/issues/839)) ([a072f3f](https://github.com/testcontainers/testcontainers-python/commit/a072f3fad46b3b3e7c5bea6255f27b79826aaf5f))
+
 ## [4.12.0](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.11.0...testcontainers-v4.12.0) (2025-07-21)
 
 

conf.py

@@ -161,7 +161,7 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
-    "selenium": ("https://seleniumhq.github.io/selenium/docs/api/py/", None),
+    "selenium": ("https://www.selenium.dev/selenium/docs/api/py/", None),
     "typing_extensions": ("https://typing-extensions.readthedocs.io/en/latest/", None),
 }
 

core/README.rst

@@ -14,6 +14,8 @@ Testcontainers Core
 
 .. autoclass:: testcontainers.core.generic.DbContainer
 
+.. autoclass:: testcontainers.core.wait_strategies.WaitStrategy
+
 .. raw:: html
 
     <hr>

core/testcontainers/compose/compose.py

@@ -1,23 +1,23 @@
 from dataclasses import asdict, dataclass, field, fields, is_dataclass
 from functools import cached_property
 from json import loads
-from logging import warning
+from logging import getLogger, warning
 from os import PathLike
 from platform import system
 from re import split
-from subprocess import CompletedProcess
+from subprocess import CalledProcessError, CompletedProcess
 from subprocess import run as subprocess_run
 from types import TracebackType
 from typing import Any, Callable, Literal, Optional, TypeVar, Union, cast
-from urllib.error import HTTPError, URLError
-from urllib.request import urlopen
 
 from testcontainers.core.exceptions import ContainerIsNotRunning, NoSuchPortExposed
-from testcontainers.core.waiting_utils import wait_container_is_ready
+from testcontainers.core.waiting_utils import WaitStrategy
 
 _IPT = TypeVar("_IPT")
 _WARNINGS = {"DOCKER_COMPOSE_GET_CONFIG": "get_config is experimental, see testcontainers/testcontainers-python#669"}
 
+logger = getLogger(__name__)
+
 
 def _ignore_properties(cls: type[_IPT], dict_: Any) -> _IPT:
     """omits extra fields like @JsonIgnoreProperties(ignoreUnknown = true)
@@ -80,6 +80,7 @@ class ComposeContainer:
     Health: Optional[str] = None
     ExitCode: Optional[int] = None
     Publishers: list[PublishedPortModel] = field(default_factory=list)
+    _docker_compose: Optional["DockerCompose"] = field(default=None, init=False, repr=False)
 
     def __post_init__(self) -> None:
         if self.Publishers:
@@ -116,6 +117,41 @@ def _matches_protocol(prefer_ip_version: str, r: PublishedPortModel) -> bool:
         r_url = r.URL
         return (r_url is not None and ":" in r_url) is (prefer_ip_version == "IPv6")
 
+    # WaitStrategy compatibility methods
+    def get_container_host_ip(self) -> str:
+        """Get the host IP for the container."""
+        # Simplified implementation - wait strategies don't use this yet
+        return "127.0.0.1"
+
+    def get_exposed_port(self, port: int) -> int:
+        """Get the exposed port mapping for the given internal port."""
+        # Simplified implementation - wait strategies don't use this yet
+        return port
+
+    def get_logs(self) -> tuple[bytes, bytes]:
+        """Get container logs."""
+        if not self._docker_compose:
+            raise RuntimeError("DockerCompose reference not set on ComposeContainer")
+        if not self.Service:
+            raise RuntimeError("Service name not set on ComposeContainer")
+        stdout, stderr = self._docker_compose.get_logs(self.Service)
+        return stdout.encode(), stderr.encode()
+
+    def get_wrapped_container(self) -> "ComposeContainer":
+        """Get the underlying container object for compatibility."""
+        return self
+
+    def reload(self) -> None:
+        """Reload container information for compatibility with wait strategies."""
+        # ComposeContainer doesn't need explicit reloading as it's fetched fresh
+        # each time through get_container(), but we need this method for compatibility
+        pass
+
+    @property
+    def status(self) -> str:
+        """Get container status for compatibility with wait strategies."""
+        return self.State or "unknown"
+
 
 @dataclass
 class DockerCompose:
@@ -137,7 +173,7 @@ class DockerCompose:
             Wait for the services to be healthy
             (as per healthcheck definitions in the docker compose configuration)
         env_file:
-            Path to an '.env' file containing environment variables
+            Path(s) to an '.env' file containing environment variables
             to pass to docker compose.
         services:
             The list of services to use from this DockerCompose.
@@ -174,14 +210,17 @@ class DockerCompose:
     build: bool = False
     wait: bool = True
     keep_volumes: bool = False
-    env_file: Optional[str] = None
+    env_file: Optional[Union[str, list[str]]] = None
     services: Optional[list[str]] = None
     docker_command_path: Optional[str] = None
     profiles: Optional[list[str]] = None
+    _wait_strategies: Optional[dict[str, Any]] = field(default=None, init=False, repr=False)
 
     def __post_init__(self) -> None:
         if isinstance(self.compose_file_name, str):
             self.compose_file_name = [self.compose_file_name]
+        if isinstance(self.env_file, str):
+            self.env_file = [self.env_file]
 
     def __enter__(self) -> "DockerCompose":
         self.start()
@@ -210,9 +249,19 @@ def compose_command_property(self) -> list[str]:
         if self.profiles:
             docker_compose_cmd += [item for profile in self.profiles for item in ["--profile", profile]]
         if self.env_file:
-            docker_compose_cmd += ["--env-file", self.env_file]
+            for env_file in self.env_file:
+                docker_compose_cmd += ["--env-file", env_file]
         return docker_compose_cmd
 
+    def waiting_for(self, strategies: dict[str, WaitStrategy]) -> "DockerCompose":
+        """
+        Set wait strategies for specific services.
+        Args:
+            strategies: Dictionary mapping service names to wait strategies
+        """
+        self._wait_strategies = strategies
+        return self
+
     def start(self) -> None:
         """
         Starts the docker compose environment.
@@ -241,6 +290,11 @@ def start(self) -> None:
 
         self._run_command(cmd=up_cmd)
 
+        if self._wait_strategies:
+            for service, strategy in self._wait_strategies.items():
+                container = self.get_container(service_name=service)
+                strategy.wait_until_ready(container)
+
     def stop(self, down: bool = True) -> None:
         """
         Stops the docker compose environment.
@@ -317,7 +371,7 @@ def get_containers(self, include_all: bool = False) -> list[ComposeContainer]:
         result = self._run_command(cmd=cmd)
         stdout = split(r"\r?\n", result.stdout.decode("utf-8"))
 
-        containers = []
+        containers: list[ComposeContainer] = []
         # one line per service in docker 25, single array for docker 24.0.2
         for line in stdout:
             if not line:
@@ -328,6 +382,10 @@ def get_containers(self, include_all: bool = False) -> list[ComposeContainer]:
             else:
                 containers.append(_ignore_properties(ComposeContainer, data))
 
+        # Set the docker_compose reference on each container
+        for container in containers:
+            container._docker_compose = self
+
         return containers
 
     def get_container(
@@ -352,6 +410,7 @@ def get_container(
         if not matching_containers:
             raise ContainerIsNotRunning(f"{service_name} is not running in the compose context")
 
+        matching_containers[0]._docker_compose = self
         return matching_containers[0]
 
     def exec_in_container(
@@ -388,12 +447,18 @@ def _run_command(
         context: Optional[str] = None,
     ) -> CompletedProcess[bytes]:
         context = context or str(self.context)
-        return subprocess_run(
-            cmd,
-            capture_output=True,
-            check=True,
-            cwd=context,
-        )
+        try:
+            return subprocess_run(
+                cmd,
+                capture_output=True,
+                check=True,
+                cwd=context,
+            )
+        except CalledProcessError as e:
+            logger.error(f"Command '{e.cmd}' failed with exit code {e.returncode}")
+            logger.error(f"STDOUT:\n{e.stdout.decode(errors='ignore')}")
+            logger.error(f"STDERR:\n{e.stderr.decode(errors='ignore')}")
+            raise e from e
 
     def get_service_port(
         self,
@@ -452,16 +517,54 @@ def get_service_host_and_port(
         publisher = self.get_container(service_name).get_publisher(by_port=port).normalize()
         return publisher.URL, publisher.PublishedPort
 
-    @wait_container_is_ready(HTTPError, URLError)
     def wait_for(self, url: str) -> "DockerCompose":
         """
         Waits for a response from a given URL. This is typically used to block until a service in
         the environment has started and is responding. Note that it does not assert any sort of
         return code, only check that the connection was successful.
 
+        This is a convenience method that internally uses HttpWaitStrategy. For more complex
+        wait scenarios, consider using the structured wait strategies with `waiting_for()`.
+
         Args:
             url: URL from one of the services in the environment to use to wait on.
+
+        Example:
+            # Simple URL wait (legacy style)
+            compose.wait_for("http://localhost:8080") \
+            \
+            # For more complex scenarios, use structured wait strategies:
+            from testcontainers.core.waiting_utils import HttpWaitStrategy, LogMessageWaitStrategy \
+            \
+            compose.waiting_for({ \
+                "web": HttpWaitStrategy(8080).for_status_code(200), \
+                "db": LogMessageWaitStrategy("database system is ready to accept connections") \
+            })
         """
+        import time
+        from urllib.error import HTTPError, URLError
+        from urllib.request import Request, urlopen
+
+        # For simple URL waiting when we have multiple containers,
+        # we'll do a direct HTTP check instead of using the container-based strategy
+        start_time = time.time()
+        timeout = 120  # Default timeout
+
+        while True:
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"URL {url} not ready within {timeout} seconds")
+
+            try:
+                request = Request(url, method="GET")
+                with urlopen(request, timeout=1) as response:
+                    if 200 <= response.status < 400:
+                        return self
+            except (URLError, HTTPError, ConnectionResetError, ConnectionRefusedError, BrokenPipeError, OSError):
+                # Any connection error means we should keep waiting
+                pass
+
+            time.sleep(1)
+
         with urlopen(url) as response:
             response.read()
         return self

core/testcontainers/core/config.py

@@ -11,6 +11,8 @@
 
 import docker
 
+ENABLE_FLAGS = ("yes", "true", "t", "y", "1")
+
 
 class ConnectionMode(Enum):
     bridge_ip = "bridge_ip"
@@ -45,16 +47,6 @@ def get_docker_socket() -> str:
         return "/var/run/docker.sock"
 
 
-def get_bool_env(name: str) -> bool:
-    """
-    Get environment variable named `name` and convert it to bool.
-
-    Defaults to False.
-    """
-    value = environ.get(name, "")
-    return value.lower() in ("yes", "true", "t", "y", "1")
-
-
 TC_FILE = ".testcontainers.properties"
 TC_GLOBAL = Path.home() / TC_FILE
 
@@ -99,11 +91,20 @@ def read_tc_properties() -> dict[str, str]:
 
 @dataclass
 class TestcontainersConfiguration:
+    def _render_bool(self, env_name: str, prop_name: str) -> bool:
+        env_val = environ.get(env_name, None)
+        if env_val is not None:
+            return env_val.lower() in ENABLE_FLAGS
+        prop_val = self.tc_properties.get(prop_name, None)
+        if prop_val is not None:
+            return prop_val.lower() in ENABLE_FLAGS
+        return False
+
     max_tries: int = int(environ.get("TC_MAX_TRIES", "120"))
-    sleep_time: int = int(environ.get("TC_POOLING_INTERVAL", "1"))
+    sleep_time: float = float(environ.get("TC_POOLING_INTERVAL", "1"))
     ryuk_image: str = environ.get("RYUK_CONTAINER_IMAGE", "testcontainers/ryuk:0.8.1")
-    ryuk_privileged: bool = get_bool_env("TESTCONTAINERS_RYUK_PRIVILEGED")
-    ryuk_disabled: bool = get_bool_env("TESTCONTAINERS_RYUK_DISABLED")
+    _ryuk_privileged: Optional[bool] = None
+    _ryuk_disabled: Optional[bool] = None
     _ryuk_docker_socket: str = ""
     ryuk_reconnection_timeout: str = environ.get("RYUK_RECONNECTION_TIMEOUT", "10s")
     tc_properties: dict[str, str] = field(default_factory=read_tc_properties)
@@ -134,17 +135,34 @@ def tc_properties_get_tc_host(self) -> Union[str, None]:
             warning(_WARNINGS.pop("tc_properties_get_tc_host"))
         return self.tc_properties.get("tc.host")
 
-    @property
-    def tc_properties_tc_host(self) -> Union[str, None]:
-        return self.tc_properties.get("tc.host")
-
-    @property
     def tc_properties_testcontainers_reuse_enable(self) -> bool:
         enabled = self.tc_properties.get("testcontainers.reuse.enable")
         return enabled == "true"
 
     @property
-    def timeout(self) -> int:
+    def ryuk_privileged(self) -> bool:
+        if self._ryuk_privileged is not None:
+            return bool(self._ryuk_privileged)
+        self._ryuk_privileged = self._render_bool("TESTCONTAINERS_RYUK_PRIVILEGED", "ryuk.container.privileged")
+        return self._ryuk_privileged
+
+    @ryuk_privileged.setter
+    def ryuk_privileged(self, value: bool) -> None:
+        self._ryuk_privileged = value
+
+    @property
+    def ryuk_disabled(self) -> bool:
+        if self._ryuk_disabled is not None:
+            return bool(self._ryuk_disabled)
+        self._ryuk_disabled = self._render_bool("TESTCONTAINERS_RYUK_DISABLED", "ryuk.disabled")
+        return self._ryuk_disabled
+
+    @ryuk_disabled.setter
+    def ryuk_disabled(self, value: bool) -> None:
+        self._ryuk_disabled = value
+
+    @property
+    def timeout(self) -> float:
         return self.max_tries * self.sleep_time
 
     @property