Merge branch 'main' into fix_test_core_registry

Author: Tranquility2

.github/workflows/ci-core.yml

@@ -1,4 +1,4 @@
-# Contrinuous Integration for the core package
+# Continuous Integration for the core package
 
 name: core
 
@@ -25,6 +25,8 @@ jobs:
         run: poetry install --all-extras
       - name: Run twine check
         run: poetry build && poetry run twine check dist/*.tar.gz
+      - name: Set up Docker
+        uses: docker/setup-docker-action@v4
       - name: Run tests
         run: make core/tests
       - name: Rename coverage file

core/README.rst

@@ -18,6 +18,8 @@ Testcontainers Core
 
 .. autoclass:: testcontainers.core.generic.DbContainer
 
+.. autoclass:: testcontainers.core.network.Network
+
 .. raw:: html
 
     <hr>

core/testcontainers/core/container.py

@@ -28,6 +28,20 @@ class DockerContainer:
     """
     Basic container object to spin up Docker instances.
 
+    Args:
+        image: The name of the image to start.
+        docker_client_kw: Dictionary with arguments that will be passed to the
+            docker.DockerClient init.
+        command: Optional execution command for the container.
+        name: Optional name for the container.
+        ports: Ports to be exposed by the container. The port number will be
+            automatically assigned on the host, use
+            :code:`get_exposed_port(PORT)` method to get the port number on the host.
+        volumes: Volumes to mount into the container. Each entry should be a tuple with
+            three values: host path, container path and. mode (default 'ro').
+        network: Optional network to connect the container to.
+        network_aliases: Optional list of aliases for the container in the network.
+
     .. doctest::
 
         >>> from testcontainers.core.container import DockerContainer
@@ -41,18 +55,40 @@ def __init__(
         self,
         image: str,
         docker_client_kw: Optional[dict] = None,
+        command: Optional[str] = None,
+        env: Optional[dict[str, str]] = None,
+        name: Optional[str] = None,
+        ports: Optional[list[int]] = None,
+        volumes: Optional[list[tuple[str, str, str]]] = None,
+        network: Optional[Network] = None,
+        network_aliases: Optional[list[str]] = None,
         **kwargs,
     ) -> None:
-        self.env = {}
+        self.env = env or {}
+
         self.ports = {}
+        if ports:
+            self.with_exposed_ports(*ports)
+
         self.volumes = {}
+        if volumes:
+            for vol in volumes:
+                self.with_volume_mapping(*vol)
+
         self.image = image
         self._docker = DockerClient(**(docker_client_kw or {}))
         self._container = None
-        self._command = None
-        self._name = None
+        self._command = command
+        self._name = name
+
         self._network: Optional[Network] = None
+        if network is not None:
+            self.with_network(network)
+
         self._network_aliases: Optional[list[str]] = None
+        if network_aliases:
+            self.with_network_aliases(*network_aliases)
+
         self._kwargs = kwargs
 
     def with_env(self, key: str, value: str) -> Self:

core/testcontainers/core/docker_client.py

@@ -151,7 +151,7 @@ def find_host_network(self) -> Optional[str]:
                         except ipaddress.AddressValueError:
                             continue
                         if docker_host in subnet:
-                            return cast(str, network.name)
+                            return cast("str", network.name)
         except (ipaddress.AddressValueError, OSError):
             pass
         return None
@@ -163,7 +163,7 @@ def port(self, container_id: str, port: int) -> str:
         port_mappings = self.client.api.port(container_id, port)
         if not port_mappings:
             raise ConnectionError(f"Port mapping for container {container_id} and port {port} is not available")
-        return cast(str, port_mappings[0]["HostPort"])
+        return cast("str", port_mappings[0]["HostPort"])
 
     def get_container(self, container_id: str) -> dict[str, Any]:
         """
@@ -172,7 +172,7 @@ def get_container(self, container_id: str) -> dict[str, Any]:
         containers = self.client.api.containers(filters={"id": container_id})
         if not containers:
             raise RuntimeError(f"Could not get container with id {container_id}")
-        return cast(dict[str, Any], containers[0])
+        return cast("dict[str, Any]", containers[0])
 
     def bridge_ip(self, container_id: str) -> str:
         """
@@ -241,7 +241,7 @@ def host(self) -> str:
             hostname = url.hostname
             if not hostname or (hostname == "localnpipe" and utils.is_windows()):
                 return "localhost"
-            return cast(str, url.hostname)
+            return cast("str", url.hostname)
         if utils.inside_container() and ("unix" in url.scheme or "npipe" in url.scheme):
             ip_address = utils.default_gateway_ip()
             if ip_address:
@@ -257,7 +257,7 @@ def login(self, auth_config: DockerAuthInfo) -> None:
 
     def client_networks_create(self, name: str, param: dict[str, Any]) -> dict[str, Any]:
         labels = create_labels("", param.get("labels"))
-        return cast(dict[str, Any], self.client.networks.create(name, **{**param, "labels": labels}))
+        return cast("dict[str, Any]", self.client.networks.create(name, **{**param, "labels": labels}))
 
 
 def get_docker_host() -> Optional[str]:

core/tests/compose_fixtures/port_multiple/compose.yaml

@@ -6,6 +6,7 @@ services:
       - '81'
       - '82'
       - target: 80
+        published: "5000-5999"
         host_ip: 127.0.0.1
         protocol: tcp
     command:
@@ -18,6 +19,7 @@ services:
     init: true
     ports:
       - target: 80
+        published: "5000-5999"
         host_ip: 127.0.0.1
         protocol: tcp
     command:

core/tests/test_container.py

@@ -75,3 +75,24 @@ def test_get_exposed_port_original(container: DockerContainer, monkeypatch: pyte
     monkeypatch.setattr(client, "get_connection_mode", lambda: ConnectionMode.bridge_ip)
 
     assert container.get_exposed_port(8080) == 8080
+
+
+@pytest.mark.parametrize(
+    "init_attr,init_value,class_attr,stored_value",
+    [
+        ("command", "ps", "_command", "ps"),
+        ("env", {"e1": "v1"}, "env", {"e1": "v1"}),
+        ("name", "foo-bar", "_name", "foo-bar"),
+        ("ports", [22, 80], "ports", {22: None, 80: None}),
+        (
+            "volumes",
+            [("/tmp", "/tmp2", "ro")],
+            "volumes",
+            {"/tmp": {"bind": "/tmp2", "mode": "ro"}},
+        ),
+    ],
+)
+def test_attribute(init_attr, init_value, class_attr, stored_value):
+    """Test that the attributes set through the __init__ function are properly stored."""
+    with DockerContainer("ubuntu", **{init_attr: init_value}) as container:
+        assert getattr(container, class_attr) == stored_value

core/tests/test_core_registry.py

@@ -18,8 +18,13 @@
 from testcontainers.core.waiting_utils import wait_for_logs
 
 from testcontainers.registry import DockerRegistryContainer
+from testcontainers.core.utils import is_mac
 
 
+@pytest.mark.skipif(
+    is_mac(),
+    reason="Docker Desktop on macOS does not support insecure private registries without daemon reconfiguration",
+)
 def test_missing_on_private_registry(monkeypatch):
     username = "user"
     password = "pass"
@@ -41,6 +46,10 @@ def test_missing_on_private_registry(monkeypatch):
                 wait_for_logs(test_container, "Hello from Docker!")
 
 
+@pytest.mark.skipif(
+    is_mac(),
+    reason="Docker Desktop on macOS does not support local insecure registries over HTTP without modifying daemon settings",
+)
 @pytest.mark.parametrize(
     "image,tag,username,password,expected_output",
     [

core/tests/test_docker_in_docker.py

@@ -15,6 +15,7 @@
 from testcontainers.core.container import DockerContainer
 from testcontainers.core.docker_client import DockerClient, LOGGER
 from testcontainers.core.utils import inside_container
+from testcontainers.core.utils import is_mac
 from testcontainers.core.waiting_utils import wait_for_logs
 
 
@@ -36,6 +37,7 @@ def _wait_for_dind_return_ip(client, dind):
     return docker_host_ip
 
 
+@pytest.mark.skipif(is_mac(), reason="Docker socket forwarding (socat) is unsupported on Docker Desktop for macOS")
 def test_wait_for_logs_docker_in_docker():
     # real dind isn't possible (AFAIK) in CI
     # forwarding the socket to a container port is at least somewhat the same
@@ -64,6 +66,9 @@ def test_wait_for_logs_docker_in_docker():
     not_really_dind.remove()
 
 
+@pytest.mark.skipif(
+    is_mac(), reason="Bridge networking and Docker socket forwarding are not supported on Docker Desktop for macOS"
+)
 def test_dind_inherits_network():
     client = DockerClient()
     try:
@@ -158,6 +163,9 @@ def test_find_host_network_in_dood() -> None:
     assert DockerClient().find_host_network() == os.environ[EXPECTED_NETWORK_VAR]
 
 
+@pytest.mark.skipif(
+    is_mac(), reason="Docker socket mounting and container networking do not work reliably on Docker Desktop for macOS"
+)
 @pytest.mark.skipif(not Path(tcc.ryuk_docker_socket).exists(), reason="No docker socket available")
 def test_dood(python_testcontainer_image: str) -> None:
     """

core/tests/test_ryuk.py

@@ -8,9 +8,14 @@
 from testcontainers.core.config import testcontainers_config
 from testcontainers.core.container import Reaper
 from testcontainers.core.container import DockerContainer
+from testcontainers.core.utils import is_mac
 from testcontainers.core.waiting_utils import wait_for_logs
 
 
+@pytest.mark.skipif(
+    is_mac(),
+    reason="Ryuk container reaping is unreliable on Docker Desktop for macOS due to VM-based container lifecycle handling",
+)
 @pytest.mark.inside_docker_check
 def test_wait_for_reaper(monkeypatch: MonkeyPatch):
     Reaper.delete_instance()
@@ -41,6 +46,9 @@ def test_wait_for_reaper(monkeypatch: MonkeyPatch):
     Reaper.delete_instance()
 
 
+@pytest.mark.skipif(
+    is_mac(), reason="Ryuk disabling behavior is unreliable on Docker Desktop for macOS due to Docker socket emulation"
+)
 @pytest.mark.inside_docker_check
 def test_container_without_ryuk(monkeypatch: MonkeyPatch):
     Reaper.delete_instance()

core/tests/test_utils.py

@@ -33,6 +33,7 @@ def test_is_windows(monkeypatch: MonkeyPatch) -> None:
 
 
 def test_is_arm(monkeypatch: MonkeyPatch) -> None:
+    monkeypatch.setattr("platform.machine", lambda: "x86_64")
     assert not utils.is_arm()
     monkeypatch.setattr("platform.machine", lambda: "arm64")
     assert utils.is_arm()