mockly-testcontainers 0.11.0__tar.gz

mockly_testcontainers-0.11.0/.gitignore

@@ -0,0 +1,72 @@
+# Binaries
+/mockly
+/mockly.exe
+dist/
+
+# UI build
+ui/dist/
+ui/node_modules/
+
+# Assets (built by make)
+assets/dist/
+
+# Go
+*.test
+*.out
+vendor/
+coverage.txt
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Config (user-specific, not example)
+mockly.yaml
+
+# Node client
+clients/node/node_modules/
+clients/node/dist/
+clients/node/bin/
+
+# Node testcontainers
+clients/node-testcontainers/node_modules/
+clients/node-testcontainers/dist/
+
+# Python client
+clients/python/.pytest_cache/
+clients/python/__pycache__/
+clients/python/src/**/__pycache__/
+clients/python/*.egg-info/
+clients/python/dist/
+clients/python/.venv/
+
+# Python testcontainers
+clients/python-testcontainers/.venv/
+clients/python-testcontainers/dist/
+clients/python-testcontainers/src/**/__pycache__/
+clients/python-testcontainers/*.egg-info/
+
+# Python cache (all locations)
+**/__pycache__/
+**/*.pyc
+
+# Java client
+clients/java/target/
+
+# Java testcontainers
+clients/java/testcontainers/target/
+
+# .NET client
+clients/dotnet/**/bin/
+clients/dotnet/**/obj/
+
+# Rust client
+clients/rust/target/
+
+# Rust testcontainers
+clients/rust-testcontainers/target/

mockly_testcontainers-0.11.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,93 @@
+# 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/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mockly-testcontainers"
+version = "0.11.0"
+description = "Testcontainers module for Mockly — run Mockly as a Docker container in tests"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["mock", "testing", "http", "integration-test", "mockly", "testcontainers", "docker"]
+dependencies = ["testcontainers>=4.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/dever-labs/mockly/tree/main/clients/python-testcontainers"
+Repository = "https://github.com/dever-labs/mockly"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mockly_testcontainers"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not integration'"
+markers = [
+    "integration: marks tests that require a running Docker daemon (deselect with '-m not integration')",
+]

mockly_testcontainers-0.11.0/src/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-0.11.0/src/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-0.11.0/src/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/tests/test_container.py

@@ -0,0 +1,113 @@
+from dataclasses import asdict
+from pathlib import Path
+from unittest.mock import MagicMock
+
+from mockly_testcontainers import MocklyContainer
+from mockly_testcontainers._types import FaultConfig, Mock, MockRequest, MockResponse
+from mockly_testcontainers.container import (
+    API_PORT,
+    CONTAINER_CONFIG_PATH,
+    DEFAULT_CONFIG,
+    DEFAULT_IMAGE,
+    HTTP_PORT,
+)
+
+
+def test_default_image():
+    assert DEFAULT_IMAGE == "ghcr.io/dever-labs/mockly:latest"
+
+
+def test_default_ports():
+    assert HTTP_PORT == 8090
+    assert API_PORT == 9091
+
+
+def test_with_inline_config():
+    container = MocklyContainer()
+    yaml = "protocols:\n  http:\n    enabled: true"
+    result = container.with_inline_config(yaml)
+    assert result is container
+    assert container._config_yaml == yaml
+
+
+def test_default_config_contains_api_port():
+    container = MocklyContainer()
+    assert container._config_yaml == DEFAULT_CONFIG
+    assert "api:\n    port: 9091" in container._config_yaml
+
+
+def test_configure_sets_command_and_mounts_config():
+    container = MocklyContainer().with_inline_config("mockly:\n  api:\n    port: 9091\n")
+
+    try:
+        container._configure()
+
+        assert container._command == f"start -c {CONTAINER_CONFIG_PATH}"
+        assert container._config_host_path is not None
+        assert Path(container._config_host_path).read_text() == container._config_yaml
+        assert container.volumes[container._config_host_path] == {
+            "bind": CONTAINER_CONFIG_PATH,
+            "mode": "ro",
+        }
+    finally:
+        container._cleanup_config_file()
+
+
+def test_mock_json_serialization():
+    mock = Mock(
+        id="test",
+        request=MockRequest(method="GET", path="/hello"),
+        response=MockResponse(status=200, body="world"),
+    )
+    data = asdict(mock)
+    assert data["id"] == "test"
+    assert data["request"]["method"] == "GET"
+    assert data["response"]["status"] == 200
+
+
+def test_add_mock_posts_serialized_body():
+    container = MocklyContainer()
+    container._request = MagicMock()
+
+    mock = Mock(
+        id="test",
+        request=MockRequest(method="GET", path="/hello"),
+        response=MockResponse(status=200, body="world"),
+    )
+
+    container.add_mock(mock)
+
+    container._request.assert_called_once_with(
+        "POST",
+        "/api/mocks/http",
+        {
+            "id": "test",
+            "request": {"method": "GET", "path": "/hello"},
+            "response": {"status": 200, "body": "world"},
+        },
+        expected=(200, 201),
+    )
+
+
+def test_set_fault_posts_config():
+    container = MocklyContainer()
+    container._request = MagicMock()
+
+    container.set_fault(FaultConfig(enabled=True, delay="50ms", error_rate=0.1))
+
+    container._request.assert_called_once_with(
+        "POST",
+        "/api/fault",
+        {"enabled": True, "delay": "50ms", "error_rate": 0.1},
+        expected=(200,),
+    )
+
+
+def test_get_logs_returns_decoded_body():
+    container = MocklyContainer()
+    container._request = MagicMock(return_value=b'[{"matched_id":"users"}]')
+
+    logs = container.get_logs()
+
+    assert logs == '[{"matched_id":"users"}]'
+    container._request.assert_called_once_with("GET", "/api/logs", expected=(200,))

mockly_testcontainers-0.11.0/tests/test_integration.py

@@ -0,0 +1,66 @@
+"""Integration tests — require a running Docker daemon.
+
+Run with:
+    pytest -m integration tests/
+"""
+
+import json
+import urllib.error
+import urllib.request
+
+import pytest
+
+from mockly_testcontainers import Mock, MocklyContainer, MockRequest, MockResponse
+
+
+pytestmark = pytest.mark.integration
+
+
+@pytest.fixture(scope="module")
+def container():
+    c = MocklyContainer()
+    c.start()
+    yield c
+    c.stop()
+
+
+def test_smoke(container):
+    assert container.get_http_base().startswith("http://")
+    assert container.get_api_base().startswith("http://")
+
+    with urllib.request.urlopen(f"{container.get_api_base()}/api/protocols") as response:
+        assert response.status == 200
+
+
+def test_add_mock_and_reset(container):
+    container.add_mock(
+        Mock(
+            id="hello-mock",
+            request=MockRequest(method="GET", path="/hello"),
+            response=MockResponse(status=200, body="world"),
+        )
+    )
+
+    with urllib.request.urlopen(f"{container.get_http_base()}/hello") as response:
+        assert response.status == 200
+        assert response.read() == b"world"
+
+    container.reset()
+
+    with pytest.raises(urllib.error.HTTPError) as exc_info:
+        urllib.request.urlopen(f"{container.get_http_base()}/hello")
+
+    assert exc_info.value.code != 200
+
+
+def test_get_logs(container):
+    container.clear_logs()
+
+    try:
+        urllib.request.urlopen(f"{container.get_http_base()}/logging-path")
+    except urllib.error.HTTPError:
+        pass
+
+    logs = container.get_logs()
+    assert len(logs) > 0
+    json.loads(logs)