piphi-runtime-testkit-python 0.1.1__py3-none-any.whl

piphi_runtime_testkit_python/__init__.py

@@ -0,0 +1,16 @@
+"""Pytest-first helpers for testing PiPhi runtime integrations."""
+
+from .assertions import assert_entities_response, assert_event_sent, assert_telemetry_sent
+from .builders import build_config_payload, build_config_snapshot, build_runtime_headers
+from .mock_core import CapturedRequest, MockCoreServer
+
+__all__ = [
+    "CapturedRequest",
+    "MockCoreServer",
+    "assert_entities_response",
+    "assert_event_sent",
+    "assert_telemetry_sent",
+    "build_config_payload",
+    "build_config_snapshot",
+    "build_runtime_headers",
+]

piphi_runtime_testkit_python/assertions.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .mock_core import CapturedRequest, MockCoreServer
+
+
+def _pick_alias(mapping: dict[str, Any], *names: str) -> Any:
+    for name in names:
+        if name in mapping:
+            return mapping[name]
+    return None
+
+
+def _assert_string_list(value: Any, *, label: str) -> None:
+    if not isinstance(value, list) or any(not isinstance(item, str) for item in value):
+        raise AssertionError(f"Expected {label} to be a list[str], but received {value!r}.")
+
+
+def _assert_optional_string(mapping: dict[str, Any], *, names: tuple[str, ...], label: str) -> None:
+    value = _pick_alias(mapping, *names)
+    if value is not None and not isinstance(value, str):
+        raise AssertionError(f"Expected {label} to be a string when provided, but received {value!r}.")
+
+
+def _assert_optional_object(mapping: dict[str, Any], *, names: tuple[str, ...], label: str) -> dict[str, Any] | None:
+    value = _pick_alias(mapping, *names)
+    if value is None:
+        return None
+    if not isinstance(value, dict):
+        raise AssertionError(f"Expected {label} to be an object when provided, but received {value!r}.")
+    return value
+
+
+def _assert_entity_shape(entity: Any, *, index: int) -> dict[str, Any]:
+    if not isinstance(entity, dict):
+        raise AssertionError(f"Expected entities[{index}] to be an object, but received {entity!r}.")
+    if not isinstance(entity.get("id"), str) or not entity["id"]:
+        raise AssertionError(f"Expected entities[{index}].id to be a non-empty string, but received {entity.get('id')!r}.")
+    if not isinstance(entity.get("name"), str) or not entity["name"]:
+        raise AssertionError(
+            f"Expected entities[{index}].name to be a non-empty string, but received {entity.get('name')!r}."
+        )
+    _assert_string_list(entity.get("capabilities"), label=f"entities[{index}].capabilities")
+    _assert_optional_string(entity, names=("config_id", "configId"), label=f"entities[{index}].config_id")
+    _assert_optional_string(entity, names=("device_id", "deviceId"), label=f"entities[{index}].device_id")
+    _assert_optional_string(entity, names=("device_type", "deviceType"), label=f"entities[{index}].device_type")
+    _assert_optional_string(entity, names=("device_class", "deviceClass"), label=f"entities[{index}].device_class")
+    _assert_optional_string(entity, names=("entity_type", "entityType"), label=f"entities[{index}].entity_type")
+
+    dashboard = _assert_optional_object(entity, names=("dashboard",), label=f"entities[{index}].dashboard")
+    if dashboard is not None:
+        allowed_widgets = _pick_alias(dashboard, "allowed_widgets", "allowedWidgets")
+        if allowed_widgets is not None:
+            _assert_string_list(allowed_widgets, label=f"entities[{index}].dashboard.allowed_widgets")
+        recommended_widgets = _pick_alias(dashboard, "recommended_widgets", "recommendedWidgets")
+        if recommended_widgets is not None:
+            _assert_string_list(recommended_widgets, label=f"entities[{index}].dashboard.recommended_widgets")
+        _assert_optional_string(
+            dashboard,
+            names=("default_widget", "defaultWidget"),
+            label=f"entities[{index}].dashboard.default_widget",
+        )
+    return entity
+
+
+def _find_request(
+    requests: list[CapturedRequest],
+    *,
+    device_id: str | None = None,
+    config_id: str | None = None,
+    event_type: str | None = None,
+) -> CapturedRequest | None:
+    for request in requests:
+        body = request.json_body
+        if body is None:
+            continue
+        body_event_type = body.get("event_type") if isinstance(body, dict) else None
+        if body_event_type is None and isinstance(body, dict):
+            body_event_type = body.get("type")
+        if device_id is not None:
+            if isinstance(body, dict) and body.get("device_id") != device_id:
+                continue
+        if config_id is not None:
+            if isinstance(body, dict) and body.get("config_id") != config_id:
+                continue
+        if event_type is not None:
+            if body_event_type != event_type:
+                continue
+        return request
+    return None
+
+
+def assert_telemetry_sent(
+    mock_core: MockCoreServer,
+    *,
+    device_id: str | None = None,
+) -> CapturedRequest:
+    """Assert that at least one telemetry request was captured."""
+
+    if not mock_core.telemetry_requests:
+        raise AssertionError("Expected telemetry to be sent to mock Core, but no telemetry requests were captured.")
+
+    if device_id is None:
+        return mock_core.telemetry_requests[-1]
+
+    request = _find_request(mock_core.telemetry_requests, device_id=device_id)
+    if request is None:
+        raise AssertionError(f"Expected telemetry for device_id={device_id!r}, but captured device_ids were {mock_core.captured_telemetry_device_ids()!r}.")
+    return request
+
+
+def assert_event_sent(
+    mock_core: MockCoreServer,
+    *,
+    device_id: str | None = None,
+    config_id: str | None = None,
+    event_type: str | None = None,
+) -> CapturedRequest:
+    """Assert that at least one event request was captured."""
+
+    if not mock_core.event_requests:
+        raise AssertionError("Expected an event to be sent to mock Core, but no event requests were captured.")
+
+    if device_id is None and config_id is None and event_type is None:
+        return mock_core.event_requests[-1]
+
+    request = _find_request(
+        mock_core.event_requests,
+        device_id=device_id,
+        config_id=config_id,
+        event_type=event_type,
+    )
+    if request is None:
+        raise AssertionError(
+            "Expected event matching filters, but none were captured. "
+            f"device_id={device_id!r} config_id={config_id!r} event_type={event_type!r}"
+        )
+    return request
+
+
+def assert_entities_response(payload: Any) -> dict[str, Any]:
+    """Assert that a runtime /entities payload matches the PiPhi contract."""
+
+    if not isinstance(payload, dict):
+        raise AssertionError(f"Expected /entities payload to be an object, but received {payload!r}.")
+
+    entities = payload.get("entities")
+    if not isinstance(entities, list):
+        raise AssertionError(f"Expected /entities payload to include an entities list, but received {entities!r}.")
+
+    for index, entity in enumerate(entities):
+        _assert_entity_shape(entity, index=index)
+
+    capabilities = payload.get("capabilities")
+    if capabilities is not None and not isinstance(capabilities, dict):
+        raise AssertionError(f"Expected /entities payload capabilities to be an object, but received {capabilities!r}.")
+
+    commands = payload.get("commands")
+    if commands is not None and not isinstance(commands, dict):
+        raise AssertionError(f"Expected /entities payload commands to be an object, but received {commands!r}.")
+
+    return payload

