python-roborock 5.26.0__tar.gz → 5.27.0__tar.gz

{python_roborock-5.26.0 → python_roborock-5.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-roborock
-Version: 5.26.0
+Version: 5.27.0
 Summary: A package to control Roborock vacuums.
 Project-URL: Repository, https://github.com/python-roborock/python-roborock
 Project-URL: Documentation, https://python-roborock.readthedocs.io/

{python_roborock-5.26.0 → python_roborock-5.27.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "5.26.0"
+version = "5.27.0"
 description = "A package to control Roborock vacuums."
 authors = [{ name = "humbertogontijo", email = "humbertogontijo@users.noreply.github.com" }, {name="Lash-L"}, {name="allenporter"}]
 requires-python = ">=3.11, <4"

python_roborock-5.27.0/roborock/testing/__init__.py

@@ -0,0 +1,101 @@
+"""Testing fakes and simulators for python-roborock.
+
+This package provides stateful firmware simulators (e.g. `V1VacuumSimulator`),
+fake transport channels (`FakeChannel`), and cloud orchestration simulators (`FakeRoborockCloud`)
+to allow downstream consumers (such as Home Assistant integrations) to write high-fidelity
+integration tests using the real client library classes instead of fragile top-level mocks.
+
+Testing Architecture & Boundaries
+---------------------------------
+We fake communication at two boundaries:
+1.  **Network HTTP API Interception**: `FakeRoborockCloud.patch_device_manager()` routes
+    HTTP requests (such as discovery, login, home details) to custom mock endpoints using
+    `aioresponses` under the hood. No Python client methods are mocked; the real EAPI client
+    executes fully.
+2.  **Plaintext RPC Message Interception**: Device communication is intercepted at the
+    plaintext JSON RPC level (Layer 2). The real client classes (`V1Channel`, `MqttChannel`)
+    run under test, but their transport calls are intercepted by our stateful simulators.
+
+     ┌────────────────────────────────────────────────────────┐
+     │               TESTED CLIENT (REAL CODE)                │
+     │                                                        │
+     │  RoborockDevice / Traits / V1RpcChannel / V1Channel    │
+     └──────────────────────────┬─────────────────────────────┘
+                                │
+                      ROBOROCKMESSAGE PAYLOADS
+                      (Plaintext JSON commands)
+                                │
+     ┌──────────────────────────▼─────────────────────────────┐
+     │                 SIMULATOR (TEST FAKE)                  │
+     │                                                        │
+     │  FakeChannel (Intercepts publish/subscribe)            │
+     │  RoborockDeviceSimulator (Stateful firmware simulator) │
+     └────────────────────────────────────────────────────────┘
+
+Integration Usage Example
+-------------------------
+```python
+from roborock.testing import FakeRoborockCloud, V1VacuumSimulator
+
+async def test_start_vacuum_service():
+    # Setup cloud state and add a simulated vacuum device
+    cloud = FakeRoborockCloud()
+    fake_device = V1VacuumSimulator(duid="living_room_s7", battery=100, state=RoborockStateCode.charging)
+    cloud.add_device(fake_device)
+
+    # Patch channels and API calls using our cloud context manager
+    with cloud.patch_device_manager():
+        # Create the real client manager (logins and discovers natively via mock HTTP)
+        manager = await create_device_manager(
+            user_params=UserParams(username="test_user", user_data=USER_DATA),
+            cache=InMemoryCache(),
+        )
+
+    # Fetch the discovered device client
+    devices = await manager.get_devices()
+    device = devices[0]
+
+    # Trigger client start command
+    await device.v1_properties.command.send("app_start")
+
+    # Assert against the simulated vacuum state
+    assert fake_device.state == RoborockStateCode.cleaning
+```
+"""
+
+from roborock.testing.channel import FakeChannel
+from roborock.testing.cloud import FakeRoborockCloud, FakeWebApiClient
+from roborock.testing.simulator import (
+    DEFAULT_KEY_T,
+    DEFAULT_LOCAL_KEY,
+    DEFAULT_PRODUCT_ID,
+    RoborockDeviceSimulator,
+)
+from roborock.testing.v1_simulator import (
+    DEFAULT_APP_INIT,
+    DEFAULT_CLEAN_SUMMARY,
+    DEFAULT_CONSUMABLE,
+    DEFAULT_DND_TIMER,
+    DEFAULT_LAST_CLEAN_RECORD,
+    DEFAULT_NETWORK_INFO,
+    DEFAULT_STATUS,
+    V1VacuumSimulator,
+)
+
+__all__ = [
+    "DEFAULT_APP_INIT",
+    "DEFAULT_CLEAN_SUMMARY",
+    "DEFAULT_CONSUMABLE",
+    "DEFAULT_DND_TIMER",
+    "DEFAULT_KEY_T",
+    "DEFAULT_LAST_CLEAN_RECORD",
+    "DEFAULT_LOCAL_KEY",
+    "DEFAULT_NETWORK_INFO",
+    "DEFAULT_PRODUCT_ID",
+    "DEFAULT_STATUS",
+    "FakeChannel",
+    "FakeRoborockCloud",
+    "FakeWebApiClient",
+    "RoborockDeviceSimulator",
+    "V1VacuumSimulator",
+]

python_roborock-5.27.0/roborock/testing/channel.py

@@ -0,0 +1,126 @@
+"""Fake channel transport implementation for python-roborock.
+
+This module defines `FakeChannel`, which simulates low-level connection,
+subscription, and publishing logic at the message boundary. It acts as an
+in-memory replacement for `MqttChannel` and `LocalChannel` during testing.
+"""
+
+from collections.abc import Callable
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+from roborock.devices.transport.channel import Channel
+from roborock.mqtt.health_manager import HealthManager
+from roborock.protocols.v1_protocol import LocalProtocolVersion
+from roborock.roborock_message import RoborockMessage
+
+
+class FakeChannel(Channel):
+    """A stateful, in-memory transport simulator implementing the Channel protocol.
+
+    It captures all published messages in `published_messages`, maintains a registry
+    of active callbacks in `subscribers`, and enables tests or stateful simulators to
+    unconditionally push unsolicited messages using `notify_subscribers`.
+
+    Caller API
+    ----------
+    The public interface consists of `AsyncMock` / `MagicMock` attributes that
+    wrap internal implementations. Because they are mocks, callers can:
+
+    - **Inspect calls**: ``channel.publish.assert_called_once()``
+    - **Inject failures**: ``channel.publish.side_effect = RoborockException(...)``
+      to simulate transport errors on the next publish.
+    - **Replace behavior**: ``channel.connect.side_effect = my_custom_connect``
+      to substitute entirely custom logic.
+    - **Queue canned responses**: Append to ``channel.response_queue`` to have
+      the channel automatically deliver a response to subscribers on the next
+      publish (useful for low-level RPC request/response testing).
+    - **Push unsolicited messages**: Call ``channel.notify_subscribers(msg)``
+      to simulate the device broadcasting a state change.
+    """
+
+    subscribe: Any
+
+    def __init__(self, is_local: bool = False):
+        """Initialize the fake channel."""
+        self.subscribers: list[Callable[[RoborockMessage], None]] = []
+        self.published_messages: list[RoborockMessage] = []
+        self.response_queue: list[RoborockMessage] = []
+        self._is_connected = False
+        self._is_local = is_local
+
+        # Set this to an exception instance to make the next publish raise it.
+        # This is a convenience shortcut; callers can also replace
+        # ``publish.side_effect`` directly for more control.
+        self.publish_side_effect: Exception | None = None
+
+        # AsyncMock wrapping _publish. Callers can replace side_effect to
+        # inject transport errors, e.g.:
+        #   channel.publish.side_effect = RoborockException("timeout")
+        self.publish = AsyncMock(side_effect=self._publish)
+
+        # AsyncMock wrapping _subscribe. Callers can replace side_effect to
+        # simulate subscription failures, e.g.:
+        #   channel.subscribe.side_effect = RoborockException("sub failed")
+        self.subscribe = AsyncMock(side_effect=self._subscribe)  # type: ignore[assignment]
+
+        # AsyncMock wrapping _connect. Callers can replace side_effect to
+        # simulate connection failures, e.g.:
+        #   channel.connect.side_effect = RoborockException("refused")
+        self.connect = AsyncMock(side_effect=self._connect)
+
+        # MagicMock wrapping _close. Callers can assert close was called
+        # or inject errors on teardown.
+        self.close = MagicMock(side_effect=self._close)
+
+        self.protocol_version = LocalProtocolVersion.V1
+        self.restart = AsyncMock()
+        self.health_manager = HealthManager(self.restart)
+
+    async def _connect(self) -> None:
+        self._is_connected = True
+
+    def _close(self) -> None:
+        self._is_connected = False
+
+    @property
+    def is_connected(self) -> bool:
+        """Return true if connected."""
+        return self._is_connected
+
+    @property
+    def is_local_connected(self) -> bool:
+        """Return true if locally connected."""
+        return self._is_connected and self._is_local
+
+    async def _publish(self, message: RoborockMessage) -> None:
+        """Default publish implementation.
+
+        Records the message in ``published_messages`` and, if
+        ``response_queue`` is non-empty, pops the first response and
+        delivers it to all current subscribers (simulating a
+        request/response round-trip).
+        """
+        self.published_messages.append(message)
+        if self.publish_side_effect:
+            raise self.publish_side_effect
+        if self.response_queue:
+            response = self.response_queue.pop(0)
+            self.notify_subscribers(response)
+
+    async def _subscribe(self, callback: Callable[[RoborockMessage], None]) -> Callable[[], None]:
+        """Default subscribe implementation.
+
+        Registers the callback and returns an unsubscribe function.
+        """
+        self.subscribers.append(callback)
+        return lambda: self.subscribers.remove(callback)
+
+    def notify_subscribers(self, message: RoborockMessage) -> None:
+        """Deliver a message to all current subscribers.
+
+        Use this to simulate the channel receiving an unsolicited message
+        from the device (e.g. a state change broadcast).
+        """
+        for subscriber in list(self.subscribers):
+            subscriber(message)

python_roborock-5.27.0/roborock/testing/cloud.py

@@ -0,0 +1,247 @@
+"""Cloud environment simulator for python-roborock testing.
+
+This module provides `FakeRoborockCloud` which acts as a central registry
+for all simulated devices, dynamically faking HTTP endpoints via aioresponses
+to simulate physical devices connected to the Roborock Cloud.
+"""
+
+import contextlib
+import re
+from typing import Any
+from unittest.mock import AsyncMock, patch
+
+from aioresponses import CallbackResult, aioresponses
+
+from roborock.data import HomeData, Reference, RRiot, UserData
+from roborock.devices.rpc.v1_channel import create_v1_channel as original_create_v1_channel
+from roborock.devices.transport.mqtt_channel import create_mqtt_channel as original_create_mqtt_channel
+from roborock.testing.simulator import RoborockDeviceSimulator
+from roborock.testing.v1_simulator import V1VacuumSimulator
+
+# EAPI Base URL pattern constants
+IOT_API_BASE_URL = r"https://.*iot\.roborock\.com/api/v1"
+REST_API_BASE_URL = r"https://api-.*\.roborock\.com"
+
+DEFAULT_USER_DATA = UserData(
+    uid=123456,
+    tokentype="token_type",
+    token="abc123",
+    rruid="abc123",
+    region="us",
+    countrycode="1",
+    country="US",
+    nickname="user_nickname",
+    rriot=RRiot(
+        u="user123",
+        s="pass123",
+        h="unknown123",
+        k="qiCNieZa",
+        r=Reference(
+            r="US",
+            a="https://api-us.roborock.com",
+            l="https://wood-us.roborock.com",
+            m="tcp://mqtt-us.roborock.com:8883",
+        ),
+    ),
+)
+
+
+class FakeWebApiClient:
+    """Fakes the EAPI at the HTTP network boundary using aioresponses.
+
+    Exposes attributes that allow test suites (like Home Assistant) to easily
+    override response payloads, status codes, and simulate API errors.
+    """
+
+    def __init__(self, cloud: "FakeRoborockCloud"):
+        self.cloud = cloud
+        self.url_by_email_status = 200
+        self.url_by_email_payload: dict[str, Any] | None = None  # Synthesized if None
+        self.login_status = 200
+        self.login_payload: dict[str, Any] | None = None  # Synthesized if None
+        self.home_detail_status = 200
+        self.home_detail_payload: dict[str, Any] | None = None  # Synthesized if None
+        self.homes_status = 200
+        self.homes_payload_override: dict[str, Any] | None = None
+
+    def get_url_by_email_payload(self) -> dict[str, Any]:
+        """Synthesize getUrlByEmail payload."""
+        if self.url_by_email_payload is not None:
+            return self.url_by_email_payload
+        return {
+            "code": 200,
+            "data": {
+                "country": self.cloud.user_data.country,
+                "countrycode": self.cloud.user_data.countrycode,
+                "url": f"https://{self.cloud.user_data.region}iot.roborock.com",
+            },
+            "msg": "success",
+        }
+
+    def get_login_payload(self) -> dict[str, Any]:
+        """Synthesize login payload using the cloud user profile state."""
+        if self.login_payload is not None:
+            return self.login_payload
+        return {
+            "code": 200,
+            "data": self.cloud.user_data.as_dict(),
+            "msg": "success",
+        }
+
+    def get_home_detail_payload(self) -> dict[str, Any]:
+        """Synthesize getHomeDetail payload using the cloud home state."""
+        if self.home_detail_payload is not None:
+            return self.home_detail_payload
+        return {
+            "code": 200,
+            "data": {
+                "deviceListOrder": None,
+                "id": self.cloud.home_id,
+                "name": self.cloud.home_name,
+                "rrHomeId": self.cloud.home_id,
+                "tuyaHomeId": 0,
+            },
+            "msg": "success",
+        }
+
+    def mock_requests(self, mocked: aioresponses) -> None:
+        """Register EAPI endpoint mocks with aioresponses."""
+        # getUrlByEmail Endpoint Mocking
+        mocked.post(
+            re.compile(rf"{IOT_API_BASE_URL}/getUrlByEmail.*"),
+            status=self.url_by_email_status,
+            payload=self.get_url_by_email_payload(),
+        )
+
+        # User Logins Endpoint Mocking
+        mocked.post(
+            re.compile(rf"{IOT_API_BASE_URL}/login.*"),
+            status=self.login_status,
+            payload=self.get_login_payload(),
+        )
+        mocked.post(
+            re.compile(rf"{IOT_API_BASE_URL}/loginWithCode.*"),
+            status=self.login_status,
+            payload=self.get_login_payload(),
+        )
+
+        # getHomeDetail Endpoint Mocking
+        mocked.get(
+            re.compile(rf"{IOT_API_BASE_URL}/getHomeDetail.*"),
+            status=self.home_detail_status,
+            payload=self.get_home_detail_payload(),
+        )
+
+        # Dynamic homes response callback wrapper
+        def get_homes_callback(url, **kwargs):
+            if self.homes_status != 200 or self.homes_payload_override is not None:
+                return CallbackResult(
+                    status=self.homes_status,
+                    payload=self.homes_payload_override,
+                )
+
+            devices = []
+            products = []
+            for server in self.cloud.simulated_devices.values():
+                devices.append(server.device_info)
+                products.append(server.product)
+
+            home_data = HomeData(
+                id=self.cloud.home_id,
+                name=self.cloud.home_name,
+                devices=devices,
+                products=products,
+            )
+            return CallbackResult(
+                status=200,
+                payload={
+                    "api": None,
+                    "code": 200,
+                    "result": home_data.as_dict(),
+                    "status": "ok",
+                    "success": True,
+                },
+            )
+
+        # getHomeDetail v2 & v3 callbacks routing
+        mocked.get(
+            re.compile(rf"{REST_API_BASE_URL}/v2/user/homes/{self.cloud.home_id}"),
+            callback=get_homes_callback,
+        )
+        mocked.get(
+            re.compile(rf"{REST_API_BASE_URL}/v3/user/homes/{self.cloud.home_id}"),
+            callback=get_homes_callback,
+        )
+
+
+class FakeRoborockCloud:
+    """A central state object representing the Roborock Cloud environment under test."""
+
+    def __init__(
+        self,
+        user_data: UserData | None = None,
+        home_id: int = 123456,
+        home_name: str = "Fake Home",
+    ) -> None:
+        self.simulated_devices: dict[str, RoborockDeviceSimulator] = {}
+        self.user_data = user_data or DEFAULT_USER_DATA
+        self.home_id = home_id
+        self.home_name = home_name
+        self.web_api = FakeWebApiClient(self)
+
+    def add_device(self, server: RoborockDeviceSimulator) -> None:
+        """Register a stateful device simulator in the cloud registry."""
+        self.simulated_devices[server.duid] = server
+
+    @contextlib.contextmanager
+    def patch_device_manager(self):
+        """Context manager to patch create_v1_channel and create_mqtt_channel.
+
+        This automatically routes communications to the registered device simulators
+        and intercepts HTTP calls at the network boundary using aioresponses.
+        """
+
+        # Wrapper function for create_v1_channel
+        def mock_create_v1_channel(user_data, mqtt_params, mqtt_session, device, device_cache):
+            if device.pv in ("A01", "B01"):
+                raise NotImplementedError(
+                    f"Simulating protocol {device.pv} is not yet supported. "
+                    "TODO: Implement stateful simulators for B01 (Q7/Q10) and A01 (Zeo/Dyad) devices."
+                )
+            server = self.simulated_devices.get(device.duid)
+            if server is not None:
+                if not isinstance(server, V1VacuumSimulator):
+                    raise TypeError(
+                        f"Device '{device.duid}' is registered with a {type(server).__name__} "
+                        f"simulator, but create_v1_channel requires a V1VacuumSimulator."
+                    )
+                return server.v1_channel
+            return original_create_v1_channel(user_data, mqtt_params, mqtt_session, device, device_cache)
+
+        # Wrapper function for create_mqtt_channel
+        def mock_create_mqtt_channel(user_data, mqtt_params, mqtt_session, device):
+            if device.pv in ("A01", "B01"):
+                raise NotImplementedError(
+                    f"Simulating protocol {device.pv} is not yet supported. "
+                    "TODO: Implement stateful simulators for B01 (Q7/Q10) and A01 (Zeo/Dyad) devices."
+                )
+            server = self.simulated_devices.get(device.duid)
+            if server:
+                return server.mqtt_channel
+            return original_create_mqtt_channel(user_data, mqtt_params, mqtt_session, device)
+
+        # Route Web requests using the dynamic FakeWebApiClient
+        with aioresponses() as mocked:
+            self.web_api.mock_requests(mocked)
+
+            # Patch Channel factories and rate limiters
+            with (
+                patch(
+                    "roborock.web_api.RoborockApiClient._login_limiter.try_acquire_async",
+                    new=AsyncMock(return_value=True),
+                ),
+                patch("roborock.web_api.RoborockApiClient._home_data_limiter.try_acquire", return_value=True),
+                patch("roborock.devices.device_manager.create_v1_channel", side_effect=mock_create_v1_channel),
+                patch("roborock.devices.device_manager.create_mqtt_channel", side_effect=mock_create_mqtt_channel),
+            ):
+                yield

python_roborock-5.27.0/roborock/testing/simulator.py

@@ -0,0 +1,110 @@
+"""Base stateful device firmware simulator for python-roborock testing.
+
+This module defines `RoborockDeviceSimulator` which intercepts plaintext JSON RPC messages
+sent over simulated channels, process them through a local state engine, update internal
+variables, and write responses back to client subscribers.
+"""
+
+import logging
+
+from roborock.data import HomeDataDevice, HomeDataProduct, RoborockCategory
+from roborock.roborock_message import RoborockMessage
+from roborock.testing.channel import FakeChannel
+
+_LOGGER = logging.getLogger(__name__)
+
+# Shared authentication key constants
+DEFAULT_LOCAL_KEY = "fake_localkey_16bytes"
+DEFAULT_KEY_T = "qiCNieZa"
+DEFAULT_PRODUCT_ID = "product-id-123"
+
+
+class RoborockDeviceSimulator:
+    """Base class for stateful device firmware simulators.
+
+    It sets up an MQTT fake transport channel (and optionally a local channel),
+    intercepts published requests, and routes them to `_handle_publish` to
+    simulate real device response.
+
+    Not all protocols support local connections. V1 devices use both MQTT and
+    local channels, while A01/B01 devices use MQTT only. Subclasses that need
+    a local channel should set ``has_local_channel=True`` (the default for
+    backward compatibility with V1 simulators).
+
+    Caller API
+    ----------
+    Subclasses (like ``RoborockVacuumSimulator``) provide the high-level
+    interface (state attributes, ``trigger_push_update()``, etc.), but callers
+    can also reach into the underlying channels for low-level inspection:
+
+    - **Inspect published messages**: ``simulator.mqtt_channel.published_messages``
+      (and ``simulator.local_channel.published_messages`` for V1) contain every
+      ``RoborockMessage`` that the client sent through each transport.
+    - **Inject transport failures**: Set
+      ``simulator.mqtt_channel.publish_side_effect = RoborockException(...)``
+      to make the next publish raise, simulating a network error.
+    - **Modify device identity**: Override ``simulator.device_info`` or
+      ``simulator.product`` before registering with ``FakeRoborockCloud`` to
+      control the device metadata returned during discovery.
+    """
+
+    def __init__(
+        self,
+        duid: str = "fake_duid",
+        device_info: HomeDataDevice | None = None,
+        product: HomeDataProduct | None = None,
+        has_local_channel: bool = True,
+    ):
+        self.duid = duid
+        self.product = product or HomeDataProduct(
+            id=DEFAULT_PRODUCT_ID,
+            name="Roborock Vacuum",
+            model="roborock.vacuum.s7",
+            category=RoborockCategory.VACUUM,
+        )
+        self.device_info = device_info or HomeDataDevice(
+            duid=self.duid,
+            name=f"Vacuum {self.duid}",
+            local_key=DEFAULT_LOCAL_KEY,
+            product_id=self.product.id,
+            sn="fake_serial_number",
+            pv="1.0",
+        )
+
+        # MQTT channel is always present — all protocols use it.
+        self.mqtt_channel = FakeChannel(is_local=False)
+        self.mqtt_channel.publish.side_effect = self._handle_mqtt_publish
+
+        # Local channel is only used by V1 devices. A01/B01 (MQTT-only)
+        # simulators should pass has_local_channel=False.
+        self.local_channel: FakeChannel | None = None
+        if has_local_channel:
+            self.local_channel = FakeChannel(is_local=True)
+            self.local_channel.publish.side_effect = self._handle_local_publish
+
+    async def _handle_local_publish(self, message: RoborockMessage) -> None:
+        assert self.local_channel is not None
+        self.local_channel.published_messages.append(message)
+        if self.local_channel.publish_side_effect:
+            raise self.local_channel.publish_side_effect
+        await self._handle_publish(message, self.local_channel)
+
+    async def _handle_mqtt_publish(self, message: RoborockMessage) -> None:
+        self.mqtt_channel.published_messages.append(message)
+        if self.mqtt_channel.publish_side_effect:
+            raise self.mqtt_channel.publish_side_effect
+        await self._handle_publish(message, self.mqtt_channel)
+
+    async def _handle_publish(self, message: RoborockMessage, channel: FakeChannel) -> None:
+        """To be overridden by subclasses to route commands."""
+        raise NotImplementedError("Subclasses must implement _handle_publish")
+
+    def connect(self) -> None:
+        if self.local_channel is not None:
+            self.local_channel._is_connected = True
+        self.mqtt_channel._is_connected = True
+
+    def close(self) -> None:
+        if self.local_channel is not None:
+            self.local_channel._is_connected = False
+        self.mqtt_channel._is_connected = False