testshed 0.0.1__tar.gz

testshed-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KloudKIT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

testshed-0.0.1/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: testshed
+Version: 0.0.1
+Summary: 🧪 The support crew for your test bench
+Author-email: Dov Benyomin Sohacheski <b@kloud.email>
+License: MIT
+Project-URL: Homepage, https://github.com/kloudkit/testshed
+Project-URL: Bug Tracker, https://github.com/kloudkit/testshed/issues
+Project-URL: Source Code, https://github.com/kloudkit/testshed
+Keywords: pytest,docker,fixtures,playwright,testing
+Classifier: Framework :: Pytest
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright<2.0.0,>=1.54.0
+Requires-Dist: pytest<9.0.0,>=8.4.1
+Requires-Dist: python-on-whales<1.0.0,>=0.78.0
+Requires-Dist: PyYAML<7.0.0,>=6.0.2
+Requires-Dist: requests<3.0.0,>=2.32.4
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.2.0; extra == "dev"
+Requires-Dist: ruff>=0.12.0; extra == "dev"
+Dynamic: license-file
+
+# KloudKIT TestShed
+
+`KloudKIT TestShed` is a `pytest` plugin that streamlines integration tests with Docker
+containers and Playwright—handling setup, execution, and teardown so you can focus on
+writing effective tests.
+
+## Features
+
+- **Automated Docker management:** Spin up and control containers from tests.
+- **Playwright integration:** Run browser tests in isolated Docker environments.
+- **Configurable via markers & CLI:** Tune environments per test or suite.
+- **Automatic resource cleanup:** Ensures a clean state after tests.
+
+## Installation
+
+```sh
+pip install testshed
+```
+
+## Usage
+
+### Docker container testing
+
+TestShed provides fixtures to manage containers inside your tests.
+
+#### High-level `shed` fixtures
+
+Use the `shed` fixture for smart container management with configurable defaults:
+
+```python
+import pytest
+
+from kloudkit.testshed.docker import Container, HttpProbe
+
+class MyAppContainer(Container):
+  DEFAULT_USER = "app"
+
+@pytest.fixture(scope="session")
+def shed_container_defaults():
+  """Override this fixture to set project-specific defaults."""
+
+  return {
+    "container_class": MyAppContainer,
+    "envs": {"APP_PORT": 3000},
+    "probe": HttpProbe(port=3000, endpoint="/health"),
+  }
+
+def test_my_app(shed):
+  # Uses your configured defaults automatically
+  assert shed.execute("whoami") == "app"
+
+@shed_env(DEBUG="true")
+def test_my_app_with_debug(shed):
+  # New container with override, merged with defaults
+  assert shed.execute("echo $DEBUG") == "true"
+  assert shed.execute("echo $APP_PORT") == "3000"
+```
+
+You can also use the factory directly:
+
+```python
+def test_custom_setup(shed_factory):
+  container = shed_factory(envs={"CUSTOM_VAR": "value"})
+  # ... test logic ...
+```
+
+#### Basic Docker container
+
+For a lower-level API, use the `docker_sidecar` fixture to create containers:
+
+```python
+import pytest
+
+def test_my_docker_app(docker_sidecar):
+  # Launch a simple Nginx container
+  nginx = docker_sidecar("nginx:latest", publish=[(8080, 80)])
+
+  # Execute a command inside the container
+  assert "nginx version" in nginx.execute(["nginx", "-v"])
+
+  # Access the container's IP
+  print(f"Nginx container IP: {nginx.ip()}")
+
+  # Interact with the file system
+  assert "/usr/share/nginx/html" in nginx.fs.ls("/usr/share/nginx")
+```
+
+#### Configure containers with decorators
+
+Configure containers using `pytest` markers/decorators:
+
+- **`@shed_config(**kwargs)`:** Generic container args.
+- **`@shed_env(**envs)`:** Environment variables.
+- **`@shed_volumes(*mounts)`:** Volume mounts as `(source, dest)` or `InlineVolume`.
+
+```python
+from kloudkit.testshed.docker import InlineVolume
+
+@shed_env(MY_ENV_VAR="hello")
+@shed_volumes(
+  ("/path/to/host/data", "/app/data:ro"),
+  InlineVolume("/app/config.txt", "any content you want", mode=0o644),
+)
+def test_configured_docker_app(docker_sidecar):
+  app = docker_sidecar("my-custom-app:latest")
+  # ... test logic ...
+```
+
+### Playwright browser testing
+
+Get a Playwright browser instance running in Docker via `playwright_browser`:
+
+```python
+def test_example_website(playwright_browser):
+  page = playwright_browser.new_page()
+  page.goto("http://example.com")
+  assert "Example Domain" in page.title()
+  # ... more Playwright test logic ...
+```
+
+### Command-line options
+
+TestShed extends `pytest` with options to control the Docker environment:
+
+- `--shed`: Enable TestShed for the current test suite *(default: disabled)*.
+- `--shed-image IMAGE`: Base image *(e.g., `ghcr.io/acme/app`)*.
+- `--shed-tag TAG|SHA`: Image tag or digest *(default: `tests`)*.
+- `--shed-build-context DIR`: Docker build context *(default: `pytest.ini` directory)*.
+- `--shed-require-local-image`: Fail if image isn’t present locally *(no build/pull)*.
+- `--shed-rebuild`: Force rebuilding the test image.
+- `--shed-network NAME`: Docker network *(default: `testshed-network`)*.
+- `--shed-skip-bootstrap`: Skip Docker bootstrapping *(useful for unit tests)*.
+
+> [!NOTE]
+> When TestShed is installed globally, you must explicitly enable it per suite with
+> `--shed`.
+> This prevents it from configuring Docker in projects that don’t use it.
+
+#### Examples
+
+```bash
+# Enable TestShed for your suite
+pytest --shed --shed-image my-test-image --shed-rebuild
+
+# Run tests without TestShed (default)
+pytest
+```

