mockly-testcontainers 0.11.0__py3-none-any.whl

mockly_testcontainers/__init__.py

@@ -0,0 +1,4 @@
+from ._types import FaultConfig, Mock, MockRequest, MockResponse
+from .container import MocklyContainer
+
+__all__ = ["FaultConfig", "Mock", "MockRequest", "MockResponse", "MocklyContainer"]

mockly_testcontainers/_types.py

@@ -0,0 +1,32 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class MockRequest:
+    method: str
+    path: str
+    headers: Optional[dict] = None
+
+
+@dataclass
+class MockResponse:
+    status: int
+    body: Optional[str] = None
+    headers: Optional[dict] = None
+    delay: Optional[str] = None
+
+
+@dataclass
+class Mock:
+    id: str
+    request: MockRequest
+    response: MockResponse
+
+
+@dataclass
+class FaultConfig:
+    enabled: bool
+    delay: Optional[str] = None
+    status_override: Optional[int] = None
+    error_rate: Optional[float] = None

mockly_testcontainers/container.py

@@ -0,0 +1,173 @@
+import json
+import os
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from dataclasses import asdict
+from typing import Any
+
+from testcontainers.core.container import DockerContainer
+
+from ._types import FaultConfig, Mock
+
+DEFAULT_IMAGE = "ghcr.io/dever-labs/mockly:latest"
+HTTP_PORT = 8090
+API_PORT = 9091
+CONTAINER_CONFIG_PATH = "/config/mockly.yaml"
+DEFAULT_CONFIG = """mockly:
+  api:
+    port: 9091
+protocols:
+  http:
+    enabled: true
+    port: 8090
+"""
+
+
+def _without_none(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {
+            key: _without_none(item)
+            for key, item in value.items()
+            if item is not None
+        }
+    if isinstance(value, list):
+        return [_without_none(item) for item in value]
+    return value
+
+
+class MocklyContainer(DockerContainer):
+    def __init__(self, image: str = DEFAULT_IMAGE) -> None:
+        super().__init__(image)
+        self._config_yaml = DEFAULT_CONFIG
+        self._config_host_path: str | None = None
+        self.with_exposed_ports(HTTP_PORT, API_PORT)
+
+    def with_inline_config(self, yaml: str) -> "MocklyContainer":
+        self._config_yaml = yaml
+        return self
+
+    def _configure(self) -> None:
+        self._cleanup_config_file()
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            prefix=".mockly-tc-",
+            suffix=".yaml",
+            dir=os.getcwd(),
+            delete=False,
+        ) as config_file:
+            config_file.write(self._config_yaml)
+            self._config_host_path = config_file.name
+        self.with_command(f"start -c {CONTAINER_CONFIG_PATH}")
+        self.with_volume_mapping(self._config_host_path, CONTAINER_CONFIG_PATH, "ro")
+
+    def _cleanup_config_file(self) -> None:
+        if self._config_host_path is None:
+            return
+        self.volumes.pop(self._config_host_path, None)
+        try:
+            os.unlink(self._config_host_path)
+        except FileNotFoundError:
+            pass
+        self._config_host_path = None
+
+    def get_http_base(self) -> str:
+        host = self.get_container_host_ip()
+        port = self.get_exposed_port(HTTP_PORT)
+        return f"http://{host}:{port}"
+
+    def get_api_base(self) -> str:
+        host = self.get_container_host_ip()
+        port = self.get_exposed_port(API_PORT)
+        return f"http://{host}:{port}"
+
+    def _wait_ready(self, max_ms: int = 60000) -> None:
+        url = f"{self.get_api_base()}/api/protocols"
+        deadline = time.monotonic() + max_ms / 1000
+        while time.monotonic() < deadline:
+            try:
+                with urllib.request.urlopen(url, timeout=2):
+                    return
+            except Exception:
+                time.sleep(0.1)
+        raise TimeoutError(f"Mockly container did not become ready within {max_ms}ms")
+
+    def start(self) -> "MocklyContainer":
+        try:
+            self._configure()
+            super().start()
+            self._wait_ready()
+            return self
+        except Exception:
+            self.stop()
+            raise
+
+    def stop(self, force: bool = True, delete_volume: bool = True) -> None:
+        try:
+            super().stop(force=force, delete_volume=delete_volume)
+        finally:
+            self._cleanup_config_file()
+
+    def add_mock(self, mock: Mock) -> None:
+        self._request(
+            "POST",
+            "/api/mocks/http",
+            _without_none(asdict(mock)),
+            expected=(200, 201),
+        )
+
+    def delete_mock(self, mock_id: str) -> None:
+        self._request("DELETE", f"/api/mocks/http/{mock_id}", expected=(204,))
+
+    def reset(self) -> None:
+        self._request("POST", "/api/reset", expected=(200,))
+
+    def activate_scenario(self, scenario_id: str) -> None:
+        self._request("POST", f"/api/scenarios/{scenario_id}/activate", expected=(200,))
+
+    def deactivate_scenario(self, scenario_id: str) -> None:
+        self._request("POST", f"/api/scenarios/{scenario_id}/deactivate", expected=(200,))
+
+    def set_fault(self, config: FaultConfig) -> None:
+        self._request(
+            "POST",
+            "/api/fault",
+            _without_none(asdict(config)),
+            expected=(200,),
+        )
+
+    def clear_fault(self) -> None:
+        self._request("DELETE", "/api/fault", expected=(200,))
+
+    def get_logs(self) -> str:
+        return self._request("GET", "/api/logs", expected=(200,)).decode()
+
+    def clear_logs(self) -> None:
+        self._request("DELETE", "/api/logs", expected=(200,))
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: dict | None = None,
+        expected: tuple[int, ...] = (200,),
+    ) -> bytes:
+        url = f"{self.get_api_base()}{path}"
+        data = json.dumps(body).encode() if body is not None else None
+        headers = {"Content-Type": "application/json"} if data is not None else {}
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req) as resp:
+                if resp.status not in expected:
+                    raise RuntimeError(
+                        f"Unexpected status {resp.status} for {method} {path}"
+                    )
+                return resp.read()
+        except urllib.error.HTTPError as exc:
+            if exc.code in expected:
+                return exc.read()
+            raise RuntimeError(
+                f"HTTP {exc.code} for {method} {path}: {exc.read().decode(errors='replace')}"
+            ) from exc