piphi_runtime_testkit_python/builders.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_runtime_headers(
+    *,
+    container_id: str = "test-container",
+    internal_token: str = "test-token",
+    extra_headers: dict[str, str] | None = None,
+) -> dict[str, str]:
+    """Build standard PiPhi runtime auth headers for tests."""
+
+    headers = {
+        "X-Container-Id": container_id,
+        "X-PiPhi-Integration-Token": internal_token,
+    }
+    if extra_headers:
+        headers.update(extra_headers)
+    return headers
+
+
+def build_config_payload(
+    *,
+    config_id: str = "config-1",
+    device_id: str | None = None,
+    container_id: str = "test-container",
+    integration_id: str = "test-integration",
+    include_core_config_id: bool = True,
+    extra: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build a single config payload for `/config` tests."""
+
+    payload: dict[str, Any] = {
+        "id": config_id,
+        "device_id": device_id or config_id,
+        "container_id": container_id,
+        "integration_id": integration_id,
+    }
+    if include_core_config_id:
+        payload["config_id"] = config_id
+    if extra:
+        payload.update(extra)
+    return payload
+
+
+def build_config_snapshot(
+    *,
+    configs: list[dict[str, Any]] | None = None,
+    container_id: str = "test-container",
+    integration_id: str = "test-integration",
+    generation: int = 1,
+    extra: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build a snapshot payload for `/config/sync` style tests."""
+
+    payload: dict[str, Any] = {
+        "container_id": container_id,
+        "integration_id": integration_id,
+        "generation": generation,
+        "configs": configs or [],
+    }
+    if extra:
+        payload.update(extra)
+    return payload

piphi_runtime_testkit_python/mock_core.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from threading import Thread
+from typing import Any
+
+
+TELEMETRY_PATH = "/api/v2/integrations/telemetry"
+EVENT_PATH = "/api/v2/events/ingest"
+
+
+@dataclass(slots=True)
+class CapturedRequest:
+    method: str
+    path: str
+    headers: dict[str, str]
+    body: bytes
+    json_body: Any
+
+
+class _RequestStore:
+    def __init__(self) -> None:
+        self.telemetry_requests: list[CapturedRequest] = []
+        self.event_requests: list[CapturedRequest] = []
+        self.telemetry_status = 200
+        self.event_status = 200
+        self.telemetry_json: Any = {"ok": True}
+        self.event_json: Any = {"ok": True}
+
+    def reset(self) -> None:
+        self.telemetry_requests.clear()
+        self.event_requests.clear()
+        self.telemetry_status = 200
+        self.event_status = 200
+        self.telemetry_json = {"ok": True}
+        self.event_json = {"ok": True}
+
+
+class _MockCoreRequestHandler(BaseHTTPRequestHandler):
+    store: _RequestStore
+
+    def do_POST(self) -> None:  # noqa: N802
+        content_length = int(self.headers.get("Content-Length", "0"))
+        body = self.rfile.read(content_length)
+        try:
+            parsed_json = json.loads(body.decode("utf-8")) if body else None
+        except json.JSONDecodeError:
+            parsed_json = None
+
+        request = CapturedRequest(
+            method="POST",
+            path=self.path,
+            headers={key: value for key, value in self.headers.items()},
+            body=body,
+            json_body=parsed_json,
+        )
+
+        if self.path == TELEMETRY_PATH:
+            self.store.telemetry_requests.append(request)
+            self._send_json(self.store.telemetry_status, self.store.telemetry_json)
+            return
+
+        if self.path == EVENT_PATH:
+            self.store.event_requests.append(request)
+            self._send_json(self.store.event_status, self.store.event_json)
+            return
+
+        self._send_json(404, {"ok": False, "detail": "unknown path"})
+
+    def log_message(self, format: str, *args: object) -> None:  # noqa: A003
+        return None
+
+    def _send_json(self, status_code: int, payload: Any) -> None:
+        data = json.dumps(payload).encode("utf-8")
+        self.send_response(status_code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+
+class MockCoreServer:
+    """Small local HTTP server that simulates PiPhi Core callbacks."""
+
+    def __init__(self) -> None:
+        self._store = _RequestStore()
+        self._server = ThreadingHTTPServer(("127.0.0.1", 0), _MockCoreRequestHandler)
+        self._server.RequestHandlerClass.store = self._store
+        self._thread = Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+
+    @property
+    def host(self) -> str:
+        return "127.0.0.1"
+
+    @property
+    def port(self) -> int:
+        return int(self._server.server_address[1])
+
+    @property
+    def base_url(self) -> str:
+        return f"http://{self.host}:{self.port}"
+
+    @property
+    def telemetry_url(self) -> str:
+        return f"{self.base_url}{TELEMETRY_PATH}"
+
+    @property
+    def event_url(self) -> str:
+        return f"{self.base_url}{EVENT_PATH}"
+
+    @property
+    def telemetry_requests(self) -> list[CapturedRequest]:
+        return self._store.telemetry_requests
+
+    @property
+    def event_requests(self) -> list[CapturedRequest]:
+        return self._store.event_requests
+
+    def set_telemetry_response(self, *, status_code: int = 200, json_body: Any = None) -> None:
+        self._store.telemetry_status = status_code
+        self._store.telemetry_json = {"ok": status_code < 400} if json_body is None else json_body
+
+    def set_event_response(self, *, status_code: int = 200, json_body: Any = None) -> None:
+        self._store.event_status = status_code
+        self._store.event_json = {"ok": status_code < 400} if json_body is None else json_body
+
+    def reset(self) -> None:
+        self._store.reset()
+
+    def captured_telemetry_device_ids(self) -> list[Any]:
+        return [
+            request.json_body.get("device_id")
+            for request in self.telemetry_requests
+            if isinstance(request.json_body, dict)
+        ]
+
+    def shutdown(self) -> None:
+        self._server.shutdown()
+        self._server.server_close()
+        self._thread.join(timeout=2)
+
+    def assert_telemetry_sent(self, *, device_id: str | None = None) -> CapturedRequest:
+        from .assertions import assert_telemetry_sent
+
+        return assert_telemetry_sent(self, device_id=device_id)
+
+    def assert_event_sent(
+        self,
+        *,
+        device_id: str | None = None,
+        config_id: str | None = None,
+        event_type: str | None = None,
+    ) -> CapturedRequest:
+        from .assertions import assert_event_sent
+
+        return assert_event_sent(
+            self,
+            device_id=device_id,
+            config_id=config_id,
+            event_type=event_type,
+        )

piphi_runtime_testkit_python/pytest_plugin.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import pytest
+
+from .builders import build_config_payload, build_config_snapshot, build_runtime_headers
+from .mock_core import MockCoreServer
+
+
+@pytest.fixture
+def mock_core() -> MockCoreServer:
+    """Run a small local mock Core server and capture outbound requests."""
+
+    server = MockCoreServer()
+    try:
+        yield server
+    finally:
+        server.shutdown()
+
+
+@pytest.fixture
+def runtime_headers() -> Callable[..., dict[str, str]]:
+    """Build standard PiPhi runtime auth headers."""
+
+    return build_runtime_headers
+
+
+@pytest.fixture
+def config_payload() -> Callable[..., dict[str, Any]]:
+    """Build a single config payload for `/config` tests."""
+
+    return build_config_payload
+
+
+@pytest.fixture
+def config_snapshot() -> Callable[..., dict[str, Any]]:
+    """Build a snapshot payload for `/config/sync` tests."""
+
+    return build_config_snapshot