testshed-0.0.1/README.md

@@ -0,0 +1,147 @@
+# KloudKIT TestShed
+
+`KloudKIT TestShed` is a `pytest` plugin that streamlines integration tests with Docker
+containers and Playwright—handling setup, execution, and teardown so you can focus on
+writing effective tests.
+
+## Features
+
+- **Automated Docker management:** Spin up and control containers from tests.
+- **Playwright integration:** Run browser tests in isolated Docker environments.
+- **Configurable via markers & CLI:** Tune environments per test or suite.
+- **Automatic resource cleanup:** Ensures a clean state after tests.
+
+## Installation
+
+```sh
+pip install testshed
+```
+
+## Usage
+
+### Docker container testing
+
+TestShed provides fixtures to manage containers inside your tests.
+
+#### High-level `shed` fixtures
+
+Use the `shed` fixture for smart container management with configurable defaults:
+
+```python
+import pytest
+
+from kloudkit.testshed.docker import Container, HttpProbe
+
+class MyAppContainer(Container):
+  DEFAULT_USER = "app"
+
+@pytest.fixture(scope="session")
+def shed_container_defaults():
+  """Override this fixture to set project-specific defaults."""
+
+  return {
+    "container_class": MyAppContainer,
+    "envs": {"APP_PORT": 3000},
+    "probe": HttpProbe(port=3000, endpoint="/health"),
+  }
+
+def test_my_app(shed):
+  # Uses your configured defaults automatically
+  assert shed.execute("whoami") == "app"
+
+@shed_env(DEBUG="true")
+def test_my_app_with_debug(shed):
+  # New container with override, merged with defaults
+  assert shed.execute("echo $DEBUG") == "true"
+  assert shed.execute("echo $APP_PORT") == "3000"
+```
+
+You can also use the factory directly:
+
+```python
+def test_custom_setup(shed_factory):
+  container = shed_factory(envs={"CUSTOM_VAR": "value"})
+  # ... test logic ...
+```
+
+#### Basic Docker container
+
+For a lower-level API, use the `docker_sidecar` fixture to create containers:
+
+```python
+import pytest
+
+def test_my_docker_app(docker_sidecar):
+  # Launch a simple Nginx container
+  nginx = docker_sidecar("nginx:latest", publish=[(8080, 80)])
+
+  # Execute a command inside the container
+  assert "nginx version" in nginx.execute(["nginx", "-v"])
+
+  # Access the container's IP
+  print(f"Nginx container IP: {nginx.ip()}")
+
+  # Interact with the file system
+  assert "/usr/share/nginx/html" in nginx.fs.ls("/usr/share/nginx")
+```
+
+#### Configure containers with decorators
+
+Configure containers using `pytest` markers/decorators:
+
+- **`@shed_config(**kwargs)`:** Generic container args.
+- **`@shed_env(**envs)`:** Environment variables.
+- **`@shed_volumes(*mounts)`:** Volume mounts as `(source, dest)` or `InlineVolume`.
+
+```python
+from kloudkit.testshed.docker import InlineVolume
+
+@shed_env(MY_ENV_VAR="hello")
+@shed_volumes(
+  ("/path/to/host/data", "/app/data:ro"),
+  InlineVolume("/app/config.txt", "any content you want", mode=0o644),
+)
+def test_configured_docker_app(docker_sidecar):
+  app = docker_sidecar("my-custom-app:latest")
+  # ... test logic ...
+```
+
+### Playwright browser testing
+
+Get a Playwright browser instance running in Docker via `playwright_browser`:
+
+```python
+def test_example_website(playwright_browser):
+  page = playwright_browser.new_page()
+  page.goto("http://example.com")
+  assert "Example Domain" in page.title()
+  # ... more Playwright test logic ...
+```
+
+### Command-line options
+
+TestShed extends `pytest` with options to control the Docker environment:
+
+- `--shed`: Enable TestShed for the current test suite *(default: disabled)*.
+- `--shed-image IMAGE`: Base image *(e.g., `ghcr.io/acme/app`)*.
+- `--shed-tag TAG|SHA`: Image tag or digest *(default: `tests`)*.
+- `--shed-build-context DIR`: Docker build context *(default: `pytest.ini` directory)*.
+- `--shed-require-local-image`: Fail if image isn’t present locally *(no build/pull)*.
+- `--shed-rebuild`: Force rebuilding the test image.
+- `--shed-network NAME`: Docker network *(default: `testshed-network`)*.
+- `--shed-skip-bootstrap`: Skip Docker bootstrapping *(useful for unit tests)*.
+
+> [!NOTE]
+> When TestShed is installed globally, you must explicitly enable it per suite with
+> `--shed`.
+> This prevents it from configuring Docker in projects that don’t use it.
+
+#### Examples
+
+```bash
+# Enable TestShed for your suite
+pytest --shed --shed-image my-test-image --shed-rebuild
+
+# Run tests without TestShed (default)
+pytest
+```

