aiohomematic-test-support 2025.12.51__tar.gz → 2025.12.54__tar.gz

{aiohomematic_test_support-2025.12.51/aiohomematic_test_support.egg-info → aiohomematic_test_support-2025.12.54}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiohomematic-test-support
-Version: 2025.12.51
+Version: 2025.12.54
 Summary: Support-only package for AioHomematic (tests/dev). Not part of production builds.
 Author-email: SukramJ <sukramj@icloud.com>, Daniel Perna <danielperna84@gmail.com>
 Project-URL: Homepage, https://github.com/SukramJ/aiohomematic

{aiohomematic_test_support-2025.12.51 → aiohomematic_test_support-2025.12.54}/__init__.py

@@ -18,6 +18,8 @@ Key Components
   playback support for deterministic testing.
 - **helper**: Test helper utilities for common testing operations.
 - **const**: Test-specific constants and configuration values.
+- **event_capture**: Event capture and assertion utilities for behavior testing.
+- **event_mock**: Event-driven mock server for test triggers.
 
 Usage Example
 -------------
@@ -35,6 +37,33 @@ Using the factory to create a test central with session playback:
     device = central.device_coordinator.get_device_by_address("VCU0000001")
     await central.stop()
 
+Using EventCapture for behavior-focused testing:
+
+    from aiohomematic_test_support.event_capture import EventCapture
+    from aiohomematic.central.event_bus import CircuitBreakerTrippedEvent
+
+    capture = EventCapture()
+    capture.subscribe_to(central.event_bus, CircuitBreakerTrippedEvent)
+
+    # ... trigger failures ...
+
+    capture.assert_event_emitted(CircuitBreakerTrippedEvent, failure_count=5)
+    capture.cleanup()
+
+Using EventDrivenMockServer for event-triggered test behavior:
+
+    from aiohomematic_test_support.event_mock import EventDrivenMockServer
+    from aiohomematic.central.event_bus import DataRefreshTriggeredEvent
+
+    mock_server = EventDrivenMockServer(event_bus=central.event_bus)
+    mock_server.when(DataRefreshTriggeredEvent).then_call(
+        lambda event: inject_mock_data()
+    )
+
+    # ... trigger refresh ...
+
+    mock_server.cleanup()
+
 The session player replays pre-recorded backend responses, enabling fast and
 reproducible tests without backend dependencies.
 
@@ -47,4 +76,4 @@ test dependencies to access test support functionality.
 
 from __future__ import annotations
 
-__version__ = "2025.12.51"
+__version__ = "2025.12.54"

