recover compose container

Author: carlosemart

compose/README.rst

@@ -0,0 +1 @@
+.. autoclass:: testcontainers.compose.DockerCompose

compose/setup.py

@@ -0,0 +1,17 @@
+from setuptools import setup, find_namespace_packages
+
+description = "Docker Compose component of testcontainers-python."
+
+setup(
+    name="testcontainers-compose",
+    version="0.0.1rc1",
+    packages=find_namespace_packages(),
+    description=description,
+    long_description=description,
+    long_description_content_type="text/x-rst",
+    url="https://github.com/testcontainers/testcontainers-python",
+    install_requires=[
+        "testcontainers-core",
+    ],
+    python_requires=">=3.7",
+)

compose/testcontainers/compose/__init__.py

@@ -0,0 +1,206 @@
+import subprocess
+from typing import Iterable, List, Optional, Tuple, Union
+
+import requests
+
+from testcontainers.core.exceptions import NoSuchPortExposed
+from testcontainers.core.waiting_utils import wait_container_is_ready
+
+
+class DockerCompose:
+    """
+    Manage docker compose environments.
+
+    Args:
+        filepath: Relative directory containing the docker compose configuration file.
+        compose_file_name: File name of the docker compose configuration file.
+        pull: Pull images before launching environment.
+        build: Build images referenced in the configuration file.
+        env_file: Path to an env file containing environment variables to pass to docker compose.
+        services: List of services to start.
+
+    Example:
+
+        This example spins up chrome and firefox containers using docker compose.
+
+        .. doctest::
+
+            >>> from testcontainers.compose import DockerCompose
+
+            >>> compose = DockerCompose("compose/tests", compose_file_name="docker-compose-4.yml",
+            ...                         pull=True)
+            >>> with compose:
+            ...     stdout, stderr = compose.get_logs()
+            >>> b"Hello from Docker!" in stdout
+            True
+
+        .. code-block:: yaml
+
+            services:
+              hello-world:
+                image: "hello-world"
+    """
+
+    def __init__(
+        self,
+        filepath: str,
+        compose_file_name: Union[str, Iterable] = "docker-compose.yml",
+        pull: bool = False,
+        build: bool = False,
+        env_file: Optional[str] = None,
+        services: Optional[List[str]] = None,
+    ) -> None:
+        self.filepath = filepath
+        self.compose_file_names = (
+            [compose_file_name]
+            if isinstance(compose_file_name, str)
+            else list(compose_file_name)
+        )
+        self.pull = pull
+        self.build = build
+        self.env_file = env_file
+        self.services = services
+
+    def __enter__(self) -> "DockerCompose":
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.stop()
+
+    def docker_compose_command(self) -> List[str]:
+        """
+        Returns command parts used for the docker compose commands
+
+        Returns:
+            cmd: Docker compose command parts.
+        """
+        docker_compose_cmd = ["docker-compose"]
+        for file in self.compose_file_names:
+            docker_compose_cmd += ["-f", file]
+        if self.env_file:
+            docker_compose_cmd += ["--env-file", self.env_file]
+        return docker_compose_cmd
+
+    def start(self) -> None:
+        """
+        Starts the docker compose environment.
+        """
+        if self.pull:
+            pull_cmd = self.docker_compose_command() + ["pull"]
+            self._call_command(cmd=pull_cmd)
+
+        up_cmd = self.docker_compose_command() + ["up", "-d"]
+        if self.build:
+            up_cmd.append("--build")
+        if self.services:
+            up_cmd.extend(self.services)
+
+        self._call_command(cmd=up_cmd)
+
+    def stop(self) -> None:
+        """
+        Stops the docker compose environment.
+        """
+        down_cmd = self.docker_compose_command() + ["down", "-v"]
+        self._call_command(cmd=down_cmd)
+
+    def get_logs(self) -> Tuple[bytes, bytes]:
+        """
+        Returns all log output from stdout and stderr
+
+        Returns:
+            stdout: Standard output stream.
+            stderr: Standard error stream.
+        """
+        logs_cmd = self.docker_compose_command() + ["logs"]
+        result = subprocess.run(
+            logs_cmd,
+            cwd=self.filepath,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        return result.stdout, result.stderr
+
+    def exec_in_container(
+        self, service_name: str, command: List[str]
+    ) -> Tuple[str, str, int]:
+        """
+        Executes a command in the container of one of the services.
+
+        Args:
+            service_name: Name of the docker compose service to run the command in.
+        command: Command to execute.
+
+        Returns:
+            stdout: Standard output stream.
+            stderr: Standard error stream.
+        """
+        exec_cmd = (
+            self.docker_compose_command() + ["exec", "-T", service_name] + command
+        )
+        result = subprocess.run(
+            exec_cmd,
+            cwd=self.filepath,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        return (
+            result.stdout.decode("utf-8"),
+            result.stderr.decode("utf-8"),
+            result.returncode,
+        )
+
+    def get_service_port(self, service_name: str, port: int) -> int:
+        """
+        Returns the mapped port for one of the services.
+
+        Args:
+            service_name: Name of the docker compose service.
+            port: Internal port to get the mapping for.
+
+        Returns:
+            mapped_port: Mapped port on the host.
+        """
+        return self._get_service_info(service_name, port)[1]
+
+    def get_service_host(self, service_name: str, port: int) -> str:
+        """
+        Returns the host for one of the services.
+
+        Args:
+            service_name: Name of the docker compose service.
+            port: Internal port to get the mapping for.
+
+        Returns:
+            host: Hostname for the service.
+        """
+        return self._get_service_info(service_name, port)[0]
+
+    def _get_service_info(self, service: str, port: int) -> List[str]:
+        port_cmd = self.docker_compose_command() + ["port", service, str(port)]
+        output = subprocess.check_output(port_cmd, cwd=self.filepath).decode("utf-8")
+        result = str(output).rstrip().split(":")
+        if len(result) != 2 or not all(result):
+            raise NoSuchPortExposed(f"port {port} is not exposed for service {service}")
+        return result
+
+    def _call_command(
+        self, cmd: Union[str, List[str]], filepath: Optional[str] = None
+    ) -> None:
+        if filepath is None:
+            filepath = self.filepath
+        subprocess.call(cmd, cwd=filepath)
+
+    @wait_container_is_ready(requests.exceptions.ConnectionError)
+    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.
+
+        Args:
+            url: URL from one of the services in the environment to use to wait on.
+        """
+        requests.get(url)
+        return self

compose/tests/.env.test

@@ -0,0 +1 @@
+TAG_TEST_ASSERT_KEY="test_has_passed"

compose/tests/docker-compose-2.yml

@@ -0,0 +1,6 @@
+services:
+  alpine:
+    image: alpine
+    command: sleep 3600
+    ports:
+      - "3306:3306"

compose/tests/docker-compose-3.yml

@@ -0,0 +1,8 @@
+services:
+  alpine:
+    image: alpine
+    command: sleep 3600
+    ports:
+      - "3306:3306"
+    environment:
+      TEST_ASSERT_KEY: ${TAG_TEST_ASSERT_KEY}

compose/tests/docker-compose-4.yml

@@ -0,0 +1,3 @@
+services:
+  hello-world:
+    image: "hello-world"

compose/tests/docker-compose.yml

@@ -0,0 +1,17 @@
+services:
+  hub:
+    image: selenium/hub
+    ports:
+      - "4444:4444"
+  firefox:
+    image: selenium/node-firefox
+    links:
+      - hub
+    expose:
+      - "5555"
+  chrome:
+    image: selenium/node-chrome
+    links:
+      - hub
+    expose:
+      - "5555"

compose/tests/test_docker_compose.py

@@ -0,0 +1,125 @@
+import os
+from unittest.mock import patch
+
+import pytest
+
+from testcontainers.compose import DockerCompose
+from testcontainers.core.docker_client import DockerClient
+from testcontainers.core.exceptions import NoSuchPortExposed
+from testcontainers.core.waiting_utils import wait_for_logs
+
+ROOT = os.path.dirname(__file__)
+
+
+def test_can_spawn_service_via_compose():
+    with DockerCompose(ROOT) as compose:
+        host = compose.get_service_host("hub", 4444)
+        port = compose.get_service_port("hub", 4444)
+        assert host == "0.0.0.0"
+        assert port == "4444"
+
+
+def test_can_pull_images_before_spawning_service_via_compose():
+    with DockerCompose(ROOT, pull=True) as compose:
+        host = compose.get_service_host("hub", 4444)
+        port = compose.get_service_port("hub", 4444)
+        assert host == "0.0.0.0"
+        assert port == "4444"
+
+
+def test_can_build_images_before_spawning_service_via_compose():
+    with patch.object(DockerCompose, "_call_command") as call_mock:
+        with DockerCompose(ROOT, build=True) as compose:
+            ...
+
+    assert compose.build
+    docker_compose_cmd = call_mock.call_args_list[0][1]["cmd"]
+    assert "docker-compose" in docker_compose_cmd
+    assert "up" in docker_compose_cmd
+    assert "--build" in docker_compose_cmd
+
+
+def test_can_specify_services():
+    with patch.object(DockerCompose, "_call_command") as call_mock:
+        with DockerCompose(ROOT, services=["hub", "firefox"]) as compose:
+            ...
+
+    assert compose.services
+    docker_compose_cmd = call_mock.call_args_list[0][1]["cmd"]
+    services_at_the_end = docker_compose_cmd[-2:]
+    assert "firefox" in services_at_the_end
+    assert "hub" in services_at_the_end
+    assert "chrome" not in docker_compose_cmd
+
+
+@pytest.mark.parametrize("should_run_hub", [
+    [True],
+    [False],
+])
+def test_can_run_specific_services(should_run_hub: bool):
+    # compose V2 will improve this test by being able to assert that "firefox" also started/exited
+    services = ["firefox"]
+    if should_run_hub:
+        services.append("hub")
+
+    with DockerCompose(ROOT, services=services) as compose:
+        if should_run_hub:
+            assert compose.get_service_host("hub", 4444)
+            assert compose.get_service_port("hub", 4444)
+        else:
+            with pytest.raises(NoSuchPortExposed):
+                assert compose.get_service_host("hub", 4444)
+
+
+def test_can_throw_exception_if_no_port_exposed():
+    with DockerCompose(ROOT) as compose:
+        with pytest.raises(NoSuchPortExposed):
+            compose.get_service_host("hub", 5555)
+
+
+def test_compose_wait_for_container_ready():
+    with DockerCompose(ROOT) as compose:
+        docker = DockerClient()
+        compose.wait_for("http://%s:4444/wd/hub" % docker.host())
+
+
+def test_compose_can_wait_for_logs():
+    with DockerCompose(filepath=ROOT, compose_file_name="docker-compose-4.yml") as compose:
+        wait_for_logs(compose, "Hello from Docker!")
+
+
+def test_can_parse_multiple_compose_files():
+    with DockerCompose(filepath=ROOT,
+                       compose_file_name=["docker-compose.yml", "docker-compose-2.yml"]) as compose:
+        host = compose.get_service_host("alpine", 3306)
+        port = compose.get_service_port("alpine", 3306)
+        assert host == "0.0.0.0"
+        assert port == "3306"
+
+        host = compose.get_service_host("hub", 4444)
+        port = compose.get_service_port("hub", 4444)
+        assert host == "0.0.0.0"
+        assert port == "4444"
+
+
+def test_can_get_logs():
+    with DockerCompose(ROOT) as compose:
+        docker = DockerClient()
+        compose.wait_for("http://%s:4444/wd/hub" % docker.host())
+        stdout, stderr = compose.get_logs()
+        assert stdout, 'There should be something on stdout'
+
+
+def test_can_pass_env_params_by_env_file():
+    with DockerCompose(ROOT, compose_file_name='docker-compose-3.yml',
+                       env_file='.env.test') as compose:
+        stdout, *_ = compose.exec_in_container("alpine", ["printenv"])
+        assert stdout.splitlines()[0], 'test_has_passed'
+
+
+def test_can_exec_commands():
+    with DockerCompose(ROOT) as compose:
+        result = compose.exec_in_container('hub', ['echo', 'my_test'])
+        assert result[0] == 'my_test\n', "The echo should be successful"
+        assert result[1] == '', "stderr should be empty"
+        assert result[2] == 0, 'The exit code should be successful'