testshed 0.0.7__tar.gz

testshed-0.0.7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 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.7/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: testshed
+Version: 0.0.7
+Summary: 🛠️ PyTest's tool shed: Docker up, Playwright on, cleanup done
+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.57.0
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: python-on-whales<1.0.0,>=0.80.0
+Requires-Dist: PyYAML<7.0.0,>=6.0.3
+Requires-Dist: requests<3.0.0,>=2.32.5
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.5.1; extra == "dev"
+Requires-Dist: ruff>=0.14.11; extra == "dev"
+Requires-Dist: coverage>=7.13.1; extra == "dev"
+Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# KloudKIT TestShed
+
+> Meet **KloudKIT TestShed**, a tidy home for your integration-testing power tools.
+>
+> It snap-fits into `pytest`, auto-provisions Docker, runs Playwright, and cleans up after itself
+> so you can focus on building sharp 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
+
+### Fixture Auto-Discovery
+
+TestShed fixtures are automatically available when `--shed` is enabled.
+
+```bash
+pytest --shed
+```
+
+For manual control or when `--shed` is not used, you can still import specific fixtures:
+
+```python
+from kloudkit.testshed.fixtures.docker import docker_sidecar
+from kloudkit.testshed.fixtures.shed import shed
+from kloudkit.testshed.fixtures.playwright import playwright_browser
+```
+
+### 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 `BaseVolume`.
+- **`@shed_mutable()`:** Force non-default shed for tests that perform mutable operations.
+
+```python
+from kloudkit.testshed.docker import InlineVolume, RemoteVolume
+
+@shed_env(MY_ENV_VAR="hello")
+@shed_volumes(
+  ("/path/to/host/data", "/app/data"),
+  InlineVolume("/app/config.txt", "any content you want", mode=0o644),
+  RemoteVolume("/app/remote-config.json", "https://api.example.com/config.json", mode=0o644),
+)
+def test_configured_docker_app(shed):
+  # ... 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-image-policy POLICY`:** Image acquisition policy for building or pulling *(default: `pull`)*.
+- **`--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.
+
+#### Image Policies
+
+The `--shed-image-policy` option controls how TestShed acquires Docker images:
+
+- **`pull`** *(default)***:** Pull image if not found locally, build as fallback.
+- **`build`:** Build only if image doesn't exist locally.
+- **`require`:** Require existing local image *(fails if not found)*.
+- **`rebuild`:** Always rebuild the image.
+
+#### Examples
+
+```bash
+# Enable TestShed for your suite
+pytest --shed --shed-image my-test-image --shed-image-policy rebuild
+
+# Run tests without TestShed (default)
+pytest
+```

testshed-0.0.7/README.md

@@ -0,0 +1,172 @@
+# KloudKIT TestShed
+
+> Meet **KloudKIT TestShed**, a tidy home for your integration-testing power tools.
+>
+> It snap-fits into `pytest`, auto-provisions Docker, runs Playwright, and cleans up after itself
+> so you can focus on building sharp 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
+
+### Fixture Auto-Discovery
+
+TestShed fixtures are automatically available when `--shed` is enabled.
+
+```bash
+pytest --shed
+```
+
+For manual control or when `--shed` is not used, you can still import specific fixtures:
+
+```python
+from kloudkit.testshed.fixtures.docker import docker_sidecar
+from kloudkit.testshed.fixtures.shed import shed
+from kloudkit.testshed.fixtures.playwright import playwright_browser
+```
+
+### 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 `BaseVolume`.
+- **`@shed_mutable()`:** Force non-default shed for tests that perform mutable operations.
+
+```python
+from kloudkit.testshed.docker import InlineVolume, RemoteVolume
+
+@shed_env(MY_ENV_VAR="hello")
+@shed_volumes(
+  ("/path/to/host/data", "/app/data"),
+  InlineVolume("/app/config.txt", "any content you want", mode=0o644),
+  RemoteVolume("/app/remote-config.json", "https://api.example.com/config.json", mode=0o644),
+)
+def test_configured_docker_app(shed):
+  # ... 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-image-policy POLICY`:** Image acquisition policy for building or pulling *(default: `pull`)*.
+- **`--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.
+
+#### Image Policies
+
+The `--shed-image-policy` option controls how TestShed acquires Docker images:
+
+- **`pull`** *(default)***:** Pull image if not found locally, build as fallback.
+- **`build`:** Build only if image doesn't exist locally.
+- **`require`:** Require existing local image *(fails if not found)*.
+- **`rebuild`:** Always rebuild the image.
+
+#### Examples
+
+```bash
+# Enable TestShed for your suite
+pytest --shed --shed-image my-test-image --shed-image-policy rebuild
+
+# Run tests without TestShed (default)
+pytest
+```

testshed-0.0.7/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "testshed"
+description = "🛠️ PyTest's tool shed: Docker up, Playwright on, cleanup done"
+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.57.0,<2.0.0",
+  "pytest>=9.0.2",
+  "python-on-whales>=0.80.0,<1.0.0",
+  "PyYAML>=6.0.3,<7.0.0",
+  "requests>=2.32.5,<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.5.1",
+  "ruff>=0.14.11",
+  "coverage>=7.13.1",
+  "pytest-cov>=7.0.0",
+]
+
+[project.entry-points.pytest11]
+testshed = "kloudkit.testshed.plugin"
+
+[tool.setuptools.dynamic]
+readme = { file = ["README.md"], content-type = "text/markdown" }
+version = { attr = "kloudkit.testshed.__version__" }
+
+[tool.coverage.run]
+source = ["kloudkit.testshed"]
+omit = [
+    "*/tests/*",
+    "*/__pycache__/*",
+    "*/venv/*",
+    "*/.venv/*"
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "@(abc\\.)?abstractmethod",
+    "# pragma: no cover",
+    "if __name__ == .__main__.:",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError"
+]
+show_missing = true
+precision = 2
+fail_under = 80
+
+[tool.coverage.html]
+directory = "htmlcov"

testshed-0.0.7/setup.cfg

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

testshed-0.0.7/src/kloudkit/testshed/__init__.py

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

testshed-0.0.7/src/kloudkit/testshed/core/__init__.py

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

testshed-0.0.7/src/kloudkit/testshed/core/bootstrap.py

@@ -0,0 +1,58 @@
+from pathlib import Path
+from typing import Literal
+
+from python_on_whales import docker
+
+import pytest
+
+
+def _build(image: str, context_path: Path) -> None:
+  print(f"Building image [{image}]")
+  docker.build(
+    context_path=context_path,
+    pull=True,
+    progress="plain",
+    tags=image,
+  )
+
+
+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,
+  *,
+  policy: Literal["pull", "build", "require", "rebuild"],
+  context_path: Path,
+) -> None:
+  """Acquire the Docker image based on the specified policy."""
+
+  image_exists = docker.image.exists(image)
+
+  match policy:
+    case "require":
+      if not image_exists:
+        raise pytest.UsageError(f"Required image [{image}] not found.")
+
+    case "build":
+      if not image_exists:
+        _build(image, context_path)
+
+    case "rebuild":
+      _build(image, context_path)
+
+    case "pull":
+      if image_exists:
+        return
+
+      try:
+        print(f"Testing image [{image}] not found")
+        print(f"Attempting to pull image [{image}]")
+        docker.pull(image)
+      except Exception as e:
+        print(f"Pull failed ({e})")
+        _build(image, context_path)

testshed-0.0.7/src/kloudkit/testshed/core/state.py

@@ -0,0 +1,72 @@
+import os
+import random
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _generate_instance_key(project_name: str) -> str:
+  """Generate a unique instance identifier for containers and networks."""
+
+  xdist_worker = os.getenv("PYTEST_XDIST_WORKER")
+  random_suffix = f"{random.randint(1000, 9999)}"
+
+  instance_parts = filter(
+    None,
+    ["testshed", project_name, random_suffix, xdist_worker],
+  )
+
+  return "-".join(instance_parts)
+
+
+@dataclass(slots=True)
+class ShedState:
+  instance_key: str
+  image: str
+  tag: str
+  src_path: Path
+  tests_path: Path
+  stubs_path: Path
+
+  @property
+  def labels(self) -> dict[str, str]:
+    """Labels for tracking Docker containers."""
+
+    return {"com.kloudkit.testshed": self.instance_key}
+
+  @property
+  def network(self) -> str:
+    """Network name for Docker containers."""
+
+    return self.instance_key
+
+  @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}"
+
+  @classmethod
+  def create(
+    cls,
+    project_name: str,
+    image: str,
+    tag: str,
+    src_path: Path,
+    tests_path: Path,
+    stubs_path: Path,
+  ) -> "ShedState":
+    """Create a ShedState instance with a dynamic instance key."""
+
+    return cls(
+      instance_key=_generate_instance_key(project_name),
+      image=image,
+      tag=tag,
+      src_path=src_path,
+      tests_path=tests_path,
+      stubs_path=stubs_path,
+    )

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

testshed-0.0.7/src/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.probes.http_probe import HttpProbe
+from kloudkit.testshed.docker.volumes.inline_volume import InlineVolume
+from kloudkit.testshed.docker.volumes.remote_volume import RemoteVolume
+
+
+__all__ = (
+  "Container",
+  "docker",
+  "DockerException",
+  "HttpProbe",
+  "InlineVolume",
+  "RemoteVolume",
+)