aiohomematic-test-support 2025.12.23__py3-none-any.whl → 2026.1.23__py3-none-any.whl

aiohomematic_test_support/event_mock.py

@@ -0,0 +1,300 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Event-driven mock server for test triggers.
+
+Overview
+--------
+This module provides a mock server that responds to events by injecting
+data or triggering actions. This enables event-based test orchestration
+where test behavior is triggered by events rather than explicit calls.
+
+The EventDrivenMockServer allows tests to:
+- Configure responses to specific event types
+- Inject mock data when certain events are published
+- Build complex test scenarios with event-driven behavior
+
+Public API
+----------
+- EventDrivenMockServer: Main mock server class
+- ResponseBuilder: Fluent builder for configuring responses
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from aiohomematic.central.events import Event, EventBus
+
+
+@dataclass
+class MockAction:
+    """
+    An action to perform when an event is received.
+
+    Attributes:
+    ----------
+        handler: The callback to invoke when the event is received
+        filter_fn: Optional filter function to match specific events
+        one_shot: If True, the action is removed after first invocation
+
+    """
+
+    handler: Callable[[Any], Any]
+    filter_fn: Callable[[Any], bool] | None = None
+    one_shot: bool = False
+
+
+@dataclass
+class EventDrivenMockServer:
+    """
+    Mock server that responds to events.
+
+    Provides a fluent API for configuring responses to specific event types.
+    When an event is published that matches a configured response, the
+    corresponding action is executed.
+
+    Example Usage
+    -------------
+        mock_server = EventDrivenMockServer(event_bus=central.event_bus)
+
+        # Configure response to inject data when refresh is triggered
+        mock_server.when(DataRefreshTriggeredEvent).then_call(
+            lambda event: inject_mock_data()
+        )
+
+        # Configure one-shot response
+        mock_server.when(CircuitBreakerTrippedEvent).once().then_call(
+            lambda event: trigger_recovery()
+        )
+
+        # Later, cleanup:
+        mock_server.cleanup()
+
+    """
+
+    _event_bus: EventBus = field(repr=False)
+    """The EventBus to subscribe to."""
+
+    _responses: dict[type[Event], list[MockAction]] = field(default_factory=dict)
+    """Mapping of event types to their configured actions."""
+
+    _unsubscribers: list[Callable[[], None]] = field(default_factory=list)
+    """Unsubscribe callbacks for cleanup."""
+
+    _invocation_count: dict[type[Event], int] = field(default_factory=dict)
+    """Count of invocations per event type."""
+
+    def cleanup(self) -> None:
+        """Unsubscribe from all events and clear responses."""
+        for unsub in self._unsubscribers:
+            unsub()
+        self._unsubscribers.clear()
+        self._responses.clear()
+        self._invocation_count.clear()
+
+    def get_invocation_count(self, *, event_type: type[Event]) -> int:
+        """
+        Return the number of times handlers were invoked for an event type.
+
+        Args:
+        ----
+            event_type: The event type to query
+
+        Returns:
+        -------
+            Number of handler invocations
+
+        """
+        return self._invocation_count.get(event_type, 0)
+
+    def when[T: Event](self, *, event_type: type[T]) -> ResponseBuilder[T]:
+        """
+        Start configuring a response for an event type.
+
+        Args:
+        ----
+            event_type: The event type to respond to
+
+        Returns:
+        -------
+            A ResponseBuilder for configuring the response
+
+        """
+        return ResponseBuilder(mock_server=self, event_type=event_type)
+
+    def _add_response(
+        self,
+        *,
+        event_type: type[Event],
+        action: MockAction,
+    ) -> None:
+        """
+        Add a response for an event type.
+
+        If this is the first response for this event type, subscribe to it.
+
+        Args:
+        ----
+            event_type: The event type to respond to
+            action: The action to perform
+
+        """
+        if event_type not in self._responses:
+            self._responses[event_type] = []
+            # Subscribe to this event type
+            unsub = self._event_bus.subscribe(
+                event_type=event_type,
+                event_key=None,
+                handler=lambda event, et=event_type: self._on_event(event=event, event_type=et),
+            )
+            self._unsubscribers.append(unsub)
+
+        self._responses[event_type].append(action)
+
+    def _on_event(self, *, event: Event, event_type: type[Event]) -> None:
+        """
+        Handle an event by invoking matching responses.
+
+        Args:
+        ----
+            event: The event that was published
+            event_type: The event type (for lookup)
+
+        """
+        if event_type not in self._responses:
+            return
+
+        # Track invocations
+        self._invocation_count[event_type] = self._invocation_count.get(event_type, 0) + 1
+
+        # Process actions (copy list to allow modification during iteration)
+        actions_to_remove: list[MockAction] = []
+        for action in list(self._responses[event_type]):
+            # Check filter if present
+            if action.filter_fn is not None and not action.filter_fn(event):
+                continue
+
+            # Invoke handler
+            action.handler(event)
+
+            # Mark one-shot actions for removal
+            if action.one_shot:
+                actions_to_remove.append(action)
+
+        # Remove one-shot actions
+        for action in actions_to_remove:
+            self._responses[event_type].remove(action)
+
+
+@dataclass
+class ResponseBuilder[T: "Event"]:
+    """
+    Fluent builder for configuring mock responses.
+
+    Provides a chainable API for configuring how the mock server should
+    respond to specific events.
+
+    Example:
+    -------
+        mock_server.when(SomeEvent)
+            .matching(lambda e: e.interface_id == "test")
+            .once()
+            .then_call(handler_fn)
+
+    """
+
+    mock_server: EventDrivenMockServer
+    """The mock server to configure."""
+
+    event_type: type[T]
+    """The event type being configured."""
+
+    _filter_fn: Callable[[T], bool] | None = None
+    """Optional filter function."""
+
+    _one_shot: bool = False
+    """Whether this is a one-shot response."""
+
+    def matching(self, *, filter_fn: Callable[[T], bool]) -> ResponseBuilder[T]:
+        """
+        Add a filter to match specific events.
+
+        Args:
+        ----
+            filter_fn: Function that returns True for matching events
+
+        Returns:
+        -------
+            Self for chaining
+
+        """
+        self._filter_fn = filter_fn
+        return self
+
+    def once(self) -> ResponseBuilder[T]:
+        """
+        Make this a one-shot response (removed after first invocation).
+
+        Returns
+        -------
+            Self for chaining
+
+        """
+        self._one_shot = True
+        return self
+
+    def then_call(self, *, handler: Callable[[T], Any]) -> None:
+        """
+        Configure the handler to call when the event is received.
+
+        Args:
+        ----
+            handler: Function to call with the event
+
+        """
+        self.mock_server._add_response(  # noqa: SLF001  # pylint: disable=protected-access
+            event_type=self.event_type,
+            action=MockAction(
+                handler=handler,
+                filter_fn=self._filter_fn,
+                one_shot=self._one_shot,
+            ),
+        )
+
+    def then_publish(self, *, event_factory: Callable[[T], Event]) -> None:
+        """
+        Configure the mock to publish another event when this event is received.
+
+        Args:
+        ----
+            event_factory: Function that creates the event to publish
+
+        """
+
+        def publish_handler(event: T) -> None:
+            new_event = event_factory(event)
+            self.mock_server._event_bus.publish_sync(event=new_event)  # noqa: SLF001  # pylint: disable=protected-access
+
+        self.then_call(handler=publish_handler)
+
+
+def create_event_mock_server(*, event_bus: EventBus) -> EventDrivenMockServer:
+    """
+    Create an EventDrivenMockServer instance.
+
+    Factory function for creating an event-driven mock server.
+
+    Args:
+    ----
+        event_bus: The EventBus to subscribe to
+
+    Returns:
+    -------
+        Configured EventDrivenMockServer instance
+
+    """
+    return EventDrivenMockServer(_event_bus=event_bus)

