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

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 

6 

7import anyio 

8import zmqtt 

9from typing_extensions import override 

10from zmqtt import topic_matches 

11 

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 

24 

25if TYPE_CHECKING: 

26 from fast_depends.library.serializer import SerializerProto 

27 

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 

32 

33__all__ = ("TestMQTTBroker",) 

34 

35 

36class _BlockingSubscription: 

37 """Fake zmqtt.Subscription that blocks forever on iteration. 

38 

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 """ 

43 

44 async def start(self) -> None: 

45 pass 

46 

47 async def stop(self) -> None: 

48 pass 

49 

50 def __aiter__(self) -> "_BlockingSubscription": 

51 return self 

52 

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 

57 

58 

59def mqtt_topic_matches(pattern: str, topic: str) -> bool: 

60 return topic_matches(pattern, topic) 

61 

62 

63def _broker_version(broker: MQTTBroker) -> MQTTVersion: 

64 return getattr(broker.config.broker_config, "version", "5.0") 

65 

66 

67class TestMQTTBroker( 

68 TestBroker[MQTTBroker, EnterType], 

69 broker=MQTTBroker, 

70): 

71 """In-memory test double for MQTTBroker. 

72 

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). 

77 

78 Usage:: 

79 

80 async with TestMQTTBroker(broker) as br: 

81 await br.publish("hello", "sensors/temp") 

82 handler.mock.assert_called_once_with("hello") 

83 """ 

84 

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: ... 

94 

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: ... 

102 

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 ) 

114 

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 

126 

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 

136 

137 return sub, is_real 

138 

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) 

148 

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 

154 

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 

168 

169 

170class FakeProducer(ZmqttBaseProducer): 

171 """In-memory producer that routes messages directly to matching subscribers. 

172 

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 """ 

176 

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 

185 

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() 

191 

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 ) 

197 

198 @property 

199 def _version(self) -> MQTTVersion: 

200 return _broker_version(self.broker) 

201 

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 ) 

216 

217 # For shared subscriptions, only deliver to one subscriber per group 

218 seen_shared_groups: set[str] = set() 

219 

220 for handler in self.subscribers: 

221 handler_topic = handler.topic 

222 if not mqtt_topic_matches(handler_topic, cmd.destination): 

223 continue 

224 

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) 

230 

231 await handler.process_message(msg) 

232 

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 ) 

246 

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 

250 

251 with anyio.fail_after(cmd.timeout or 30.0): 

252 result = await handler.process_message(msg) 

253 

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 ) 

263 

264 raise SubscriberNotFound 

265 

266 

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. 

281 

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) 

289 

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 ) 

297 

298 user_props: list[tuple[str, str]] = list((headers or {}).items()) 

299 

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 ) 

306 

307 return zmqtt.Message( 

308 topic=topic, 

309 payload=payload, 

310 qos=zmqtt.QoS(qos), 

311 retain=retain, 

312 properties=properties, 

313 )