testshed 0.0.1__py3-none-any.whl

kloudkit/testshed/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

kloudkit/testshed/_internal/state.py

@@ -0,0 +1,35 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class Options:
+  labels: dict[str, str] = field(
+    default_factory=lambda: {"com.kloudkit.testshed": "testing-container"}
+  )
+  network: str = "testshed-network"
+  image: str | None = None
+  tag: str = "tests"
+  src_path: Path | None = None
+  tests_path: Path | None = None
+  stubs_path: Path | None = None
+
+  @property
+  def image_and_tag(self) -> str:
+    """Fully-qualified Docker testing image for test runs."""
+
+    sep = ":"
+
+    if self.tag.startswith("sha"):
+      sep = "@"
+
+    return f"{self.image}{sep}{self.tag}"
+
+
+_state: Options = Options()
+
+
+def get_state() -> Options:
+  """Get the current state."""
+
+  return _state

kloudkit/testshed/core/__init__.py

@@ -0,0 +1,6 @@
+from kloudkit.testshed.core.wrapper import Wrapper
+
+
+__all__ = (
+  "Wrapper",
+)

kloudkit/testshed/core/bootstrap.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+
+from python_on_whales import docker
+
+import pytest
+
+
+def init_shed_network(network: str) -> None:
+  """Ensure the required Docker network exists."""
+
+  if not docker.network.exists(network):
+    docker.network.create(network)
+
+
+def init_shed_image(
+  image: str,
+  *,
+  require_local_image: bool,
+  force_build: bool,
+  context_path: Path,
+) -> None:
+  """Build the Docker image when missing or rebuild is forced."""
+
+  image_missing = not docker.image.exists(image)
+
+  if image_missing and require_local_image:
+    pytest.exit(f"Required image [{image}] not found. Aborting")
+
+  if image_missing:
+    print(f"Testing image [{image}] not found")
+    force_build = True
+
+  if force_build:
+    print(f"Forcing build of test image [{image}]")
+
+    docker.build(
+      context_path=context_path,
+      pull=True,
+      progress="plain",
+      tags=image,
+    )

kloudkit/testshed/core/wrapper.py

@@ -0,0 +1,42 @@
+from types import SimpleNamespace
+from typing import Any, Generic, TypeVar
+
+
+T = TypeVar("T")
+
+
+class Wrapper(Generic[T]):
+  __slots__ = ("_wrapped", "_args")
+
+  def __init__(self, wrapped: T, **kwargs: Any) -> None:
+    self._wrapped: T = wrapped
+    self._args = SimpleNamespace(**kwargs)
+
+  def __getattr__(self, name: str) -> Any:
+    """Delegate lookups to the wrapped object."""
+
+    return getattr(self._wrapped, name)
+
+  def __dir__(self) -> list[str]:
+    """Augment `dir` with attributes from the wrapped object."""
+
+    return sorted(set(super().__dir__()) | set(dir(self._wrapped)))
+
+  def __repr__(self) -> str:
+    """Representation of the wrapper, including passed keyword args."""
+
+    args_dict = vars(self._args)
+    suffix = ""
+
+    if args_dict:
+      kv = ", ".join(f"{k}={args_dict[k]!r}" for k in sorted(args_dict))
+
+      suffix = f", {kv}"
+
+    return f"{type(self).__name__}({self._wrapped!r}{suffix})"
+
+  @property
+  def wrapped(self) -> T:
+    """Get the underlying wrapped object with its precise type."""
+
+    return self._wrapped

kloudkit/testshed/docker/__init__.py

@@ -0,0 +1,16 @@
+from python_on_whales import DockerException, docker
+
+from kloudkit.testshed.docker.container import Container
+from kloudkit.testshed.docker.factory import Factory
+from kloudkit.testshed.docker.inline_volume import InlineVolume
+from kloudkit.testshed.docker.probes.http_probe import HttpProbe
+
+
+__all__ = (
+  "Container",
+  "docker",
+  "DockerException",
+  "Factory",
+  "HttpProbe",
+  "InlineVolume",
+)

kloudkit/testshed/docker/container.py