aiohomematic_test_support/factory.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
 """
 Test factories for creating CentralUnit and Client instances.
 
@@ -35,16 +37,22 @@ import asyncio
 from collections.abc import AsyncGenerator, Callable
 import contextlib
 import logging
-from typing import Self, cast
+from typing import Any, Self, cast
 from unittest.mock import MagicMock, Mock, patch
 
 from aiohttp import ClientSession
 
 from aiohomematic.central import CentralConfig, CentralUnit
-from aiohomematic.central.event_bus import BackendSystemEventData, HomematicEvent
-from aiohomematic.client import ClientConfig, InterfaceConfig
-from aiohomematic.const import LOCAL_HOST, BackendSystemEvent, Interface, OptionalSettings
-from aiohomematic.interfaces.client import ClientProtocol
+from aiohomematic.central.events import (
+    DataPointsCreatedEvent,
+    DeviceLifecycleEvent,
+    DeviceLifecycleEventType,
+    DeviceTriggerEvent,
+    SystemStatusChangedEvent,
+)
+from aiohomematic.client import InterfaceConfig, create_client as create_client_func
+from aiohomematic.const import LOCAL_HOST, Interface, OptionalSettings
+from aiohomematic.interfaces import ClientProtocol
 from aiohomematic_test_support import const
 from aiohomematic_test_support.mock import SessionPlayer, get_client_session, get_mock, get_xml_rpc_proxy
 
@@ -82,27 +90,45 @@ class FactoryWithClient:
         self.system_event_mock = MagicMock()
         self.ha_event_mock = MagicMock()
         self._event_bus_unsubscribe_callbacks: list[Callable[[], None]] = []
+        self._patches: list[Any] = []
 
-    def cleanup_event_bus_subscriptions(self) -> None:
-        """Clean up all event bus subscriptions."""
+    def cleanup(self) -> None:
+        """Clean up all patches and event bus subscriptions."""
         for unsubscribe in self._event_bus_unsubscribe_callbacks:
             unsubscribe()
         self._event_bus_unsubscribe_callbacks.clear()
+        for p in self._patches:
+            p.stop()
+        self._patches.clear()
+
+    def cleanup_event_bus_subscriptions(self) -> None:
+        """Clean up all event bus subscriptions. Deprecated: use cleanup() instead."""
+        self.cleanup()
 
     async def get_default_central(self, *, start: bool = True) -> CentralUnit:
         """Return a central based on give address_device_translation."""
         central = await self.get_raw_central()
 
         await self._xml_proxy.do_init()
-        patch("aiohomematic.client.ClientConfig._create_xml_rpc_proxy", return_value=self._xml_proxy).start()
-        patch("aiohomematic.central.CentralUnit._identify_ip_addr", return_value=LOCAL_HOST).start()
+        p1 = patch("aiohomematic.client.ClientConfig._create_xml_rpc_proxy", return_value=self._xml_proxy)
+        p2 = patch("aiohomematic.central.CentralUnit._identify_ip_addr", return_value=LOCAL_HOST)
+        p1.start()
+        p2.start()
+        self._patches.extend([p1, p2])
 
         # Optionally patch client creation to return a mocked client
         if self._do_mock_client:
-            _orig_create_client = ClientConfig.create_client
-
-            async def _mocked_create_client(config: ClientConfig) -> ClientProtocol | Mock:
-                real_client = await _orig_create_client(config)
+            _orig_create_client = create_client_func
+
+            async def _mocked_create_client(
+                *,
+                client_deps: Any,
+                interface_config: InterfaceConfig,
+            ) -> ClientProtocol | Mock:
+                real_client = await _orig_create_client(
+                    client_deps=client_deps,
+                    interface_config=interface_config,
+                )
                 return cast(
                     Mock,
                     get_mock(
@@ -112,7 +138,9 @@ class FactoryWithClient:
                     ),
                 )
 
-            patch("aiohomematic.client.ClientConfig.create_client", _mocked_create_client).start()
+            p3 = patch("aiohomematic.client.create_client", _mocked_create_client)
+            p3.start()
+            self._patches.append(p3)
 
         if start:
             await central.start()
@@ -123,7 +151,7 @@ class FactoryWithClient:
     async def get_raw_central(self) -> CentralUnit:
         """Return a central based on give address_device_translation."""
         interface_configs = self._interface_configs if self._interface_configs else set()
-        central = CentralConfig(
+        central = await CentralConfig(
             name=const.CENTRAL_NAME,
             host=const.CCU_HOST,
             username=const.CCU_USERNAME,
@@ -138,21 +166,41 @@ class FactoryWithClient:
         ).create_central()
 
         # Subscribe to events via event bus
-        def _system_event_handler(event: BackendSystemEventData) -> None:
-            """Handle backend system events."""
+        def _device_lifecycle_event_handler(event: DeviceLifecycleEvent) -> None:
+            """Handle device lifecycle events."""
             self.system_event_mock(event)
 
-        def _ha_event_handler(event: HomematicEvent) -> None:
-            """Handle homematic events."""
+        def _data_points_created_event_handler(event: DataPointsCreatedEvent) -> None:
+            """Handle data points created events."""
+            self.system_event_mock(event)
+
+        def _device_trigger_event_handler(event: DeviceTriggerEvent) -> None:
+            """Handle device trigger events."""
+            self.ha_event_mock(event)
+
+        def _system_status_event_handler(event: SystemStatusChangedEvent) -> None:
+            """Handle system status events (issues, state changes)."""
             self.ha_event_mock(event)
 
         self._event_bus_unsubscribe_callbacks.append(
             central.event_bus.subscribe(
-                event_type=BackendSystemEventData, event_key=None, handler=_system_event_handler
+                event_type=DeviceLifecycleEvent, event_key=None, handler=_device_lifecycle_event_handler
             )
         )
         self._event_bus_unsubscribe_callbacks.append(
-            central.event_bus.subscribe(event_type=HomematicEvent, event_key=None, handler=_ha_event_handler)
+            central.event_bus.subscribe(
+                event_type=DataPointsCreatedEvent, event_key=None, handler=_data_points_created_event_handler
+            )
+        )
+        self._event_bus_unsubscribe_callbacks.append(
+            central.event_bus.subscribe(
+                event_type=DeviceTriggerEvent, event_key=None, handler=_device_trigger_event_handler
+            )
+        )
+        self._event_bus_unsubscribe_callbacks.append(
+            central.event_bus.subscribe(
+                event_type=SystemStatusChangedEvent, event_key=None, handler=_system_status_event_handler
+            )
         )
 
         assert central
@@ -223,14 +271,14 @@ async def get_central_client_factory(
         un_ignore_list=un_ignore_list,
     )
     central = await factory.get_default_central()
-    client = central.primary_client
+    client = central.client_coordinator.primary_client
     assert client
     try:
         yield central, client, factory
     finally:
-        factory.cleanup_event_bus_subscriptions()
+        factory.cleanup()
         await central.stop()
-        await central.clear_files()
+        await central.cache_coordinator.clear_all()
 
 
 async def get_pydev_ccu_central_unit_full(
@@ -241,9 +289,9 @@ async def get_pydev_ccu_central_unit_full(
     """Create and yield central, after all devices have been created."""
     device_event = asyncio.Event()
 
-    def system_event_handler(event: BackendSystemEventData) -> None:
-        """Handle backend system events."""
-        if event.system_event == BackendSystemEvent.DEVICES_CREATED:
+    def device_lifecycle_event_handler(event: DeviceLifecycleEvent) -> None:
+        """Handle device lifecycle events."""
+        if event.event_type == DeviceLifecycleEventType.CREATED:
             device_event.set()
 
     interface_configs = {
@@ -254,7 +302,7 @@ async def get_pydev_ccu_central_unit_full(
         )
     }
 
-    central = CentralConfig(
+    central = await CentralConfig(
         name=const.CENTRAL_NAME,
         host=const.CCU_HOST,
         username=const.CCU_USERNAME,
@@ -265,7 +313,7 @@ async def get_pydev_ccu_central_unit_full(
         program_markers=(),
         sysvar_markers=(),
     ).create_central()
-    central.event_bus.subscribe(event_type=BackendSystemEventData, event_key=None, handler=system_event_handler)
+    central.event_bus.subscribe(event_type=DeviceLifecycleEvent, event_key=None, handler=device_lifecycle_event_handler)
     await central.start()
 
     # Wait up to 60 seconds for the DEVICES_CREATED event which signals that all devices are available

aiohomematic_test_support/helper.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
 """Helpers for tests."""
 
 from __future__ import annotations
@@ -11,7 +13,7 @@ import orjson
 
 from aiohomematic.central import CentralUnit
 from aiohomematic.const import UTF_8
-from aiohomematic.interfaces.model import CustomDataPointProtocol
+from aiohomematic.interfaces import CustomDataPointProtocol
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -19,7 +21,7 @@ _LOGGER = logging.getLogger(__name__)
 # pylint: disable=protected-access
 
 
-def _load_json_file(anchor: str, resource: str, file_name: str) -> Any | None:
+def _load_json_file(anchor: str, resource: str, file_name: str) -> Any | None:  # kwonly: disable
     """Load json file from disk into dict."""
     package_path = str(importlib.resources.files(anchor))
     with open(
@@ -29,7 +31,7 @@ def _load_json_file(anchor: str, resource: str, file_name: str) -> Any | None:
         return orjson.loads(fptr.read())
 
 
-def get_prepared_custom_data_point(
+def get_prepared_custom_data_point(  # kwonly: disable
     central: CentralUnit, address: str, channel_no: int
 ) -> CustomDataPointProtocol | None:
     """Return the hm custom_data_point."""
@@ -40,7 +42,7 @@ def get_prepared_custom_data_point(
     return None
 
 
-def load_device_description(file_name: str) -> Any:
+def load_device_description(file_name: str) -> Any:  # kwonly: disable
     """Load device description."""
     dev_desc = _load_json_file(anchor="pydevccu", resource="device_descriptions", file_name=file_name)
     assert dev_desc