mockly_testcontainers-0.11.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: mockly-testcontainers
+Version: 0.11.0
+Summary: Testcontainers module for Mockly — run Mockly as a Docker container in tests
+Project-URL: Homepage, https://github.com/dever-labs/mockly/tree/main/clients/python-testcontainers
+Project-URL: Repository, https://github.com/dever-labs/mockly
+License: MIT
+Keywords: docker,http,integration-test,mock,mockly,testcontainers,testing
+Requires-Python: >=3.10
+Requires-Dist: testcontainers>=4.0.0
+Description-Content-Type: text/markdown
+
+# mockly-testcontainers
+
+Run Mockly in Docker-backed Python tests with `testcontainers-python`.
+
+The package starts `ghcr.io/dever-labs/mockly:latest`, waits for the management API to be ready, and provides helpers for mocks, scenarios, faults, and logs.
+
+## Requirements
+
+- Python 3.10+
+- Docker
+
+## Install
+
+```sh
+pip install mockly-testcontainers
+```
+
+## Quickstart
+
+```python
+import urllib.request
+
+from mockly_testcontainers import Mock, MockRequest, MockResponse, MocklyContainer
+
+with MocklyContainer() as container:
+    container.add_mock(
+        Mock(
+            id="get-user",
+            request=MockRequest(method="GET", path="/users/1"),
+            response=MockResponse(status=200, body='{"id":1}'),
+        )
+    )
+
+    with urllib.request.urlopen(f"{container.get_http_base()}/users/1") as response:
+        assert response.status == 200
+        assert response.read().decode() == '{"id":1}'
+```
+
+## When to use the testcontainers module
+
+Use `mockly-testcontainers` when you want Docker-managed lifecycle, no native binary download, or the same Mockly image in local tests and CI.
+
+Use `mockly-driver` when you want to run the native Mockly binary directly from Python.
+
+## Construction and configuration
+
+`MocklyContainer` extends `testcontainers.core.container.DockerContainer`.
+
+| API | Description |
+|---|---|
+| `MocklyContainer(image=DEFAULT_IMAGE)` | Create a container using the default Mockly image, or override it with another image name. |
+| `with_inline_config(yaml)` | Replace `/config/mockly.yaml` with inline YAML before startup. |
+| `start()` | Start the container and wait for the management API. |
+| `stop()` | Stop the container and clean up the generated config file. |
+
+### Custom YAML config
+
+```python
+with MocklyContainer().with_inline_config("""mockly:
+  api:
+    port: 9091
+protocols:
+  http:
+    enabled: true
+    port: 8090
+""") as container:
+    ...
+```
+
+## Management methods
+
+| Method | Description |
+|---|---|
+| `get_http_base()` | Base URL of the mock HTTP server. |
+| `get_api_base()` | Base URL of the management API. |
+| `add_mock(mock)` | Register a dynamic HTTP mock. |
+| `delete_mock(mock_id)` | Delete a mock by ID. |
+| `reset()` | Remove dynamic mocks, deactivate scenarios, and clear faults. |
+| `activate_scenario(scenario_id)` | Activate a configured scenario. |
+| `deactivate_scenario(scenario_id)` | Deactivate a configured scenario. |
+| `set_fault(config)` | Apply a global HTTP fault. |
+| `clear_fault()` | Remove the active fault. |
+| `get_logs()` | Read request logs as JSON. |
+| `clear_logs()` | Clear stored request logs. |
+
+## Exported types
+
+The package exports these dataclasses:
+
+- `Mock`
+- `MockRequest`
+- `MockResponse`
+- `FaultConfig`

mockly_testcontainers-0.11.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+mockly_testcontainers/__init__.py,sha256=ZLhoise8pYrdKkL5zSNXWNUUVYXHrhNf4WVg-n_nH5A,189
+mockly_testcontainers/_types.py,sha256=diJ-6LPmFKRU5vuyes7Ikx3OPh5wgC6mIli3T5xgvA4,558
+mockly_testcontainers/container.py,sha256=F8sUVYQULEw9EnKYBTNrRtdcrLgpK4Pul7K3izZB2Xs,5552
+mockly_testcontainers-0.11.0.dist-info/METADATA,sha256=GxEz1FQ_B7H2IEE9r6SnR4sA5fYtZvp1tDHCvTceICk,3218
+mockly_testcontainers-0.11.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+mockly_testcontainers-0.11.0.dist-info/RECORD,,

mockly_testcontainers-0.11.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any