{aiohomematic_test_support-2025.12.51 → aiohomematic_test_support-2025.12.54/aiohomematic_test_support.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiohomematic-test-support
-Version: 2025.12.51
+Version: 2025.12.54
 Summary: Support-only package for AioHomematic (tests/dev). Not part of production builds.
 Author-email: SukramJ <sukramj@icloud.com>, Daniel Perna <danielperna84@gmail.com>
 Project-URL: Homepage, https://github.com/SukramJ/aiohomematic

{aiohomematic_test_support-2025.12.51 → aiohomematic_test_support-2025.12.54}/aiohomematic_test_support.egg-info/SOURCES.txt

@@ -2,6 +2,8 @@ MANIFEST.in
 README.md
 __init__.py
 const.py
+event_capture.py
+event_mock.py
 factory.py
 helper.py
 mock.py
@@ -9,6 +11,8 @@ py.typed
 pyproject.toml
 ./__init__.py
 ./const.py
+./event_capture.py
+./event_mock.py
 ./factory.py
 ./helper.py
 ./mock.py

aiohomematic_test_support-2025.12.54/event_capture.py

@@ -0,0 +1,256 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""
+Event capture utilities for test verification.
+
+This module provides tools for capturing and asserting events in tests,
+enabling behavior-focused testing through event verification.
+
+Public API
+----------
+- EventCapture: Capture events for test verification
+- EventSequenceAssertion: Verify event ordering
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, TypeVar
+
+if TYPE_CHECKING:
+    from aiohomematic.central.event_bus import Event, EventBus
+
+T = TypeVar("T", bound="Event")
+
+
+@dataclass
+class EventCapture:
+    """
+    Capture events from EventBus for test verification.
+
+    Provides methods to subscribe to events, capture them, and make assertions
+    about what events were emitted during test execution.
+
+    Example:
+    -------
+        capture = EventCapture()
+        capture.subscribe_to(event_bus, CircuitBreakerTrippedEvent)
+
+        # ... perform test actions ...
+
+        capture.assert_event_emitted(
+            CircuitBreakerTrippedEvent,
+            interface_id="test",
+            failure_count=5,
+        )
+        capture.cleanup()
+
+    """
+
+    captured_events: list[Event] = field(default_factory=list)
+    """List of all captured events."""
+
+    _unsubscribers: list[Callable[[], None]] = field(default_factory=list)
+    """Unsubscribe callbacks for cleanup."""
+
+    def assert_event_emitted(
+        self,
+        *,
+        event_type: type[Event],
+        count: int | None = None,
+        **expected_attrs: Any,
+    ) -> None:
+        """
+        Assert that an event with specific attributes was emitted.
+
+        Args:
+            event_type: The expected event type
+            count: If provided, assert exactly this many events were emitted
+            **expected_attrs: Expected attribute values on the event
+
+        Raises:
+            AssertionError: If no matching event found or count mismatch
+
+        """
+        events = self.get_events_of_type(event_type=event_type)
+
+        if count is not None and len(events) != count:
+            raise AssertionError(f"Expected {count} {event_type.__name__} events, got {len(events)}")
+
+        if not expected_attrs:
+            if not events:
+                raise AssertionError(f"No {event_type.__name__} events captured")
+            return
+
+        for event in events:
+            if all(getattr(event, k, None) == v for k, v in expected_attrs.items()):
+                return
+
+        raise AssertionError(
+            f"No {event_type.__name__} found with attributes {expected_attrs}. Captured {len(events)} events: {events}"
+        )
+
+    def assert_no_event(self, *, event_type: type[Event]) -> None:
+        """
+        Assert that no events of a specific type were emitted.
+
+        Args:
+            event_type: The event type that should not exist
+
+        Raises:
+            AssertionError: If any events of that type were captured
+
+        """
+        if events := self.get_events_of_type(event_type=event_type):
+            raise AssertionError(f"Expected no {event_type.__name__} events, but found {len(events)}: {events}")
+
+    def cleanup(self) -> None:
+        """Unsubscribe from all events and clear captured events."""
+        for unsub in self._unsubscribers:
+            unsub()
+        self._unsubscribers.clear()
+        self.captured_events.clear()
+
+    def clear(self) -> None:
+        """Clear all captured events."""
+        self.captured_events.clear()
+
+    def get_event_count(self, *, event_type: type[Event]) -> int:
+        """
+        Return count of captured events of a specific type.
+
+        Args:
+            event_type: The event type to count
+
+        Returns:
+            Number of events of that type
+
+        """
+        return len(self.get_events_of_type(event_type=event_type))
+
+    def get_events_of_type(self, *, event_type: type[T]) -> list[T]:
+        """
+        Return all captured events of a specific type.
+
+        Args:
+            event_type: The event type to filter by
+
+        Returns:
+            List of events matching the type
+
+        """
+        return [e for e in self.captured_events if isinstance(e, event_type)]
+
+    def subscribe_to(self, event_bus: EventBus, *event_types: type[Event]) -> None:
+        """
+        Subscribe to specific event types on the EventBus.
+
+        Args:
+            event_bus: The EventBus to subscribe to
+            *event_types: Event types to capture
+
+        """
+        for event_type in event_types:
+            unsubscribe = event_bus.subscribe(
+                event_type=event_type,
+                event_key=None,
+                handler=self._capture_handler,
+            )
+            self._unsubscribers.append(unsubscribe)
+
+    def _capture_handler(self, *, event: Event) -> None:
+        """Handle event by capturing it."""
+        self.captured_events.append(event)
+
+
+@dataclass
+class EventSequenceAssertion:
+    """
+    Assert events occur in expected sequence.
+
+    Useful for verifying state machine transitions and multi-step processes.
+
+    Example:
+    -------
+        sequence = EventSequenceAssertion(expected_sequence=[
+            ConnectionStageChangedEvent,
+            ClientStateChangedEvent,
+            CentralStateChangedEvent,
+        ])
+        event_bus.subscribe(Event, sequence.on_event)
+
+        # ... perform actions ...
+
+        sequence.verify()
+
+    """
+
+    expected_sequence: list[type[Event]]
+    """The expected sequence of event types."""
+
+    captured_types: list[type[Event]] = field(default_factory=list)
+    """Captured event types in order."""
+
+    def on_event(self, *, event: Event) -> None:
+        """
+        Handle event by capturing its type.
+
+        Args:
+            event: The event that was published
+
+        """
+        self.captured_types.append(type(event))
+
+    def reset(self) -> None:
+        """Reset captured types for reuse."""
+        self.captured_types.clear()
+
+    def verify(self, *, strict: bool = False) -> None:
+        """
+        Verify the captured sequence matches expected.
+
+        Args:
+            strict: If True, require exact sequence match.
+                    If False, verify expected events appear in order
+                    (other events may be interspersed).
+
+        Raises:
+            AssertionError: If sequence doesn't match
+
+        """
+        if strict:
+            self._verify_strict()
+        else:
+            self._verify_subsequence()
+
+    def _verify_strict(self) -> None:
+        """Verify exact sequence match."""
+        if len(self.captured_types) != len(self.expected_sequence):
+            raise AssertionError(
+                f"Expected {len(self.expected_sequence)} events, "
+                f"got {len(self.captured_types)}.\n"
+                f"Expected: {[e.__name__ for e in self.expected_sequence]}\n"
+                f"Got: {[e.__name__ for e in self.captured_types]}"
+            )
+
+        for i, (expected, actual) in enumerate(zip(self.expected_sequence, self.captured_types, strict=True)):
+            if expected != actual:
+                raise AssertionError(f"Event {i}: expected {expected.__name__}, got {actual.__name__}")
+
+    def _verify_subsequence(self) -> None:
+        """Verify expected events appear in order (non-strict)."""
+        expected_idx = 0
+        for actual_type in self.captured_types:
+            if expected_idx >= len(self.expected_sequence):
+                break
+            if actual_type == self.expected_sequence[expected_idx]:
+                expected_idx += 1
+
+        if expected_idx < len(self.expected_sequence):
+            missing = self.expected_sequence[expected_idx:]
+            raise AssertionError(
+                f"Missing expected events in sequence: {[e.__name__ for e in missing]}\n"
+                f"Expected: {[e.__name__ for e in self.expected_sequence]}\n"
+                f"Got: {[e.__name__ for e in self.captured_types]}"
+            )

aiohomematic_test_support-2025.12.54/event_mock.py

@@ -0,0 +1,300 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""
+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.event_bus 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-2025.12.51 → aiohomematic_test_support-2025.12.54}/factory.py

@@ -48,7 +48,7 @@ from aiohomematic.central.integration_events import (
     DeviceLifecycleEvent,
     DeviceLifecycleEventType,
     DeviceTriggerEvent,
-    SystemStatusEvent,
+    SystemStatusChangedEvent,
 )
 from aiohomematic.client import ClientConfig, InterfaceConfig
 from aiohomematic.const import LOCAL_HOST, Interface, OptionalSettings
@@ -171,7 +171,7 @@ class FactoryWithClient:
             """Handle device trigger events."""
             self.ha_event_mock(event)
 
-        def _system_status_event_handler(event: SystemStatusEvent) -> None:
+        def _system_status_event_handler(event: SystemStatusChangedEvent) -> None:
             """Handle system status events (issues, state changes)."""
             self.ha_event_mock(event)
 
@@ -192,7 +192,7 @@ class FactoryWithClient:
         )
         self._event_bus_unsubscribe_callbacks.append(
             central.event_bus.subscribe(
-                event_type=SystemStatusEvent, event_key=None, handler=_system_status_event_handler
+                event_type=SystemStatusChangedEvent, event_key=None, handler=_system_status_event_handler
             )
         )