@@ -0,0 +1,51 @@
+from python_on_whales import Container as NativeContainer, docker
+
+from kloudkit.testshed.core.wrapper import Wrapper
+from kloudkit.testshed.docker.runtime.file_system import FileSystem
+from kloudkit.testshed.docker.runtime.shell import Shell
+
+
+class Container(Wrapper[NativeContainer]):
+  BASH_PATH = "/bin/bash"
+  SH_PATH = "/bin/sh"
+  ZSH_PATH = "/usr/bin/zsh"
+
+  LOGIN_SHELL = False
+  DEFAULT_USER = None
+  DEFAULT_SHELL = None
+
+  def ip(self) -> str:
+    """Retrieve internal IP address of container."""
+
+    return self.execute(["hostname", "-i"])
+
+  @property
+  def fs(self) -> FileSystem:
+    """Higher order file system."""
+
+    return FileSystem(self)
+
+  @property
+  def execute(self) -> Shell:
+    """Higher order execution."""
+
+    return Shell(
+      self._wrapped,
+      bash_path=self.BASH_PATH,
+      sh_path=self.SH_PATH,
+      zsh_path=self.ZSH_PATH,
+      user=self.DEFAULT_USER,
+      shell=self.DEFAULT_SHELL,
+      login_shell=self.LOGIN_SHELL,
+    )
+
+  @classmethod
+  def run(cls, *args, **kwargs):
+    """Wrap the native `docker.run`."""
+
+    instance = docker.run(*args, **kwargs)
+
+    if isinstance(instance, str):
+      return instance
+
+    return cls(instance)

kloudkit/testshed/docker/container_config.py

@@ -0,0 +1,45 @@
+from dataclasses import dataclass
+from typing import Self
+
+import pytest
+
+
+@dataclass(frozen=True, slots=True)
+class ContainerConfig:
+  envs: dict[str, str]
+  volumes: tuple[str, ...]
+  args: dict[str, str]
+  test_name: str
+
+  @property
+  def has_overrides(self) -> bool:
+    """If any fields are non-empty."""
+
+    return bool(self.envs or self.volumes or self.args)
+
+  def to_dict(self) -> dict:
+    """Return a plain dict with merged configs."""
+
+    return dict(
+      envs=self.envs,
+      volumes=self.volumes,
+      test_name=self.test_name,
+      **self.args,
+    )
+
+  @classmethod
+  def create(cls, request: pytest.FixtureRequest) -> Self:
+    """Create configs from a pytest request of the current node."""
+
+    item = request.node
+
+    config_marker = item.get_closest_marker("shed_config")
+    env_marker = item.get_closest_marker("shed_env")
+    volumes_marker = item.get_closest_marker("shed_volumes")
+
+    return cls(
+      envs=env_marker.kwargs if env_marker else {},
+      volumes=tuple(volumes_marker.args) if volumes_marker else tuple(),
+      test_name=item.nodeid,
+      args=(config_marker.kwargs if config_marker else {}),
+    )

kloudkit/testshed/docker/decorators.py

@@ -0,0 +1,23 @@
+from kloudkit.testshed.docker.inline_volume import InlineVolume
+
+import pytest
+
+
+def shed_config(**configs) -> pytest.MarkDecorator:
+  """Assign generic configs to the `shed` instance."""
+
+  return pytest.mark.shed_config(**configs)
+
+
+def shed_env(**envs) -> pytest.MarkDecorator:
+  """Assign environment variables to the `shed` instance."""
+
+  return pytest.mark.shed_env(**envs)
+
+
+def shed_volumes(
+  *mounts: tuple[str, str] | InlineVolume,
+) -> pytest.MarkDecorator:
+  """Assign volume mounts to the `shed` instance."""
+
+  return pytest.mark.shed_volumes(*mounts)

kloudkit/testshed/docker/factory.py

@@ -0,0 +1,68 @@
+from kloudkit.testshed._internal.state import get_state
+from kloudkit.testshed.docker.container import Container
+from kloudkit.testshed.docker.probes.http_probe import HttpProbe
+from kloudkit.testshed.docker.probes.readiness_check import ReadinessCheck
+from kloudkit.testshed.docker.runtime.cleanup import Cleanup
+from kloudkit.testshed.docker.volume_manager import VolumeManager
+
+
+class Factory:
+  def __init__(self):
+    self._containers: list[Container] = []
+    self._volume_manager = VolumeManager()
+
+  def __call__(self, *args, **kwargs) -> Container | str:
+    """Delegate to `build`."""
+
+    return self.build(*args, **kwargs)
+
+  def build(
+    self,
+    image: str,
+    *,
+    detach: bool = True,
+    probe: HttpProbe | None = None,
+    container_class: type[Container] | None = None,
+    test_name: str | None = None,
+    **kwargs,
+  ) -> Container | str:
+    """Create a Docker container to use in test-cases."""
+
+    container_class = container_class or Container
+
+    container = container_class.run(
+      image,
+      remove=True,
+      labels=self._prepare_labels(test_name),
+      detach=detach,
+      networks=kwargs.pop("networks", [get_state().network]),
+      volumes=self._volume_manager.normalize(kwargs.pop("volumes", [])),
+      **kwargs,
+    )
+
+    if isinstance(container, str):
+      return container
+
+    self._containers.append(container)
+
+    if probe:
+      ReadinessCheck(container, probe).wait()
+
+    return container
+
+  def _prepare_labels(self, test_name: str | None) -> dict:
+    """Prepare labels to track Docker container instance."""
+
+    labels = get_state().labels
+
+    if test_name:
+      labels["com.kloudkit.testshed.test"] = test_name
+
+    return labels
+
+  def cleanup(self) -> None:
+    """Force-remove all containers started during test-cases."""
+
+    Cleanup.run(self._containers, get_state().labels)
+
+    self._volume_manager.cleanup()