testshed-0.0.1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "testshed"
+description = "🧪 The support crew for your test bench"
+requires-python = ">=3.11"
+authors = [{ name = "Dov Benyomin Sohacheski", email = "b@kloud.email" }]
+license = { text = "MIT" }
+keywords = ["pytest", "docker", "fixtures", "playwright", "testing"]
+classifiers = [
+  "Framework :: Pytest",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+dependencies = [
+  "playwright>=1.54.0,<2.0.0",
+  "pytest>=8.4.1,<9.0.0",
+  "python-on-whales>=0.78.0,<1.0.0",
+  "PyYAML>=6.0.2,<7.0.0",
+  "requests>=2.32.4,<3.0.0",
+]
+dynamic = ["readme", "version"]
+
+[project.urls]
+"Homepage" = "https://github.com/kloudkit/testshed"
+"Bug Tracker" = "https://github.com/kloudkit/testshed/issues"
+"Source Code" = "https://github.com/kloudkit/testshed"
+
+[project.optional-dependencies]
+dev = ["pre-commit>=4.2.0", "ruff>=0.12.0"]
+
+[project.entry-points.pytest11]
+testshed = "kloudkit.testshed.plugin"
+
+[tool.setuptools]
+package-dir = { "kloudkit.testshed" = "src" }
+
+[tool.setuptools.dynamic]
+readme = { file = ["README.md"], content-type = "text/markdown" }
+version = { attr = "kloudkit.testshed.__version__" }
+
+[tool.coverage.report]
+exclude_lines = ["@(abc\\.)?abstractmethod", "# pragma: no cover"]

testshed-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

testshed-0.0.1/src/__init__.py

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

testshed-0.0.1/src/_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

testshed-0.0.1/src/core/__init__.py

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

testshed-0.0.1/src/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,
+    )

testshed-0.0.1/src/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

testshed-0.0.1/src/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",
+)

testshed-0.0.1/src/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)

testshed-0.0.1/src/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 {}),
+    )

testshed-0.0.1/src/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)