Coverage for faststream/mqtt/testing.py: 93%
96 statements
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-17 21:20 +0000
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-17 21:20 +0000
1import asyncio
2from collections.abc import Generator, Iterable, Sequence
3from contextlib import contextmanager
4from typing import TYPE_CHECKING, Any, Optional, cast, overload
5from unittest.mock import MagicMock
7import anyio
8import zmqtt
9from typing_extensions import override
10from zmqtt import topic_matches
12from faststream._internal.endpoint.utils import ParserComposition
13from faststream._internal.parser import DefaultCodec
14from faststream._internal.testing.broker import (
15 EnterType,
16 TestBroker,
17 change_producer,
18)
19from faststream.exceptions import SubscriberNotFound
20from faststream.mqtt.broker.broker import MQTTBroker
21from faststream.mqtt.parser import MQTTVersion, parser_for
22from faststream.mqtt.publisher.producer import ZmqttBaseProducer
23from faststream.mqtt.response import MQTTPublishCommand
25if TYPE_CHECKING:
26 from fast_depends.library.serializer import SerializerProto
28 from faststream._internal.basic_types import SendableMessage
29 from faststream._internal.parser import CodecProto
30 from faststream.mqtt.publisher.usecase import MQTTPublisher
31 from faststream.mqtt.subscriber.usecase import MQTTBaseSubscriber
33__all__ = ("TestMQTTBroker",)
36class _BlockingSubscription:
37 """Fake zmqtt.Subscription that blocks forever on iteration.
39 Used by ``TestMQTTBroker`` so dynamic subscribers can call
40 ``start()`` without a real MQTT connection. Message routing
41 happens through ``FakeProducer``, not through this iterator.
42 """
44 async def start(self) -> None:
45 pass
47 async def stop(self) -> None:
48 pass
50 def __aiter__(self) -> "_BlockingSubscription":
51 return self
53 async def __anext__(self) -> zmqtt.Message:
54 # Block until the task is cancelled (i.e. subscriber.stop() is called)
55 await asyncio.sleep(1e9)
56 raise StopAsyncIteration # pragma: no cover
59def mqtt_topic_matches(pattern: str, topic: str) -> bool:
60 return topic_matches(pattern, topic)
63def _broker_version(broker: MQTTBroker) -> MQTTVersion:
64 return getattr(broker.config.broker_config, "version", "5.0")
67class TestMQTTBroker(
68 TestBroker[MQTTBroker, EnterType],
69 broker=MQTTBroker,
70):
71 """In-memory test double for MQTTBroker.
73 Routes published messages to matching subscribers without a real
74 MQTT connection, using MQTT wildcard rules for topic matching.
75 Messages are encoded in the same wire format as the configured
76 broker version (V311 envelope or V5 PublishProperties).
78 Usage::
80 async with TestMQTTBroker(broker) as br:
81 await br.publish("hello", "sensors/temp")
82 handler.mock.assert_called_once_with("hello")
83 """
85 @overload
86 def __init__(
87 self: "TestMQTTBroker[MQTTBroker]",
88 broker: MQTTBroker,
89 /,
90 *,
91 with_real: bool = False,
92 connect_only: bool | None = None,
93 ) -> None: ...
95 @overload
96 def __init__(
97 self: "TestMQTTBroker[tuple[MQTTBroker, ...]]",
98 *brokers: MQTTBroker,
99 with_real: bool = False,
100 connect_only: bool | None = None,
101 ) -> None: ...
103 def __init__(
104 self,
105 *brokers: MQTTBroker,
106 with_real: bool = False,
107 connect_only: bool | None = None,
108 ) -> None:
109 super().__init__(
110 *brokers,
111 with_real=with_real,
112 connect_only=connect_only,
113 )
115 def create_publisher_fake_subscriber(
116 self,
117 broker: MQTTBroker,
118 publisher: "MQTTPublisher",
119 ) -> tuple["MQTTBaseSubscriber", bool]:
120 sub: MQTTBaseSubscriber | None = None
121 for handler in (s for b in self.brokers for s in b.subscribers):
122 handler = cast("MQTTBaseSubscriber", handler)
123 if mqtt_topic_matches(handler.topic, publisher.topic):
124 sub = handler
125 break
127 if sub is None:
128 is_real = False
129 sub = broker.subscriber(publisher.topic, persistent=False)
130 # Apply the correct version parser so fake subs match FakeProducer output.
131 parser = sub._build_parser()
132 sub._parser = parser.parse_message
133 sub._decoder = parser.decode_message
134 else:
135 is_real = True
137 return sub, is_real
139 def _fake_start(self, broker: MQTTBroker, *args: Any, **kwargs: Any) -> None:
140 # Ensure all pre-existing subscribers use the version-correct parser
141 # (preserving each subscriber's own path_regex) before patch_broker_calls
142 # builds the fastdepends model.
143 for sub in cast("list[MQTTBaseSubscriber]", broker.subscribers):
144 parser = sub._build_parser()
145 sub._parser = parser.parse_message
146 sub._decoder = parser.decode_message
147 super()._fake_start(broker, *args, **kwargs)
149 @contextmanager
150 def _patch_producer(self, broker: MQTTBroker) -> Generator[None, None, None]:
151 fake_producer = FakeProducer(broker, self.brokers)
152 with change_producer(broker.config.broker_config, fake_producer):
153 yield
155 @override
156 async def _fake_connect( # type: ignore[override]
157 self,
158 broker: MQTTBroker,
159 *args: Any,
160 **kwargs: Any,
161 ) -> MagicMock:
162 fake_client = MagicMock()
163 fake_client.subscribe.return_value = _BlockingSubscription()
164 # Wire fake client into config so that dynamically-added subscribers
165 # can call start() without a real MQTT connection.
166 broker.config.broker_config._client = fake_client
167 return fake_client
170class FakeProducer(ZmqttBaseProducer):
171 """In-memory producer that routes messages directly to matching subscribers.
173 Encodes messages in the wire format matching the broker's configured
174 MQTT version: V311 envelope for 3.1.1, PublishProperties for 5.0.
175 """
177 def __init__(
178 self,
179 broker: MQTTBroker,
180 brokers: Sequence[MQTTBroker],
181 ) -> None:
182 self.broker = broker
183 self.brokers = brokers
184 self.serializer: SerializerProto | None = None
186 version = _broker_version(broker)
187 default = parser_for(version)()
188 self._parser = ParserComposition(broker._parser, default.parse_message)
189 self._decoder = ParserComposition(broker._decoder, default.decode_message)
190 self.codec = broker.config.broker_codec or DefaultCodec()
192 @property
193 def subscribers(self) -> Iterable["MQTTBaseSubscriber"]:
194 return (
195 cast("MQTTBaseSubscriber", s) for b in self.brokers for s in b.subscribers
196 )
198 @property
199 def _version(self) -> MQTTVersion:
200 return _broker_version(self.broker)
202 @override
203 async def publish(self, cmd: MQTTPublishCommand) -> None:
204 msg = await build_message(
205 message=cmd.body,
206 topic=cmd.destination,
207 version=self._version,
208 qos=cmd.qos,
209 retain=cmd.retain,
210 reply_to=cmd.reply_to,
211 correlation_id=cmd.correlation_id,
212 headers=cmd.headers,
213 serializer=self.broker.config.fd_config._serializer,
214 codec=self.codec,
215 )
217 # For shared subscriptions, only deliver to one subscriber per group
218 seen_shared_groups: set[str] = set()
220 for handler in self.subscribers:
221 handler_topic = handler.topic
222 if not mqtt_topic_matches(handler_topic, cmd.destination):
223 continue
225 if handler_topic.startswith("$share/"):
226 _, group, _ = handler_topic.split("/", 2)
227 if group in seen_shared_groups: 227 ↛ 228line 227 didn't jump to line 228 because the condition on line 227 was never true
228 continue
229 seen_shared_groups.add(group)
231 await handler.process_message(msg)
233 @override
234 async def request(self, cmd: MQTTPublishCommand) -> "zmqtt.Message":
235 msg = await build_message(
236 message=cmd.body,
237 topic=cmd.destination,
238 version=self._version,
239 qos=cmd.qos,
240 retain=cmd.retain,
241 correlation_id=cmd.correlation_id,
242 headers=cmd.headers,
243 serializer=self.broker.config.fd_config._serializer,
244 codec=self.codec,
245 )
247 for handler in self.subscribers: 247 ↛ 264line 247 didn't jump to line 264 because the loop on line 247 didn't complete
248 if not mqtt_topic_matches(handler.topic, cmd.destination):
249 continue
251 with anyio.fail_after(cmd.timeout or 30.0):
252 result = await handler.process_message(msg)
254 return await build_message(
255 message=result.body,
256 topic=cmd.destination,
257 version=self._version,
258 correlation_id=result.correlation_id,
259 headers=result.headers,
260 serializer=self.broker.config.fd_config._serializer,
261 codec=self.codec,
262 )
264 raise SubscriberNotFound
267async def build_message(
268 message: "SendableMessage",
269 topic: str,
270 *,
271 version: MQTTVersion = "5.0",
272 qos: int = 0,
273 retain: bool = False,
274 reply_to: str = "",
275 correlation_id: str | None = None,
276 headers: dict[str, str] | None = None,
277 serializer: Optional["SerializerProto"] = None,
278 codec: Optional["CodecProto"] = None,
279) -> zmqtt.Message:
280 """Build a fake ``zmqtt.Message`` from publish parameters.
282 For MQTT 5.0 uses *PublishProperties* to carry metadata so that
283 ``MQTTParserV5`` can extract them transparently.
284 For MQTT 3.1.1 returns a plain message with raw payload only.
285 """
286 if codec is None: 286 ↛ 287line 286 didn't jump to line 287 because the condition on line 286 was never true
287 codec = DefaultCodec()
288 payload, content_type = await codec.encode(message, serializer=serializer)
290 if version == "3.1.1":
291 return zmqtt.Message(
292 topic=topic,
293 payload=payload,
294 qos=zmqtt.QoS(qos),
295 retain=retain,
296 )
298 user_props: list[tuple[str, str]] = list((headers or {}).items())
300 properties = zmqtt.PublishProperties(
301 content_type=content_type or None,
302 response_topic=reply_to or None,
303 correlation_data=correlation_id.encode() if correlation_id else None,
304 user_properties=tuple(user_props),
305 )
307 return zmqtt.Message(
308 topic=topic,
309 payload=payload,
310 qos=zmqtt.QoS(qos),
311 retain=retain,
312 properties=properties,
313 )