kloudkit/testshed/docker/inline_volume.py

@@ -0,0 +1,41 @@
+import os
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class InlineVolume:
+  """A volume mount created from inline content written to a temporary file."""
+
+  path: Path | str
+  _content: bytes | str
+  _mode: int = 0o644
+  _temp_path: Path | str | None = field(default=None, init=False, repr=False)
+
+  def create(self) -> str:
+    """Create the temporary file and return its path."""
+
+    if self._temp_path is not None:
+      return self._temp_path
+
+    temp_file = tempfile.NamedTemporaryFile(mode="w", delete=False)
+
+    try:
+      temp_file.write(self._content)
+      temp_file.flush()
+
+      self._temp_path = temp_file.name
+
+      os.chmod(self._temp_path, self._mode)
+    finally:
+      temp_file.close()
+
+    return self._temp_path
+
+  def cleanup(self) -> None:
+    """Clean up the temporary file."""
+
+    if self._temp_path and Path(self._temp_path).exists():
+      os.unlink(self._temp_path)
+      self._temp_path = None

kloudkit/testshed/docker/probes/http_probe.py

@@ -0,0 +1,23 @@
+from dataclasses import asdict, dataclass, replace
+from typing import Self
+
+
+@dataclass(slots=True)
+class HttpProbe:
+  host: str = "http://localhost"
+  port: int | None = None
+  endpoint: str | None = None
+  command: str = "curl"
+  timeout: float = 30.0
+
+  def merge(
+    self, other: "HttpProbe", *, ignore_none: bool = True
+  ) -> Self:
+    """Merge two Probes."""
+
+    if not ignore_none:
+      return replace(self, **asdict(other))
+
+    overlay = {k: v for k, v in asdict(other).items() if v is not None}
+
+    return replace(self, **overlay)

kloudkit/testshed/docker/probes/readiness_check.py

@@ -0,0 +1,48 @@
+import time
+
+from python_on_whales.exceptions import DockerException
+
+from kloudkit.testshed.docker.container import Container
+from kloudkit.testshed.docker.probes.http_probe import HttpProbe
+
+import pytest
+
+
+class ReadinessCheck:
+  def __init__(self, container: Container, probe: HttpProbe):
+    self._container: Container = container
+    self._probe: HttpProbe = probe
+
+  @property
+  def url(self) -> str:
+    """Full probe target URL."""
+
+    port = f":{self._probe.port}" if self._probe.port else ""
+    endpoint = self._probe.endpoint if self._probe.endpoint else ""
+
+    return "".join((self._probe.host, port, endpoint))
+
+  @property
+  def command(self) -> list[str]:
+    """Full probe test command."""
+
+    return [*self._probe.command.split(" "), self.url]
+
+  def wait(self) -> None:
+    """Wait until a container responds on the given endpoint."""
+
+    deadline = time.time() + self._probe.timeout
+
+    failure_message = (
+      f"URL [{self.url}] was not reachable within {self._probe.timeout}s"
+    )
+
+    while time.time() < deadline:
+      try:
+        self._container.execute(self.command, raises=True)
+
+        return
+      except DockerException:
+        time.sleep(0.1)
+
+    pytest.fail(failure_message, pytrace=False)

kloudkit/testshed/docker/runtime/cleanup.py

@@ -0,0 +1,30 @@
+import contextlib
+
+from python_on_whales import docker
+from python_on_whales.exceptions import DockerException
+
+from kloudkit.testshed._internal.state import get_state
+from kloudkit.testshed.docker.container import Container
+
+
+class Cleanup:
+  @classmethod
+  def run(
+    cls,
+    containers: list[Container] | None = None,
+    labels: dict | None = None,
+  ) -> None:
+    """Force-remove all provided containers or labeled."""
+
+    if containers is None:
+      labels = labels or get_state().labels
+
+      key, value = next(iter(labels.items()))
+
+      containers = docker.container.list(
+        all=True, filters=[("label", f"{key}={value}")]
+      )
+
+    for container in containers:
+      with contextlib.suppress(DockerException):
+        container.remove(force=True, volumes=True)

kloudkit/testshed/docker/runtime/error_handler.py

@@ -0,0 +1,33 @@
+import functools
+from typing import Callable, ParamSpec, TypeVar
+
+from python_on_whales.exceptions import DockerException, NoSuchContainer
+
+import pytest
+
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+def error_handler(fn: Callable[P, T]) -> Callable[P, T]:
+  """Handle Docker related error output."""
+
+  @functools.wraps(fn)
+  def _wrapped(self, *args, **kwargs):
+    raises = kwargs.pop("raises", False)
+
+    try:
+      return fn(self, *args, **kwargs)
+    except NoSuchContainer as error:
+      failure = str(error)
+    except DockerException as error:
+      if raises:
+        raise
+
+      failure = str(error)
+
+    if failure:
+      pytest.fail(failure, pytrace=False)
+
+  return _wrapped

kloudkit/testshed/docker/runtime/file_system.py

@@ -0,0 +1,62 @@
+import json
+import tempfile
+from pathlib import Path
+
+import yaml
+from python_on_whales import docker
+
+from kloudkit.testshed.core.wrapper import Wrapper
+from kloudkit.testshed.docker.runtime.error_handler import error_handler
+
+
+class FileSystem(Wrapper["Container"]):
+  def exists(self, path: str | Path) -> bool:
+    """Check if a file or directory exists."""
+
+    result = self._wrapped.execute(
+      ["test", "-e", path, "&&", "echo", "yes", "||", "echo", "no"]
+    )
+
+    return "yes" in result
+
+  def json(self, path: str | Path) -> dict:
+    """Retrieve the content of a file as json."""
+
+    return json.loads(self(path))
+
+  def yaml(self, path: str | Path) -> dict:
+    """Retrieve the content of a file as yaml."""
+
+    return yaml.safe_load(self(path))
+
+  def text(self, path: str | Path) -> str:
+    """Retrieve the content of a file as text."""
+
+    return self.bytes(path).decode("utf-8")
+
+  @error_handler
+  def bytes(self, path: str | Path) -> bytes:
+    """Retrieve the content of a file as bytes."""
+
+    with tempfile.NamedTemporaryFile(delete=True) as tmp_file:
+      docker.copy((self._wrapped.id, path), tmp_file.name)
+
+      return Path(tmp_file.name).read_bytes()
+
+  @error_handler
+  def ls(self, path: str | Path, *, hidden=False) -> tuple[str, ...]:
+    """Retrieve directory listing for a given path."""
+
+    flags = "-1"
+
+    if hidden:
+      flags = f"{flags}a"
+
+    return tuple(
+      self._wrapped.execute(["\\ls", flags, str(path)]).splitlines()
+    )
+
+  def __call__(self, path: str | Path) -> str:
+    """Retrieve the content of a file for a given path."""
+
+    return self.text(path)

kloudkit/testshed/docker/runtime/shell.py

@@ -0,0 +1,75 @@
+from typing import Iterable
+
+from python_on_whales import Container as NativeContainer
+
+from kloudkit.testshed.core.wrapper import Wrapper
+from kloudkit.testshed.docker.runtime.error_handler import error_handler
+
+
+class Shell(Wrapper[NativeContainer]):
+  @error_handler
+  def _execute(
+    self,
+    command: list[str] | tuple[str] | str,
+    shell: str = None,
+    login_shell: bool | None = None,
+    raises=False,
+    **kwargs,
+  ) -> Iterable[tuple[str, bytes]] | str | None:
+    """Execute commands natively using the default shell."""
+
+    flags = (
+      "-cli"
+      if (login_shell if login_shell is not None else self._args.login_shell)
+      else "-c"
+    )
+
+    user = kwargs.pop("user", self._args.user)
+
+    shell = shell or (
+      self._args.shell if self._args.shell is not None else None
+    )
+
+    if shell:
+      if not isinstance(command, str):
+        command = " ".join(command)
+
+      command = [shell, flags, command]
+
+    return self._wrapped.execute(command, user=user, **kwargs)
+
+  def bash(
+    self,
+    command: list[str] | tuple[str] | str,
+    **kwargs,
+  ) -> Iterable[tuple[str, bytes]] | str | None:
+    """Execute commands using `bash` shell."""
+
+    return self._execute(command, shell=self._args.bash_path, **kwargs)
+
+  def zsh(
+    self,
+    command: list[str] | tuple[str] | str,
+    **kwargs,
+  ) -> Iterable[tuple[str, bytes]] | str | None:
+    """Execute commands using `zsh` shell."""
+
+    return self._execute(command, shell=self._args.zsh_path, **kwargs)
+
+  def sh(
+    self,
+    command: list[str] | tuple[str] | str,
+    **kwargs,
+  ) -> Iterable[tuple[str, bytes]] | str | None:
+    """Execute commands using `sh` shell."""
+
+    return self._execute(command, shell=self._args.sh_path, **kwargs)
+
+  def __call__(
+    self,
+    command: list[str] | tuple[str] | str,
+    **kwargs,
+  ) -> Iterable[tuple[str, bytes]] | str | None:
+    """Execute using the native method."""
+
+    return self._execute(command, **kwargs)