music-assistant-server
489.7 KB•PY
test_protocol_linking.py
489.7 KB • 12,405 lines • python
1"""Tests for protocol player linking and universal player creation."""
2
3import asyncio
4import inspect
5import logging
6import re
7from collections.abc import Awaitable, Iterator
8from typing import Any
9from unittest.mock import AsyncMock, MagicMock, patch
10from uuid import UUID
11
12import pytest
13from music_assistant_models.config_entries import PlayerConfig
14from music_assistant_models.enums import (
15 EventType,
16 IdentifierType,
17 PlaybackState,
18 PlayerFeature,
19 PlayerType,
20)
21from music_assistant_models.media_items import AudioSource
22from music_assistant_models.media_items.provider_mapping import ProviderMapping
23from music_assistant_models.player import PlayerMedia
24
25from music_assistant.constants import (
26 ATTR_ENABLED,
27 CONF_PLAYER_DSP,
28 CONF_PLAYER_QUEUES,
29 CONF_PLAYERS,
30 CONF_PREFERRED_OUTPUT_PROTOCOL,
31 CONF_PROTOCOL_PARENT_ID,
32 CONF_UNDERLYING_PLAYER_ID,
33)
34from music_assistant.controllers.config import ConfigController
35from music_assistant.controllers.config.migrations import migrate
36from music_assistant.controllers.players import PlayerController
37from music_assistant.helpers.util import enrich_device_mac_address
38from music_assistant.models.player import DeviceInfo, LinkedOutputProtocol, Player
39from music_assistant.models.player_provider import PlayerProvider
40from music_assistant.providers.universal_player.constants import CONF_CREATED_AT
41from music_assistant.providers.universal_player.player import UniversalPlayer
42from music_assistant.providers.universal_player.provider import UniversalPlayerProvider
43
44
45def create_mock_config(name: str) -> MagicMock:
46 """Create a mock player config with the given name."""
47 config = MagicMock()
48 config.name = None # No custom name, use default
49 config.default_name = name
50 return config
51
52
53def create_mock_universal_provider(mock_mass: MagicMock) -> UniversalPlayerProvider:
54 """Create a mock UniversalPlayerProvider for testing."""
55 # Create a mock manifest
56 manifest = MagicMock()
57 manifest.domain = "universal_player"
58 manifest.name = "Universal Player"
59
60 # Create provider with the mock manifest
61 provider = UniversalPlayerProvider.__new__(UniversalPlayerProvider)
62 provider.mass = mock_mass
63 provider.manifest = manifest
64 provider.logger = logging.getLogger("test.universal_player")
65 # Add config mock for instance_id property
66 config = MagicMock()
67 config.instance_id = "universal_player"
68 config.name = None
69 provider.config = config
70 # Initialize the lock that would normally be set in handle_async_init
71 provider._lock = asyncio.Lock()
72 return provider
73
74
75# Player id of the universal player a device was wrapped in earlier, as minted once
76# by UniversalPlayerProvider.mint_player_id.
77STORED_UNIVERSAL_ID = "up1a2b3c4d"
78
79
80def _wire_nested_config(mock_mass: MagicMock, store: dict[str, Any]) -> None:
81 """Wire mass.config get/set/remove to a nested, path-addressable store."""
82
83 def _get(key: str, default: object = None) -> object:
84 node: Any = store
85 for part in key.split("/"):
86 if not isinstance(node, dict) or part not in node:
87 return default
88 node = node[part]
89 return node
90
91 def _set(key: str, value: object) -> None:
92 parts = key.split("/")
93 node: dict[str, Any] = store
94 for part in parts[:-1]:
95 node = node.setdefault(part, {})
96 node[parts[-1]] = value
97
98 def _remove(key: str) -> None:
99 parts = key.split("/")
100 node: Any = store
101 for part in parts[:-1]:
102 node = node.get(part) if isinstance(node, dict) else None
103 if node is None:
104 return
105 if isinstance(node, dict):
106 node.pop(parts[-1], None)
107
108 mock_mass.config.get = MagicMock(side_effect=_get)
109 mock_mass.config.set = MagicMock(side_effect=_set)
110 mock_mass.config.remove = MagicMock(side_effect=_remove)
111
112
113def _fake_create_default_player_config(
114 store: dict[str, Any],
115 player_id: str,
116 provider: str,
117 player_type: PlayerType,
118 name: str | None = None,
119 enabled: bool = True,
120 values: dict[str, Any] | None = None,
121) -> None:
122 """
123 Mirror ConfigController.create_default_player_config against a plain dict store.
124
125 Only the parts the universal player flows depend on: a fresh config keeps the
126 creation-time name as the default name only, an existing config keeps its type.
127 """
128 players: dict[str, Any] = store.setdefault(CONF_PLAYERS, {})
129 if existing := players.get(player_id):
130 if name and name != existing.get("default_name"):
131 existing["default_name"] = name
132 return
133 players[player_id] = {
134 "player_id": player_id,
135 "provider": provider,
136 "player_type": player_type.value,
137 "enabled": enabled,
138 "name": None,
139 "default_name": name,
140 "values": dict(values or {}),
141 }
142
143
144class MockProvider:
145 """Mock player provider for testing."""
146
147 def __init__(
148 self, domain: str, instance_id: str = "test_instance", mass: MagicMock | None = None
149 ) -> None:
150 """Initialize the mock provider."""
151 self.domain = domain
152 self.instance_id = instance_id
153 self.name = f"Mock {domain.title()}"
154 self.manifest = MagicMock()
155 self.manifest.name = f"Mock {domain} Provider"
156 self.mass = mass or MagicMock()
157 self.logger = logging.getLogger(f"test.{domain}")
158 # the controller iterates these when a group related field changes
159 self.players: list[Player] = []
160
161
162class MockPlayer(Player):
163 """Mock player for testing."""
164
165 def __init__(
166 self,
167 provider: MockProvider,
168 player_id: str,
169 name: str,
170 player_type: PlayerType = PlayerType.PLAYER,
171 identifiers: dict[IdentifierType, str] | None = None,
172 ) -> None:
173 """Initialize the mock player."""
174 # Set up the mock config before calling super().__init__
175 # because the parent __init__ accesses config
176 provider.mass.config.get_base_player_config.return_value = create_mock_config(name)
177
178 super().__init__(provider, player_id) # type: ignore[arg-type]
179 self._attr_name = name
180 # Set type as instance attribute (overrides class attribute)
181 self._attr_type = player_type
182 self._attr_available = True
183 self._attr_powered = True
184 self._attr_supported_features = {PlayerFeature.VOLUME_SET}
185 self._attr_can_group_with = set()
186
187 # Set up device info with identifiers
188 self._attr_device_info = DeviceInfo(
189 model="Test Model",
190 manufacturer="Test Manufacturer",
191 )
192 if identifiers:
193 for conn_type, value in identifiers.items():
194 self._attr_device_info.add_identifier(conn_type, value)
195
196 # Clear cached properties after modifying attributes
197 self._cache.clear()
198
199 # Update state to reflect the modified attributes
200 self.update_state(signal_event=False)
201
202 async def stop(self) -> None:
203 """Stop playback - required abstract method."""
204
205 async def set_members(
206 self,
207 player_ids_to_add: list[str] | None = None,
208 player_ids_to_remove: list[str] | None = None,
209 ) -> None:
210 """Mock implementation of set_members."""
211 current_members = set(getattr(self, "_attr_group_members", []))
212
213 if player_ids_to_add:
214 current_members.update(player_ids_to_add)
215
216 if player_ids_to_remove:
217 current_members.difference_update(player_ids_to_remove)
218
219 # Always include self as first member if there are members
220 if current_members:
221 self._attr_group_members = [self.player_id] + [
222 pid for pid in current_members if pid != self.player_id
223 ]
224 else:
225 self._attr_group_members = []
226
227 # Clear cache to reflect changes
228 self._cache.clear()
229
230
231class SessionBoundMockPlayer(MockPlayer):
232 """Mock player whose native grouping attaches members to its own stream (e.g. AirPlay)."""
233
234 @property
235 def native_grouping_requires_own_stream(self) -> bool:
236 """Return True: native members ride this player's own stream session."""
237 return True
238
239
240@pytest.fixture
241def mock_mass() -> Iterator[MagicMock]:
242 """Create a mock MusicAssistant instance."""
243 mass = MagicMock()
244 mass.closing = False
245 mass.config = MagicMock()
246 mass.config.get = MagicMock(return_value=[])
247
248 def _get_raw_player_config_value(
249 _player_id: str, key: str, default: str | int | None = None
250 ) -> str | int | None:
251 """Return appropriate defaults for player config values."""
252 if key == "min_volume":
253 return 0
254 if key == "max_volume":
255 return 100
256 return default
257
258 mass.config.get_raw_player_config_value = MagicMock(side_effect=_get_raw_player_config_value)
259 # Return "GLOBAL" for log level config (standard default)
260 mass.config.get_raw_core_config_value = MagicMock(return_value="GLOBAL")
261 mass.config.set = MagicMock()
262 mass.signal_event = MagicMock()
263 mass.get_providers = MagicMock(return_value=[])
264 # awaited by the tests that replay the tasks scheduled during a config wipe
265 mass.webserver.auth.remove_from_user_filters = AsyncMock()
266 mass.webserver.auth.replace_player_in_user_filters = AsyncMock()
267 yield mass
268 for call in mass.create_task.call_args_list:
269 if call.args and inspect.iscoroutine(coro := call.args[0]):
270 coro.close()
271
272
273class TestIdentifiersMatch:
274 """Tests for identifier matching logic."""
275
276 def test_mac_address_match(self, mock_mass: MagicMock) -> None:
277 """Test that MAC addresses match correctly."""
278 controller = PlayerController(mock_mass)
279
280 provider = MockProvider("test")
281 player_a = MockPlayer(
282 provider,
283 "player_a",
284 "Player A",
285 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
286 )
287 player_b = MockPlayer(
288 provider,
289 "player_b",
290 "Player B",
291 identifiers={IdentifierType.MAC_ADDRESS: "aa:bb:cc:dd:ee:ff"}, # lowercase
292 )
293
294 assert controller._identifiers_match(player_a, player_b) is True
295
296 def test_mac_address_no_match(self, mock_mass: MagicMock) -> None:
297 """Test that different MAC addresses don't match."""
298 controller = PlayerController(mock_mass)
299
300 provider = MockProvider("test")
301 player_a = MockPlayer(
302 provider,
303 "player_a",
304 "Player A",
305 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
306 )
307 player_b = MockPlayer(
308 provider,
309 "player_b",
310 "Player B",
311 identifiers={IdentifierType.MAC_ADDRESS: "11:22:33:44:55:66"},
312 )
313
314 assert controller._identifiers_match(player_a, player_b) is False
315
316 def test_invalid_mac_address_no_match(self, mock_mass: MagicMock) -> None:
317 """Test that an all-zero MAC is not identity and never matches across devices."""
318 controller = PlayerController(mock_mass)
319
320 provider = MockProvider("test")
321 player_a = MockPlayer(
322 provider,
323 "player_a",
324 "Player A",
325 identifiers={IdentifierType.MAC_ADDRESS: "00:00:00:00:00:00"},
326 )
327 player_b = MockPlayer(
328 provider,
329 "player_b",
330 "Player B",
331 identifiers={IdentifierType.MAC_ADDRESS: "00:00:00:00:00:00"},
332 )
333
334 assert controller._identifiers_match(player_a, player_b) is False
335
336 def test_mac_address_locally_administered_bit_match(self, mock_mass: MagicMock) -> None:
337 """
338 Test that MAC addresses differing only in locally-administered bit match.
339
340 Some protocols (like AirPlay) report a MAC with the locally-administered
341 bit set (bit 1 of first octet), while other protocols report the real
342 hardware MAC. These should match as the same device.
343
344 Example: 54:78:C9:E6:0D:A0 (hardware) vs 56:78:C9:E6:0D:A0 (AirPlay)
345 """
346 controller = PlayerController(mock_mass)
347
348 provider = MockProvider("test")
349 # Real hardware MAC (first byte 0x54 = 01010100, bit 1 = 0)
350 player_a = MockPlayer(
351 provider,
352 "player_a",
353 "WiiM Pro (DLNA)",
354 identifiers={IdentifierType.MAC_ADDRESS: "54:78:C9:E6:0D:A0"},
355 )
356 # AirPlay MAC with locally-administered bit set (first byte 0x56 = 01010110, bit 1 = 1)
357 player_b = MockPlayer(
358 provider,
359 "player_b",
360 "WiiM Pro (AirPlay)",
361 identifiers={IdentifierType.MAC_ADDRESS: "56:78:C9:E6:0D:A0"},
362 )
363
364 # These should match because they differ only in the locally-administered bit
365 assert controller._identifiers_match(player_a, player_b) is True
366
367 def test_mac_address_locally_administered_bit_different_devices_no_match(
368 self, mock_mass: MagicMock
369 ) -> None:
370 """
371 Test that different devices with locally-administered MACs don't match.
372
373 Only the locally-administered bit should be ignored, not other differences.
374 """
375 controller = PlayerController(mock_mass)
376
377 provider = MockProvider("test")
378 player_a = MockPlayer(
379 provider,
380 "player_a",
381 "Device A",
382 identifiers={IdentifierType.MAC_ADDRESS: "54:78:C9:E6:0D:A0"},
383 )
384 player_b = MockPlayer(
385 provider,
386 "player_b",
387 "Device B",
388 identifiers={IdentifierType.MAC_ADDRESS: "56:78:C9:E6:0D:A1"}, # Different last byte
389 )
390
391 # These should NOT match - they differ in more than just the locally-administered bit
392 assert controller._identifiers_match(player_a, player_b) is False
393
394 def test_ip_address_fallback_with_no_mac(self, mock_mass: MagicMock) -> None:
395 """Test that same IP matches when no MAC is available (ARP couldn't help)."""
396 controller = PlayerController(mock_mass)
397
398 provider = MockProvider("test")
399 player_a = MockPlayer(
400 provider,
401 "player_a",
402 "Player A",
403 identifiers={IdentifierType.IP_ADDRESS: "192.168.1.100"},
404 )
405 player_b = MockPlayer(
406 provider,
407 "player_b",
408 "Player B",
409 identifiers={IdentifierType.IP_ADDRESS: "192.168.1.100"},
410 )
411
412 # Same IP with no MAC at all = match (likely same device, ARP unavailable)
413 assert controller._identifiers_match(player_a, player_b) is True
414
415 def test_sonos_uuid_dlna_suffix_match(self, mock_mass: MagicMock) -> None:
416 """Test Sonos UUID matching with DLNA _MR suffix."""
417 controller = PlayerController(mock_mass)
418
419 provider = MockProvider("test")
420 # Sonos native player
421 player_a = MockPlayer(
422 provider,
423 "player_a",
424 "Sonos Player",
425 identifiers={IdentifierType.UUID: "RINCON_000E58123456"},
426 )
427 # DLNA player with _MR suffix
428 player_b = MockPlayer(
429 provider,
430 "player_b",
431 "DLNA Player",
432 identifiers={IdentifierType.UUID: "RINCON_000E58123456_MR"},
433 )
434
435 assert controller._identifiers_match(player_a, player_b) is True
436
437 def test_no_identifiers_no_match(self, mock_mass: MagicMock) -> None:
438 """Test that players without identifiers don't match."""
439 controller = PlayerController(mock_mass)
440
441 provider = MockProvider("test")
442 player_a = MockPlayer(provider, "player_a", "Player A")
443 player_b = MockPlayer(provider, "player_b", "Player B")
444
445 assert controller._identifiers_match(player_a, player_b) is False
446
447 def test_cast_uuid_match(self, mock_mass: MagicMock) -> None:
448 """
449 Test that CAST_UUID identifiers match for cross-protocol linking.
450
451 When a Chromecast device has no valid MAC (non-Google devices like SEI Robotics),
452 the CAST_UUID identifier allows matching the Chromecast player with its
453 Sendspin bridge player.
454 """
455 controller = PlayerController(mock_mass)
456
457 provider = MockProvider("test")
458 # Chromecast player with UUID and CAST_UUID but no MAC
459 player_a = MockPlayer(
460 provider,
461 "player_a",
462 "Android TV (Cast)",
463 player_type=PlayerType.PROTOCOL,
464 identifiers={
465 IdentifierType.UUID: "88ef6168-67d7-3d08-fae8-b1b1709c1ed7",
466 IdentifierType.CAST_UUID: "88ef6168-67d7-3d08-fae8-b1b1709c1ed7",
467 IdentifierType.IP_ADDRESS: "192.168.1.228",
468 },
469 )
470 # Sendspin bridge player with only MAC and CAST_UUID (no UUID, no IP)
471 player_b = MockPlayer(
472 provider,
473 "player_b",
474 "Android TV (Sendspin)",
475 player_type=PlayerType.PROTOCOL,
476 identifiers={
477 IdentifierType.MAC_ADDRESS: "D4:CF:F9:D9:DA:FD",
478 IdentifierType.CAST_UUID: "88ef6168-67d7-3d08-fae8-b1b1709c1ed7",
479 },
480 )
481
482 # Should match via CAST_UUID even though they share no MAC, UUID, or IP
483 assert controller._identifiers_match(player_a, player_b) is True
484
485 def test_cast_uuid_no_match(self, mock_mass: MagicMock) -> None:
486 """Test that different CAST_UUIDs don't match."""
487 controller = PlayerController(mock_mass)
488
489 provider = MockProvider("test")
490 player_a = MockPlayer(
491 provider,
492 "player_a",
493 "Device A",
494 player_type=PlayerType.PROTOCOL,
495 identifiers={IdentifierType.CAST_UUID: "88ef6168-67d7-3d08-fae8-b1b1709c1ed7"},
496 )
497 player_b = MockPlayer(
498 provider,
499 "player_b",
500 "Device B",
501 player_type=PlayerType.PROTOCOL,
502 identifiers={IdentifierType.CAST_UUID: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"},
503 )
504
505 assert controller._identifiers_match(player_a, player_b) is False
506
507 def test_airplay_id_match(self, mock_mass: MagicMock) -> None:
508 """
509 Test that AIRPLAY_ID identifiers match for cross-protocol linking.
510
511 When an AirPlay device's MAC has locally-administered bit differences,
512 AIRPLAY_ID provides a reliable secondary match path between the AirPlay
513 player and its Sendspin bridge player.
514 """
515 controller = PlayerController(mock_mass)
516
517 provider = MockProvider("test")
518 # AirPlay player with its player_id as AIRPLAY_ID
519 player_a = MockPlayer(
520 provider,
521 "player_a",
522 "Apple TV (AirPlay)",
523 player_type=PlayerType.PROTOCOL,
524 identifiers={
525 IdentifierType.MAC_ADDRESS: "54:78:1A:D4:FF:44",
526 IdentifierType.AIRPLAY_ID: "ap54781ad4ff44",
527 IdentifierType.IP_ADDRESS: "192.168.1.50",
528 },
529 )
530 # Sendspin bridge player with MAC and AIRPLAY_ID
531 player_b = MockPlayer(
532 provider,
533 "player_b",
534 "Apple TV (Sendspin)",
535 player_type=PlayerType.PROTOCOL,
536 identifiers={
537 IdentifierType.MAC_ADDRESS: "54:78:1A:D4:FF:44",
538 IdentifierType.AIRPLAY_ID: "ap54781ad4ff44",
539 },
540 )
541
542 # Should match via both MAC and AIRPLAY_ID
543 assert controller._identifiers_match(player_a, player_b) is True
544
545 def test_airplay_id_no_match(self, mock_mass: MagicMock) -> None:
546 """Test that different AIRPLAY_IDs don't match."""
547 controller = PlayerController(mock_mass)
548
549 provider = MockProvider("test")
550 player_a = MockPlayer(
551 provider,
552 "player_a",
553 "Device A",
554 player_type=PlayerType.PROTOCOL,
555 identifiers={IdentifierType.AIRPLAY_ID: "ap54781ad4ff44"},
556 )
557 player_b = MockPlayer(
558 provider,
559 "player_b",
560 "Device B",
561 player_type=PlayerType.PROTOCOL,
562 identifiers={IdentifierType.AIRPLAY_ID: "apaabbccddeeff"},
563 )
564
565 assert controller._identifiers_match(player_a, player_b) is False
566
567 def test_ip_fallback_with_la_mac(self, mock_mass: MagicMock) -> None:
568 """Test IP fallback matching when one player has a locally-administered MAC."""
569 controller = PlayerController(mock_mass)
570
571 provider = MockProvider("test")
572 player_a = MockPlayer(
573 provider,
574 "player_a",
575 "AirPlay Device",
576 player_type=PlayerType.PROTOCOL,
577 identifiers={
578 IdentifierType.MAC_ADDRESS: "C0:F5:35:7B:6D:A0",
579 IdentifierType.IP_ADDRESS: "192.168.1.48",
580 },
581 )
582 player_b = MockPlayer(
583 provider,
584 "player_b",
585 "DLNA Device",
586 player_type=PlayerType.PROTOCOL,
587 identifiers={
588 # Locally-administered MAC from ARP (device uses MAC randomization)
589 IdentifierType.MAC_ADDRESS: "02:4E:52:A1:BC:6B",
590 IdentifierType.IP_ADDRESS: "192.168.1.48",
591 },
592 )
593
594 assert controller._identifiers_match(player_a, player_b) is True
595
596 def test_ip_fallback_with_missing_mac(self, mock_mass: MagicMock) -> None:
597 """Test IP fallback matching when one player has no MAC at all."""
598 controller = PlayerController(mock_mass)
599
600 provider = MockProvider("test")
601 player_a = MockPlayer(
602 provider,
603 "player_a",
604 "AirPlay Device",
605 player_type=PlayerType.PROTOCOL,
606 identifiers={
607 IdentifierType.MAC_ADDRESS: "C0:F5:35:7B:6D:A0",
608 IdentifierType.IP_ADDRESS: "192.168.1.48",
609 },
610 )
611 player_b = MockPlayer(
612 provider,
613 "player_b",
614 "DLNA Device",
615 player_type=PlayerType.PROTOCOL,
616 identifiers={
617 IdentifierType.IP_ADDRESS: "192.168.1.48",
618 },
619 )
620
621 assert controller._identifiers_match(player_a, player_b) is True
622
623 def test_ip_fallback_protocol_players_with_real_macs(self, mock_mass: MagicMock) -> None:
624 """
625 Test that IP matches protocol players even when both have real MACs.
626
627 Some devices (e.g., Yamaha MusicCast) report different valid globally-unique
628 MACs per protocol (DLNA vs AirPlay differ by 1 in the last octet).
629 IP matching is safe here because two devices on a LAN can't share an IP.
630 """
631 controller = PlayerController(mock_mass)
632
633 provider = MockProvider("test")
634 player_a = MockPlayer(
635 provider,
636 "player_a",
637 "Device A",
638 player_type=PlayerType.PROTOCOL,
639 identifiers={
640 IdentifierType.MAC_ADDRESS: "C0:F5:35:7B:6D:A0",
641 IdentifierType.IP_ADDRESS: "192.168.1.48",
642 },
643 )
644 player_b = MockPlayer(
645 provider,
646 "player_b",
647 "Device B",
648 player_type=PlayerType.PROTOCOL,
649 identifiers={
650 # A8 first octet = 10101000, LA bit (0x02) is clear -> real MAC
651 IdentifierType.MAC_ADDRESS: "A8:BB:CC:DD:EE:FF",
652 IdentifierType.IP_ADDRESS: "192.168.1.48",
653 },
654 )
655
656 # Protocol players with real MACs on same IP -> match (same physical device)
657 assert controller._identifiers_match(player_a, player_b) is True
658
659 def test_ip_no_fallback_native_players_with_real_macs(self, mock_mass: MagicMock) -> None:
660 """Test that IP alone does NOT match two native PLAYER-type players with real MACs."""
661 controller = PlayerController(mock_mass)
662
663 provider = MockProvider("test")
664 player_a = MockPlayer(
665 provider,
666 "player_a",
667 "Device A",
668 player_type=PlayerType.PLAYER,
669 identifiers={
670 IdentifierType.MAC_ADDRESS: "C0:F5:35:7B:6D:A0",
671 IdentifierType.IP_ADDRESS: "192.168.1.48",
672 },
673 )
674 player_b = MockPlayer(
675 provider,
676 "player_b",
677 "Device B",
678 player_type=PlayerType.PLAYER,
679 identifiers={
680 IdentifierType.MAC_ADDRESS: "A8:BB:CC:DD:EE:FF",
681 IdentifierType.IP_ADDRESS: "192.168.1.48",
682 },
683 )
684
685 # Two native players with real MACs that don't match - IP should NOT be used
686 assert controller._identifiers_match(player_a, player_b) is False
687
688 def test_ip_no_fallback_different_ips(self, mock_mass: MagicMock) -> None:
689 """Test that different IPs don't match even with LA MAC."""
690 controller = PlayerController(mock_mass)
691
692 provider = MockProvider("test")
693 player_a = MockPlayer(
694 provider,
695 "player_a",
696 "Device A",
697 player_type=PlayerType.PROTOCOL,
698 identifiers={
699 IdentifierType.MAC_ADDRESS: "C0:F5:35:7B:6D:A0",
700 IdentifierType.IP_ADDRESS: "192.168.1.48",
701 },
702 )
703 player_b = MockPlayer(
704 provider,
705 "player_b",
706 "Device B",
707 player_type=PlayerType.PROTOCOL,
708 identifiers={
709 IdentifierType.MAC_ADDRESS: "02:4E:52:A1:BC:6B",
710 IdentifierType.IP_ADDRESS: "192.168.1.99",
711 },
712 )
713
714 assert controller._identifiers_match(player_a, player_b) is False
715
716
717class TestProtocolPlayerDetection:
718 """Tests for protocol player type detection."""
719
720 def test_is_protocol_player_true(self, mock_mass: MagicMock) -> None:
721 """Test that PlayerType.PROTOCOL is correctly detected."""
722 controller = PlayerController(mock_mass)
723
724 provider = MockProvider("airplay")
725 player = MockPlayer(
726 provider,
727 "ap_123456",
728 "Samsung TV (AirPlay)",
729 player_type=PlayerType.PROTOCOL,
730 )
731
732 assert controller._is_protocol_player(player) is True
733
734 def test_is_protocol_player_false(self, mock_mass: MagicMock) -> None:
735 """Test that PlayerType.PLAYER is not detected as protocol."""
736 controller = PlayerController(mock_mass)
737
738 provider = MockProvider("airplay")
739 player = MockPlayer(
740 provider,
741 "ap_123456",
742 "HomePod",
743 player_type=PlayerType.PLAYER, # Apple device with native support
744 )
745
746 assert controller._is_protocol_player(player) is False
747
748
749class TestFindMatchingProtocolPlayers:
750 """Tests for finding matching protocol players."""
751
752 def test_find_matching_by_mac(self, mock_mass: MagicMock) -> None:
753 """Test finding matching protocol players by MAC address."""
754 controller = PlayerController(mock_mass)
755
756 # Set up providers
757 airplay_provider = MockProvider("airplay")
758 chromecast_provider = MockProvider("chromecast")
759
760 # Create matching protocol players (same device, different protocols)
761 airplay_player = MockPlayer(
762 airplay_provider,
763 "ap_aabbccddee",
764 "Samsung TV (AirPlay)",
765 player_type=PlayerType.PROTOCOL,
766 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
767 )
768 chromecast_player = MockPlayer(
769 chromecast_provider,
770 "cc_aabbccddee",
771 "Samsung TV (Chromecast)",
772 player_type=PlayerType.PROTOCOL,
773 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
774 )
775
776 # Register players
777 controller._players = {
778 "ap_aabbccddee": airplay_player,
779 "cc_aabbccddee": chromecast_player,
780 }
781
782 # Mark players as initialized so they are returned by all_players()
783 airplay_player.set_initialized()
784 chromecast_player.set_initialized()
785
786 # Find matching players for AirPlay player
787 matches = controller._find_matching_protocol_players(airplay_player)
788
789 assert len(matches) == 2
790 assert airplay_player in matches
791 assert chromecast_player in matches
792
793 def test_same_protocol_not_matched(self, mock_mass: MagicMock) -> None:
794 """Test that multiple players of same protocol on same host are NOT matched together."""
795 controller = PlayerController(mock_mass)
796
797 # Set up provider
798 snapcast_provider = MockProvider("snapcast")
799
800 # Create multiple Snapcast players on same host (same MAC/IP)
801 # This simulates multiple Snapcast clients running on the same server
802 snapcast_player_1 = MockPlayer(
803 snapcast_provider,
804 "snapcast_client_1",
805 "Snapcast Client 1",
806 player_type=PlayerType.PROTOCOL,
807 identifiers={
808 IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF",
809 IdentifierType.IP_ADDRESS: "192.168.1.100",
810 },
811 )
812 snapcast_player_2 = MockPlayer(
813 snapcast_provider,
814 "snapcast_client_2",
815 "Snapcast Client 2",
816 player_type=PlayerType.PROTOCOL,
817 identifiers={
818 IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF",
819 IdentifierType.IP_ADDRESS: "192.168.1.100",
820 },
821 )
822
823 # Register players
824 controller._players = {
825 "snapcast_client_1": snapcast_player_1,
826 "snapcast_client_2": snapcast_player_2,
827 }
828
829 # Find matching players for first Snapcast player
830 matches = controller._find_matching_protocol_players(snapcast_player_1)
831
832 # Should only match itself, NOT the other Snapcast player (same protocol domain)
833 assert len(matches) == 1
834 assert snapcast_player_1 in matches
835 assert snapcast_player_2 not in matches
836
837
838class TestResolveStoredUniversalPlayer:
839 """
840 Tests for resolving the universal player a protocol player is persistently linked to.
841
842 Regression tests for music-assistant/support#5888: the universal player id is
843 minted once and a device is always routed back to the wrapper its protocol
844 players point at, so the id API consumers (such as the Home Assistant
845 integration) bind their entities to stays put.
846 """
847
848 @staticmethod
849 def _stored_universal_config(**overrides: Any) -> dict[str, Any]:
850 """Return the stored config of a universal player wrapping the ap_123456 device."""
851 return {
852 "player_id": STORED_UNIVERSAL_ID,
853 "provider": "universal_player",
854 "player_type": "player",
855 "enabled": True,
856 "default_name": "Living Room",
857 "values": {
858 "linked_protocol_ids": ["ap_123456"],
859 "device_identifiers": {"mac_address": "54:78:C9:E6:0D:A0"},
860 "device_info": {"model": "WiiM Pro", "manufacturer": "Linkplay"},
861 },
862 } | overrides
863
864 @staticmethod
865 def _wire_config(
866 mock_mass: MagicMock,
867 parent_id: str | None,
868 parent_config: dict[str, Any] | None = None,
869 ) -> None:
870 """
871 Wire a config store holding the ap_123456 protocol player and its parent.
872
873 :param mock_mass: The mocked MusicAssistant instance to wire.
874 :param parent_id: Parent link persisted on the protocol player, if any.
875 :param parent_config: Stored config of the parent player, when it (still) exists.
876 """
877 players: dict[str, Any] = {
878 "ap_123456": {
879 "player_id": "ap_123456",
880 "provider": "airplay",
881 "player_type": "protocol",
882 "enabled": True,
883 "values": {"protocol_parent_id": parent_id},
884 }
885 }
886 if parent_config is not None:
887 players[parent_config["player_id"]] = parent_config
888 _wire_nested_config(mock_mass, {CONF_PLAYERS: players})
889
890 @staticmethod
891 def _wire_players(mock_mass: MagicMock, registry: dict[str, Player]) -> None:
892 """Wire mass.players so registrations land in the given registry."""
893
894 async def _register(player: Player) -> None:
895 registry[player.player_id] = player
896 player.set_initialized()
897
898 mock_mass.players = MagicMock()
899 mock_mass.players.get_player = MagicMock(
900 side_effect=lambda pid, *_args, **_kwargs: registry.get(pid)
901 )
902 mock_mass.players.register_or_update = AsyncMock(side_effect=_register)
903
904 @staticmethod
905 def _make_protocol_player(mock_mass: MagicMock) -> MockPlayer:
906 """Return the unlinked AirPlay protocol player of the wrapped device."""
907 player = MockPlayer(
908 MockProvider("airplay", mass=mock_mass),
909 "ap_123456",
910 "Test Player",
911 player_type=PlayerType.PROTOCOL,
912 identifiers={IdentifierType.MAC_ADDRESS: "54:78:C9:E6:0D:A0"},
913 )
914 player.set_initialized()
915 return player
916
917 async def test_registered_parent_resolves_to_its_universal_player(
918 self, mock_mass: MagicMock
919 ) -> None:
920 """The stored parent link resolves to the universal player it names."""
921 universal_provider = create_mock_universal_provider(mock_mass)
922 self._wire_config(mock_mass, STORED_UNIVERSAL_ID, self._stored_universal_config())
923 registry: dict[str, Player] = {}
924 self._wire_players(mock_mass, registry)
925 universal = _create_universal_player(
926 mock_mass, STORED_UNIVERSAL_ID, "Living Room", protocol_player_ids=["ap_123456"]
927 )
928 registry[STORED_UNIVERSAL_ID] = universal
929 player = self._make_protocol_player(mock_mass)
930
931 assert await universal_provider._resolve_stored_universal_player(player) is universal
932 mock_mass.players.register_or_update.assert_not_awaited()
933
934 async def test_unregistered_parent_is_restored_from_its_config(
935 self, mock_mass: MagicMock
936 ) -> None:
937 """A stored parent that is not registered is restored under its own player id."""
938 universal_provider = create_mock_universal_provider(mock_mass)
939 self._wire_config(mock_mass, STORED_UNIVERSAL_ID, self._stored_universal_config())
940 registry: dict[str, Player] = {}
941 self._wire_players(mock_mass, registry)
942 player = self._make_protocol_player(mock_mass)
943
944 resolved = await universal_provider._resolve_stored_universal_player(player)
945
946 assert resolved is not None
947 assert resolved.player_id == STORED_UNIVERSAL_ID
948 assert resolved._protocol_player_ids == ["ap_123456"]
949 assert registry[STORED_UNIVERSAL_ID] is resolved
950
951 async def test_parent_config_of_another_provider_is_ignored(self, mock_mass: MagicMock) -> None:
952 """A parent config owned by another provider is never ours to resolve to."""
953 universal_provider = create_mock_universal_provider(mock_mass)
954 # a native player whose id merely happens to start with the universal player prefix
955 self._wire_config(
956 mock_mass,
957 "upnp_media_renderer",
958 {
959 "player_id": "upnp_media_renderer",
960 "provider": "some_native_provider",
961 "enabled": True,
962 "values": {"linked_protocol_ids": ["ap_123456"]},
963 },
964 )
965 registry: dict[str, Player] = {}
966 self._wire_players(mock_mass, registry)
967 player = self._make_protocol_player(mock_mass)
968
969 assert await universal_provider._resolve_stored_universal_player(player) is None
970 mock_mass.players.register_or_update.assert_not_awaited()
971
972 async def test_disabled_parent_config_is_ignored(self, mock_mass: MagicMock) -> None:
973 """A disabled universal player stays off: the user turned this device off."""
974 universal_provider = create_mock_universal_provider(mock_mass)
975 self._wire_config(
976 mock_mass, STORED_UNIVERSAL_ID, self._stored_universal_config(enabled=False)
977 )
978 registry: dict[str, Player] = {}
979 self._wire_players(mock_mass, registry)
980 player = self._make_protocol_player(mock_mass)
981
982 assert await universal_provider._resolve_stored_universal_player(player) is None
983 mock_mass.players.register_or_update.assert_not_awaited()
984
985 async def test_stored_parent_without_a_config_is_ignored(self, mock_mass: MagicMock) -> None:
986 """A parent link left dangling by a deleted config resolves to nothing."""
987 universal_provider = create_mock_universal_provider(mock_mass)
988 self._wire_config(mock_mass, STORED_UNIVERSAL_ID)
989 registry: dict[str, Player] = {}
990 self._wire_players(mock_mass, registry)
991 player = self._make_protocol_player(mock_mass)
992
993 assert await universal_provider._resolve_stored_universal_player(player) is None
994 mock_mass.players.register_or_update.assert_not_awaited()
995
996 async def test_without_a_stored_parent_link_nothing_resolves(
997 self, mock_mass: MagicMock
998 ) -> None:
999 """A protocol player that was never wrapped resolves to no universal player."""
1000 universal_provider = create_mock_universal_provider(mock_mass)
1001 self._wire_config(mock_mass, None)
1002 registry: dict[str, Player] = {}
1003 self._wire_players(mock_mass, registry)
1004 player = self._make_protocol_player(mock_mass)
1005
1006 assert await universal_provider._resolve_stored_universal_player(player) is None
1007
1008
1009class TestMintPlayerId:
1010 """Tests for minting the opaque player id of a new universal player."""
1011
1012 def test_minted_id_is_free_as_a_player_and_as_a_config(self, mock_mass: MagicMock) -> None:
1013 """A minted id is never one that is already taken."""
1014 universal_provider = create_mock_universal_provider(mock_mass)
1015 _wire_nested_config(
1016 mock_mass,
1017 {CONF_PLAYERS: {"upbbbbbbbb": {"player_id": "upbbbbbbbb", "enabled": False}}},
1018 )
1019 registered = {"upaaaaaaaa": MagicMock()}
1020 mock_mass.players = MagicMock()
1021 mock_mass.players.get_player = MagicMock(
1022 side_effect=lambda pid, *_args, **_kwargs: registered.get(pid)
1023 )
1024 candidates = [
1025 UUID("aaaaaaaa-0000-0000-0000-000000000000"), # taken by a registered player
1026 UUID("bbbbbbbb-0000-0000-0000-000000000000"), # taken by a (stale) config
1027 UUID("cccccccc-0000-0000-0000-000000000000"),
1028 ]
1029
1030 with patch(
1031 "music_assistant.providers.universal_player.provider.uuid4", side_effect=candidates
1032 ):
1033 assert universal_provider.mint_player_id() == "upcccccccc"
1034
1035
1036class TestGetCleanPlayerName:
1037 """Tests for player name selection."""
1038
1039 def test_prefers_chromecast_name(self, mock_mass: MagicMock) -> None:
1040 """Test that Chromecast names are preferred over other protocols."""
1041 universal_provider = create_mock_universal_provider(mock_mass)
1042
1043 airplay_provider = MockProvider("airplay")
1044 chromecast_provider = MockProvider("chromecast")
1045
1046 airplay_player = MockPlayer(
1047 airplay_provider,
1048 "ap_123456",
1049 "Samsung TV",
1050 player_type=PlayerType.PROTOCOL,
1051 )
1052 chromecast_player = MockPlayer(
1053 chromecast_provider,
1054 "cc_123456",
1055 "Living Room Speaker",
1056 player_type=PlayerType.PROTOCOL,
1057 )
1058
1059 # Chromecast should be preferred (priority 1)
1060 clean_name = universal_provider._get_clean_player_name([airplay_player, chromecast_player])
1061 assert clean_name == "Living Room Speaker"
1062
1063 def test_filters_mac_address_names(self, mock_mass: MagicMock) -> None:
1064 """Test that MAC address-like names are filtered out."""
1065 universal_provider = create_mock_universal_provider(mock_mass)
1066
1067 squeezelite_provider = MockProvider("squeezelite")
1068 airplay_provider = MockProvider("airplay")
1069
1070 # Squeezelite with MAC address as name
1071 sq_player = MockPlayer(
1072 squeezelite_provider,
1073 "sq_123456",
1074 "AA:BB:CC:DD:EE:FF",
1075 player_type=PlayerType.PROTOCOL,
1076 )
1077 # AirPlay with proper name
1078 ap_player = MockPlayer(
1079 airplay_provider,
1080 "ap_123456",
1081 "Kitchen Speaker",
1082 player_type=PlayerType.PROTOCOL,
1083 )
1084
1085 # Should prefer Kitchen Speaker over MAC address
1086 clean_name = universal_provider._get_clean_player_name([sq_player, ap_player])
1087 assert clean_name == "Kitchen Speaker"
1088
1089 def test_filters_player_id_names(self, mock_mass: MagicMock) -> None:
1090 """Test that player ID-like names are filtered out."""
1091 universal_provider = create_mock_universal_provider(mock_mass)
1092
1093 sendspin_provider = MockProvider("sendspin")
1094 dlna_provider = MockProvider("dlna")
1095
1096 # SendSpin with player ID as name
1097 ss_player = MockPlayer(
1098 sendspin_provider,
1099 "sendspin_123456",
1100 "sendspin_device_abc",
1101 player_type=PlayerType.PROTOCOL,
1102 )
1103 # DLNA with proper name
1104 dlna_player = MockPlayer(
1105 dlna_provider,
1106 "dlna_123456",
1107 "Bedroom TV",
1108 player_type=PlayerType.PROTOCOL,
1109 )
1110
1111 # Should prefer Bedroom TV over player ID
1112 clean_name = universal_provider._get_clean_player_name([ss_player, dlna_player])
1113 assert clean_name == "Bedroom TV"
1114
1115 def test_valid_name_unchanged(self, mock_mass: MagicMock) -> None:
1116 """Test that valid names are returned unchanged."""
1117 universal_provider = create_mock_universal_provider(mock_mass)
1118
1119 provider = MockProvider("airplay")
1120 player = MockPlayer(
1121 provider,
1122 "ap_123456",
1123 "HomePod Mini",
1124 player_type=PlayerType.PLAYER,
1125 )
1126
1127 clean_name = universal_provider._get_clean_player_name([player])
1128 assert clean_name == "HomePod Mini"
1129
1130
1131class TestCachedProtocolParentRestore:
1132 """Tests for restoring cached protocol parent links."""
1133
1134 def test_protocol_parent_id_restored_from_config(self, mock_mass: MagicMock) -> None:
1135 """Test that cached protocol_parent_id is loaded and used for immediate linking."""
1136 controller = PlayerController(mock_mass)
1137
1138 # Mock config to return cached parent_id when queried
1139 def mock_config_get(key: str, default: str | None = None) -> str | None:
1140 if "protocol_parent_id" in str(key):
1141 return "native_player_id"
1142 return default
1143
1144 mock_mass.config.get.side_effect = mock_config_get
1145
1146 # Create native player
1147 native_provider = MockProvider("sonos", mass=mock_mass)
1148 native_player = MockPlayer(
1149 native_provider,
1150 "native_player_id",
1151 "Sonos Speaker",
1152 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1153 )
1154
1155 # Create protocol player
1156 dlna_provider = MockProvider("dlna", mass=mock_mass)
1157 protocol_player = MockPlayer(
1158 dlna_provider,
1159 "uuid:RINCON_AABBCCDDEEFF_MR",
1160 "Sonos DLNA",
1161 player_type=PlayerType.PROTOCOL,
1162 )
1163
1164 # Register native player
1165 controller._players = {"native_player_id": native_player}
1166
1167 # Try to link protocol to native - should load cached parent_id
1168 controller._try_link_protocol_to_native(protocol_player)
1169
1170 # Verify protocol_parent_id was set
1171 assert protocol_player.protocol_parent_id == "native_player_id"
1172
1173 # Verify protocol was linked to native player
1174 assert any(
1175 link.output_protocol_id == protocol_player.player_id
1176 for link in native_player.linked_output_protocols
1177 )
1178
1179 def test_missing_cached_parent_schedules_protocol_evaluation(
1180 self, mock_mass: MagicMock
1181 ) -> None:
1182 """Test that a missing cached parent does not block delayed protocol evaluation."""
1183 controller = PlayerController(mock_mass)
1184
1185 # Mock config to return cached parent_id (parent not yet registered)
1186 def mock_config_get(key: str, default: str | None = None) -> str | None:
1187 if "protocol_parent_id" in str(key):
1188 return "native_player_id"
1189 return default
1190
1191 mock_mass.config.get.side_effect = mock_config_get
1192
1193 # Create protocol player
1194 dlna_provider = MockProvider("dlna", mass=mock_mass)
1195 protocol_player = MockPlayer(
1196 dlna_provider,
1197 "uuid:RINCON_AABBCCDDEEFF_MR",
1198 "Sonos DLNA",
1199 player_type=PlayerType.PROTOCOL,
1200 )
1201
1202 # No native player registered yet
1203 controller._players = {}
1204
1205 with patch.object(controller, "_schedule_protocol_evaluation") as mock_schedule:
1206 controller._try_link_protocol_to_native(protocol_player)
1207
1208 # A cached parent that is not registered yet should be handled by the
1209 # delayed evaluation path, not by assigning a dangling in-memory parent.
1210 assert protocol_player.protocol_parent_id is None
1211 mock_schedule.assert_called_once_with(protocol_player)
1212
1213 def test_stale_cache_does_not_claim_a_protocol_waiting_for_its_owner(
1214 self, mock_mass: MagicMock
1215 ) -> None:
1216 """A protocol whose persisted owner is still starting up is not claimed by another parent."""
1217 controller = PlayerController(mock_mass)
1218
1219 store: dict[str, Any] = {
1220 CONF_PLAYERS: {
1221 "ap_shared": {
1222 "provider": "airplay--x",
1223 "player_type": "protocol",
1224 "values": {CONF_PROTOCOL_PARENT_ID: "sonos_owner"},
1225 },
1226 "heos_player": {
1227 "provider": "heos--y",
1228 "player_type": "player",
1229 "values": {"linked_protocol_ids": ["ap_shared"]},
1230 },
1231 "sonos_owner": {
1232 "provider": "sonos--z",
1233 "player_type": "player",
1234 "values": {"linked_protocol_ids": ["ap_shared"]},
1235 },
1236 }
1237 }
1238 _wire_nested_config(mock_mass, store)
1239
1240 # a native player that kept a stale cached id for a protocol it no longer owns
1241 heos_player = MockPlayer(
1242 MockProvider("heos", mass=mock_mass),
1243 "heos_player",
1244 "Old Receiver",
1245 identifiers={IdentifierType.MAC_ADDRESS: "11:22:33:44:55:66"},
1246 )
1247 heos_player.set_initialized()
1248 airplay = MockPlayer(
1249 MockProvider("airplay", mass=mock_mass),
1250 "ap_shared",
1251 "Speaker (AirPlay)",
1252 player_type=PlayerType.PROTOCOL,
1253 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1254 )
1255 airplay.set_initialized()
1256 controller._players = {"heos_player": heos_player, "ap_shared": airplay}
1257
1258 # the persisted owner has not registered yet
1259 controller._try_link_protocol_to_native(airplay)
1260
1261 assert airplay.protocol_parent_id is None
1262 assert heos_player.linked_output_protocols == []
1263 assert mock_mass.loop.call_later.call_args.args[0] == 45.0
1264
1265 # once the owner registers it takes its own protocol
1266 sonos_owner = MockPlayer(
1267 MockProvider("sonos", mass=mock_mass),
1268 "sonos_owner",
1269 "Speaker",
1270 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1271 )
1272 sonos_owner.set_initialized()
1273 controller._players["sonos_owner"] = sonos_owner
1274 controller._try_link_protocols_to_native(sonos_owner)
1275
1276 assert airplay.protocol_parent_id == "sonos_owner"
1277 assert [ # type: ignore[unreachable]
1278 link.output_protocol_id for link in sonos_owner.linked_output_protocols
1279 ] == ["ap_shared"]
1280
1281 def test_identifier_match_does_not_claim_a_protocol_waiting_for_its_owner(
1282 self, mock_mass: MagicMock
1283 ) -> None:
1284 """Identifier matching does not override a protocol's own persisted owner."""
1285 controller = PlayerController(mock_mass)
1286
1287 store: dict[str, Any] = {
1288 CONF_PLAYERS: {
1289 "ap_shared": {
1290 "provider": "airplay--x",
1291 "player_type": "protocol",
1292 "values": {CONF_PROTOCOL_PARENT_ID: "sonos_owner"},
1293 },
1294 "sonos_owner": {"provider": "sonos--z", "player_type": "player", "values": {}},
1295 }
1296 }
1297 _wire_nested_config(mock_mass, store)
1298
1299 # shares identifiers with the protocol but is not its persisted owner
1300 other_native = MockPlayer(
1301 MockProvider("heos", mass=mock_mass),
1302 "heos_player",
1303 "Other Receiver",
1304 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1305 )
1306 other_native.set_initialized()
1307 airplay = MockPlayer(
1308 MockProvider("airplay", mass=mock_mass),
1309 "ap_shared",
1310 "Speaker (AirPlay)",
1311 player_type=PlayerType.PROTOCOL,
1312 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1313 )
1314 airplay.set_initialized()
1315 controller._players = {"heos_player": other_native, "ap_shared": airplay}
1316
1317 controller._try_link_protocol_to_native(airplay)
1318
1319 assert airplay.protocol_parent_id is None
1320 assert other_native.linked_output_protocols == []
1321
1322 def test_other_native_does_not_claim_a_protocol_reserved_for_its_owner(
1323 self, mock_mass: MagicMock
1324 ) -> None:
1325 """A native registering before the persisted owner leaves that owner's protocol alone."""
1326 controller = PlayerController(mock_mass)
1327
1328 store: dict[str, Any] = {
1329 CONF_PLAYERS: {
1330 "ap_shared": {
1331 "provider": "airplay--x",
1332 "player_type": "protocol",
1333 "values": {CONF_PROTOCOL_PARENT_ID: "sonos_owner"},
1334 },
1335 "sonos_owner": {"provider": "sonos--z", "player_type": "player", "values": {}},
1336 }
1337 }
1338 _wire_nested_config(mock_mass, store)
1339
1340 airplay = MockPlayer(
1341 MockProvider("airplay", mass=mock_mass),
1342 "ap_shared",
1343 "Speaker (AirPlay)",
1344 player_type=PlayerType.PROTOCOL,
1345 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1346 )
1347 airplay.set_initialized()
1348 controller._players = {"ap_shared": airplay}
1349
1350 controller._try_link_protocol_to_native(airplay)
1351 assert airplay.protocol_parent_id is None
1352
1353 # another native with a colliding identifier registers before the owner
1354 other_native = MockPlayer(
1355 MockProvider("heos", mass=mock_mass),
1356 "heos_player",
1357 "Other Receiver",
1358 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1359 )
1360 other_native.set_initialized()
1361 controller._players["heos_player"] = other_native
1362 controller._try_link_protocols_to_native(other_native)
1363
1364 assert airplay.protocol_parent_id is None
1365 assert other_native.linked_output_protocols == []
1366
1367 # the owner still gets its own protocol
1368 sonos_owner = MockPlayer(
1369 MockProvider("sonos", mass=mock_mass),
1370 "sonos_owner",
1371 "Speaker",
1372 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1373 )
1374 sonos_owner.set_initialized()
1375 controller._players["sonos_owner"] = sonos_owner
1376 controller._try_link_protocols_to_native(sonos_owner)
1377
1378 assert airplay.protocol_parent_id == "sonos_owner"
1379
1380 @pytest.mark.asyncio
1381 async def test_protocol_links_elsewhere_when_its_owner_never_registers(
1382 self, mock_mass: MagicMock
1383 ) -> None:
1384 """A protocol whose persisted owner never registers still links on delayed evaluation."""
1385 controller = PlayerController(mock_mass)
1386
1387 store: dict[str, Any] = {
1388 CONF_PLAYERS: {
1389 "ap_shared": {
1390 "provider": "airplay--x",
1391 "player_type": "protocol",
1392 "values": {CONF_PROTOCOL_PARENT_ID: "gone_owner"},
1393 },
1394 "heos_player": {
1395 "provider": "heos--y",
1396 "player_type": "player",
1397 "values": {"linked_protocol_ids": ["ap_shared"]},
1398 },
1399 }
1400 }
1401 _wire_nested_config(mock_mass, store)
1402
1403 heos_player = MockPlayer(
1404 MockProvider("heos", mass=mock_mass),
1405 "heos_player",
1406 "Receiver",
1407 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1408 )
1409 heos_player.set_initialized()
1410 airplay = MockPlayer(
1411 MockProvider("airplay", mass=mock_mass),
1412 "ap_shared",
1413 "Speaker (AirPlay)",
1414 player_type=PlayerType.PROTOCOL,
1415 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1416 )
1417 airplay.set_initialized()
1418 controller._players = {"heos_player": heos_player, "ap_shared": airplay}
1419
1420 controller._try_link_protocol_to_native(airplay)
1421 assert airplay.protocol_parent_id is None
1422
1423 await controller._delayed_protocol_evaluation("ap_shared")
1424
1425 assert airplay.protocol_parent_id == "heos_player"
1426
1427 @pytest.mark.asyncio
1428 async def test_cached_parent_registers_before_delayed_eval_links_without_universal(
1429 self, mock_mass: MagicMock
1430 ) -> None:
1431 """Test cached parent startup grace still links when native registers during delay."""
1432 controller = PlayerController(mock_mass)
1433
1434 def mock_config_get(
1435 key: str, default: str | list[str] | None = None
1436 ) -> str | list[str] | None:
1437 if "protocol_parent_id" in str(key):
1438 return "native_player_id"
1439 return default
1440
1441 mock_mass.config.get.side_effect = mock_config_get
1442
1443 dlna_provider = MockProvider("dlna", mass=mock_mass)
1444 protocol_player = MockPlayer(
1445 dlna_provider,
1446 "uuid:RINCON_AABBCCDDEEFF_MR",
1447 "Sonos DLNA",
1448 player_type=PlayerType.PROTOCOL,
1449 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1450 )
1451 protocol_player.set_initialized()
1452 controller._players = {protocol_player.player_id: protocol_player}
1453
1454 controller._try_link_protocol_to_native(protocol_player)
1455
1456 assert protocol_player.protocol_parent_id is None
1457 assert mock_mass.loop.call_later.call_args.args[0] == 45.0
1458
1459 native_provider = MockProvider("sonos", mass=mock_mass)
1460 native_player = MockPlayer(
1461 native_provider,
1462 "native_player_id",
1463 "Sonos Speaker",
1464 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1465 )
1466 native_player.set_initialized()
1467 controller._players[native_player.player_id] = native_player
1468
1469 controller._try_link_protocols_to_native(native_player)
1470
1471 assert protocol_player.protocol_parent_id == native_player.player_id
1472 assert any( # type: ignore[unreachable]
1473 link.output_protocol_id == protocol_player.player_id
1474 for link in native_player.linked_output_protocols
1475 )
1476
1477 with patch.object(controller, "_create_or_update_universal_player") as mock_create_up:
1478 await controller._delayed_protocol_evaluation(protocol_player.player_id)
1479
1480 mock_create_up.assert_not_called()
1481
1482
1483class TestSelectBestOutputProtocol:
1484 """Tests for output protocol selection logic."""
1485
1486 def test_select_native_when_preferred_is_native(self, mock_mass: MagicMock) -> None:
1487 """Test that native protocol is selected when user prefers native."""
1488
1489 # Mock config to return "native" as preferred, but still handle min/max volume
1490 def _get_raw_config(
1491 _player_id: str, key: str, _default: str | int | None = None
1492 ) -> str | int | None:
1493 if key == "min_volume":
1494 return 0
1495 if key == "max_volume":
1496 return 100
1497 return "native"
1498
1499 mock_mass.config.get_raw_player_config_value = MagicMock(side_effect=_get_raw_config)
1500
1501 controller = PlayerController(mock_mass)
1502 provider = MockProvider("sonos", mass=mock_mass)
1503
1504 # Create native player with PLAY_MEDIA support
1505 native_player = MockPlayer(
1506 provider,
1507 "sonos_123",
1508 "Kantoor",
1509 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1510 )
1511 native_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
1512
1513 # Wire up mock_mass.players to controller
1514 mock_mass.players = controller
1515
1516 # Register players
1517 controller._players = {"sonos_123": native_player}
1518
1519 # Select protocol
1520 selected_player, output_protocol = controller._select_best_output_protocol(native_player)
1521
1522 # Should select native player
1523 assert selected_player == native_player
1524 assert output_protocol is None # None means native playback
1525
1526 def test_select_dlna_when_preferred_is_dlna(self, mock_mass: MagicMock) -> None:
1527 """Test that DLNA protocol is selected when user prefers DLNA."""
1528
1529 # Mock config to return the full player ID as preferred, but still handle min/max volume
1530 def _get_raw_config(
1531 _player_id: str, key: str, _default: str | int | None = None
1532 ) -> str | int | None:
1533 if key == "min_volume":
1534 return 0
1535 if key == "max_volume":
1536 return 100
1537 return "dlna_AABBCCDDEEFF"
1538
1539 mock_mass.config.get_raw_player_config_value = MagicMock(side_effect=_get_raw_config)
1540
1541 controller = PlayerController(mock_mass)
1542
1543 # Create native player with linked protocols
1544 sonos_provider = MockProvider("sonos", mass=mock_mass)
1545 native_player = MockPlayer(
1546 sonos_provider,
1547 "sonos_123",
1548 "Kantoor",
1549 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1550 )
1551 native_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
1552
1553 # Create DLNA protocol player
1554 dlna_provider = MockProvider("dlna", mass=mock_mass)
1555 dlna_player = MockPlayer(
1556 dlna_provider,
1557 "dlna_AABBCCDDEEFF",
1558 "Kantoor DLNA",
1559 player_type=PlayerType.PROTOCOL,
1560 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1561 )
1562
1563 # Register players
1564 controller._players = {
1565 "sonos_123": native_player,
1566 "dlna_AABBCCDDEEFF": dlna_player,
1567 }
1568
1569 # Link DLNA protocol to native player
1570 native_player.set_linked_output_protocols(
1571 [
1572 LinkedOutputProtocol(
1573 output_protocol_id="dlna_AABBCCDDEEFF",
1574 protocol_domain="dlna",
1575 priority=50,
1576 )
1577 ]
1578 )
1579
1580 # Select protocol
1581 selected_player, output_protocol = controller._select_best_output_protocol(native_player)
1582
1583 # Should select DLNA player, not native
1584 assert selected_player == dlna_player
1585 assert output_protocol is not None
1586 assert output_protocol.output_protocol_id == "dlna_AABBCCDDEEFF"
1587
1588 def test_select_airplay_when_preferred_is_airplay(self, mock_mass: MagicMock) -> None:
1589 """Test that AirPlay protocol is selected when user prefers AirPlay."""
1590
1591 # Mock config to return the full player ID as preferred, but still handle min/max volume
1592 def _get_raw_config(
1593 _player_id: str, key: str, _default: str | int | None = None
1594 ) -> str | int | None:
1595 if key == "min_volume":
1596 return 0
1597 if key == "max_volume":
1598 return 100
1599 return "airplay_AABBCCDDEEFF"
1600
1601 mock_mass.config.get_raw_player_config_value = MagicMock(side_effect=_get_raw_config)
1602
1603 controller = PlayerController(mock_mass)
1604
1605 # Create native player
1606 sonos_provider = MockProvider("sonos", mass=mock_mass)
1607 native_player = MockPlayer(
1608 sonos_provider,
1609 "sonos_123",
1610 "Kantoor",
1611 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1612 )
1613 native_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
1614
1615 # Create AirPlay and DLNA protocol players
1616 airplay_provider = MockProvider("airplay", mass=mock_mass)
1617 airplay_player = MockPlayer(
1618 airplay_provider,
1619 "airplay_AABBCCDDEEFF",
1620 "Kantoor AirPlay",
1621 player_type=PlayerType.PROTOCOL,
1622 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1623 )
1624
1625 dlna_provider = MockProvider("dlna", mass=mock_mass)
1626 dlna_player = MockPlayer(
1627 dlna_provider,
1628 "dlna_AABBCCDDEEFF",
1629 "Kantoor DLNA",
1630 player_type=PlayerType.PROTOCOL,
1631 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1632 )
1633
1634 # Register players
1635 controller._players = {
1636 "sonos_123": native_player,
1637 "airplay_AABBCCDDEEFF": airplay_player,
1638 "dlna_AABBCCDDEEFF": dlna_player,
1639 }
1640
1641 # Link protocols to native player
1642 native_player.set_linked_output_protocols(
1643 [
1644 LinkedOutputProtocol(
1645 output_protocol_id="airplay_AABBCCDDEEFF",
1646 protocol_domain="airplay",
1647 priority=10,
1648 ),
1649 LinkedOutputProtocol(
1650 output_protocol_id="dlna_AABBCCDDEEFF",
1651 protocol_domain="dlna",
1652 priority=50,
1653 ),
1654 ]
1655 )
1656
1657 # Select protocol
1658 selected_player, output_protocol = controller._select_best_output_protocol(native_player)
1659
1660 # Should select AirPlay player (even though DLNA has lower priority value),
1661 # because user preference overrides priority
1662 assert selected_player == airplay_player
1663 assert output_protocol is not None
1664 assert output_protocol.output_protocol_id == "airplay_AABBCCDDEEFF"
1665
1666 def test_fallback_to_native_when_auto(self, mock_mass: MagicMock) -> None:
1667 """Test that native playback is used when preference is auto."""
1668
1669 # Mock config to return "auto" as preferred, but still handle min/max volume
1670 def _get_raw_config(
1671 _player_id: str, key: str, _default: str | int | None = None
1672 ) -> str | int | None:
1673 if key == "min_volume":
1674 return 0
1675 if key == "max_volume":
1676 return 100
1677 return "auto"
1678
1679 mock_mass.config.get_raw_player_config_value = MagicMock(side_effect=_get_raw_config)
1680
1681 controller = PlayerController(mock_mass)
1682 provider = MockProvider("sonos", mass=mock_mass)
1683
1684 native_player = MockPlayer(
1685 provider,
1686 "sonos_123",
1687 "Kantoor",
1688 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1689 )
1690 native_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
1691
1692 controller._players = {"sonos_123": native_player}
1693
1694 # Select protocol with auto preference
1695 selected_player, output_protocol = controller._select_best_output_protocol(native_player)
1696
1697 # Should select native player
1698 assert selected_player == native_player
1699 assert output_protocol is None # None means native playback
1700
1701 def test_skip_protocol_that_needs_setup(self, mock_mass: MagicMock) -> None:
1702 """Test that a protocol player which still needs setup is never selected."""
1703 controller = PlayerController(mock_mass)
1704
1705 # Universal player wrapping the protocols of a device without native playback
1706 universal_provider = MockProvider("universal_player", mass=mock_mass)
1707 universal_player = MockPlayer(
1708 universal_provider,
1709 "up_AABBCCDDEEFF",
1710 "Living Room TV",
1711 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1712 )
1713
1714 # AirPlay protocol player that is discovered but still awaits pairing
1715 airplay_provider = MockProvider("airplay", mass=mock_mass)
1716 airplay_player = MockPlayer(
1717 airplay_provider,
1718 "airplay_AABBCCDDEEFF",
1719 "Living Room TV AirPlay",
1720 player_type=PlayerType.PROTOCOL,
1721 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1722 )
1723 airplay_player._attr_needs_setup = True
1724
1725 dlna_provider = MockProvider("dlna", mass=mock_mass)
1726 dlna_player = MockPlayer(
1727 dlna_provider,
1728 "dlna_AABBCCDDEEFF",
1729 "Living Room TV DLNA",
1730 player_type=PlayerType.PROTOCOL,
1731 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
1732 )
1733
1734 # Wire up mock_mass.players to controller
1735 mock_mass.players = controller
1736
1737 # Register players
1738 controller._players = {
1739 "up_AABBCCDDEEFF": universal_player,
1740 "airplay_AABBCCDDEEFF": airplay_player,
1741 "dlna_AABBCCDDEEFF": dlna_player,
1742 }
1743
1744 # Link both protocols, AirPlay with the better priority
1745 universal_player.set_linked_output_protocols(
1746 [
1747 LinkedOutputProtocol(
1748 output_protocol_id="airplay_AABBCCDDEEFF",
1749 protocol_domain="airplay",
1750 priority=10,
1751 ),
1752 LinkedOutputProtocol(
1753 output_protocol_id="dlna_AABBCCDDEEFF",
1754 protocol_domain="dlna",
1755 priority=50,
1756 ),
1757 ]
1758 )
1759
1760 selected_player, output_protocol = controller._select_best_output_protocol(universal_player)
1761
1762 # Should skip the unpaired AirPlay output and fall through to DLNA
1763 assert selected_player == dlna_player
1764 assert output_protocol is not None
1765 assert output_protocol.output_protocol_id == "dlna_AABBCCDDEEFF"
1766
1767 # and the unpaired output must be reported as unavailable
1768 universal_player.update_state(signal_event=False)
1769 airplay_output = next(
1770 protocol
1771 for protocol in universal_player.output_protocols
1772 if protocol.output_protocol_id == "airplay_AABBCCDDEEFF"
1773 )
1774 assert airplay_output.available is False
1775
1776
1777class TestGetControlTarget:
1778 """Tests for resolving the target of an audio-path command."""
1779
1780 def test_fallback_follows_protocol_priority(self, mock_mass: MagicMock) -> None:
1781 """
1782 Without an active output the fallback picks the highest priority protocol.
1783
1784 An announcement on an idle player reaches this path, so it has to land on the
1785 same output that regular playback selection would have chosen.
1786 """
1787 controller = PlayerController(mock_mass)
1788 mock_mass.players = controller
1789
1790 universal_provider = MockProvider("universal_player", mass=mock_mass)
1791 universal_player = MockPlayer(universal_provider, "universal_123", "Kantoor")
1792 universal_player._attr_supported_features = set()
1793
1794 sendspin_player = MockPlayer(
1795 MockProvider("sendspin", mass=mock_mass),
1796 "sendspin_AABBCCDDEEFF",
1797 "Kantoor Sendspin",
1798 player_type=PlayerType.PROTOCOL,
1799 )
1800 sendspin_player._attr_supported_features.add(PlayerFeature.PLAY_ANNOUNCEMENT)
1801 airplay_player = MockPlayer(
1802 MockProvider("airplay", mass=mock_mass),
1803 "airplay_AABBCCDDEEFF",
1804 "Kantoor AirPlay",
1805 player_type=PlayerType.PROTOCOL,
1806 )
1807 airplay_player._attr_supported_features.add(PlayerFeature.PLAY_ANNOUNCEMENT)
1808
1809 controller._players = {
1810 "universal_123": universal_player,
1811 "sendspin_AABBCCDDEEFF": sendspin_player,
1812 "airplay_AABBCCDDEEFF": airplay_player,
1813 }
1814 # sendspin links first, but airplay outranks it
1815 universal_player.set_linked_output_protocols(
1816 [
1817 LinkedOutputProtocol(
1818 output_protocol_id="sendspin_AABBCCDDEEFF",
1819 protocol_domain="sendspin",
1820 priority=40,
1821 ),
1822 LinkedOutputProtocol(
1823 output_protocol_id="airplay_AABBCCDDEEFF",
1824 protocol_domain="airplay",
1825 priority=10,
1826 ),
1827 ]
1828 )
1829
1830 target = controller._get_control_target(
1831 universal_player, PlayerFeature.PLAY_ANNOUNCEMENT, require_active=False
1832 )
1833 assert target == airplay_player
1834
1835 def test_fallback_follows_preferred_output_protocol(self, mock_mass: MagicMock) -> None:
1836 """An explicitly preferred output beats the priority order."""
1837 controller = PlayerController(mock_mass)
1838 mock_mass.players = controller
1839
1840 def _get_raw_player_config_value(
1841 _player_id: str, key: str, default: str | int | None = None
1842 ) -> str | int | None:
1843 if key == CONF_PREFERRED_OUTPUT_PROTOCOL:
1844 return "sendspin_AABBCCDDEEFF"
1845 if key == "min_volume":
1846 return 0
1847 if key == "max_volume":
1848 return 100
1849 return default
1850
1851 mock_mass.config.get_raw_player_config_value = MagicMock(
1852 side_effect=_get_raw_player_config_value
1853 )
1854
1855 universal_player = MockPlayer(
1856 MockProvider("universal_player", mass=mock_mass), "universal_123", "Kantoor"
1857 )
1858 universal_player._attr_supported_features = set()
1859 sendspin_player = MockPlayer(
1860 MockProvider("sendspin", mass=mock_mass),
1861 "sendspin_AABBCCDDEEFF",
1862 "Kantoor Sendspin",
1863 player_type=PlayerType.PROTOCOL,
1864 )
1865 sendspin_player._attr_supported_features.add(PlayerFeature.PLAY_ANNOUNCEMENT)
1866 airplay_player = MockPlayer(
1867 MockProvider("airplay", mass=mock_mass),
1868 "airplay_AABBCCDDEEFF",
1869 "Kantoor AirPlay",
1870 player_type=PlayerType.PROTOCOL,
1871 )
1872 airplay_player._attr_supported_features.add(PlayerFeature.PLAY_ANNOUNCEMENT)
1873
1874 controller._players = {
1875 "universal_123": universal_player,
1876 "sendspin_AABBCCDDEEFF": sendspin_player,
1877 "airplay_AABBCCDDEEFF": airplay_player,
1878 }
1879 # airplay outranks sendspin, but the user picked sendspin
1880 universal_player.set_linked_output_protocols(
1881 [
1882 LinkedOutputProtocol(
1883 output_protocol_id="airplay_AABBCCDDEEFF",
1884 protocol_domain="airplay",
1885 priority=10,
1886 ),
1887 LinkedOutputProtocol(
1888 output_protocol_id="sendspin_AABBCCDDEEFF",
1889 protocol_domain="sendspin",
1890 priority=40,
1891 ),
1892 ]
1893 )
1894
1895 target = controller._get_control_target(
1896 universal_player, PlayerFeature.PLAY_ANNOUNCEMENT, require_active=False
1897 )
1898 assert target == sendspin_player
1899
1900 def test_fallback_ignores_preference_for_another_players_output(
1901 self, mock_mass: MagicMock
1902 ) -> None:
1903 """A preference left behind by a relink does not steal another speaker's output."""
1904 controller = PlayerController(mock_mass)
1905 mock_mass.players = controller
1906
1907 def _get_raw_player_config_value(
1908 _player_id: str, key: str, default: str | int | None = None
1909 ) -> str | int | None:
1910 if key == CONF_PREFERRED_OUTPUT_PROTOCOL:
1911 return "airplay_998877665544"
1912 if key == "min_volume":
1913 return 0
1914 if key == "max_volume":
1915 return 100
1916 return default
1917
1918 mock_mass.config.get_raw_player_config_value = MagicMock(
1919 side_effect=_get_raw_player_config_value
1920 )
1921
1922 universal_player = MockPlayer(
1923 MockProvider("universal_player", mass=mock_mass), "universal_123", "Kantoor"
1924 )
1925 universal_player._attr_supported_features = set()
1926 own_player = MockPlayer(
1927 MockProvider("sendspin", mass=mock_mass),
1928 "sendspin_AABBCCDDEEFF",
1929 "Kantoor Sendspin",
1930 player_type=PlayerType.PROTOCOL,
1931 )
1932 own_player._attr_supported_features.add(PlayerFeature.PLAY_ANNOUNCEMENT)
1933 # the preference now points at an output belonging to a different speaker
1934 other_player = MockPlayer(
1935 MockProvider("airplay", mass=mock_mass),
1936 "airplay_998877665544",
1937 "Woonkamer AirPlay",
1938 player_type=PlayerType.PROTOCOL,
1939 )
1940 other_player._attr_supported_features.add(PlayerFeature.PLAY_ANNOUNCEMENT)
1941
1942 controller._players = {
1943 "universal_123": universal_player,
1944 "sendspin_AABBCCDDEEFF": own_player,
1945 "airplay_998877665544": other_player,
1946 }
1947 universal_player.set_linked_output_protocols(
1948 [
1949 LinkedOutputProtocol(
1950 output_protocol_id="sendspin_AABBCCDDEEFF",
1951 protocol_domain="sendspin",
1952 priority=40,
1953 )
1954 ]
1955 )
1956
1957 target = controller._get_control_target(
1958 universal_player, PlayerFeature.PLAY_ANNOUNCEMENT, require_active=False
1959 )
1960 assert target == own_player
1961
1962 def test_require_active_skips_the_fallback(self, mock_mass: MagicMock) -> None:
1963 """With require_active there is no fallback to an idle linked protocol."""
1964 controller = PlayerController(mock_mass)
1965 mock_mass.players = controller
1966
1967 universal_player = MockPlayer(
1968 MockProvider("universal_player", mass=mock_mass),
1969 "universal_123",
1970 "Kantoor",
1971 )
1972 universal_player._attr_supported_features = set()
1973 airplay_player = MockPlayer(
1974 MockProvider("airplay", mass=mock_mass),
1975 "airplay_AABBCCDDEEFF",
1976 "Kantoor AirPlay",
1977 player_type=PlayerType.PROTOCOL,
1978 )
1979 airplay_player._attr_supported_features.add(PlayerFeature.PLAY_ANNOUNCEMENT)
1980
1981 controller._players = {
1982 "universal_123": universal_player,
1983 "airplay_AABBCCDDEEFF": airplay_player,
1984 }
1985 universal_player.set_linked_output_protocols(
1986 [
1987 LinkedOutputProtocol(
1988 output_protocol_id="airplay_AABBCCDDEEFF",
1989 protocol_domain="airplay",
1990 priority=10,
1991 )
1992 ]
1993 )
1994
1995 assert (
1996 controller._get_control_target(
1997 universal_player, PlayerFeature.PLAY_ANNOUNCEMENT, require_active=True
1998 )
1999 is None
2000 )
2001
2002
2003class TestPlayerGrouping:
2004 """Tests for player grouping scenarios."""
2005
2006 def test_native_to_native_grouping(self, mock_mass: MagicMock) -> None:
2007 """Test that native players from same provider can group together."""
2008 controller = PlayerController(mock_mass)
2009
2010 sonos_provider = MockProvider("sonos", mass=mock_mass)
2011
2012 # Create two Sonos players
2013 player_a = MockPlayer(
2014 sonos_provider,
2015 "sonos_123",
2016 "Living Room",
2017 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
2018 )
2019 player_a._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2020 player_a._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2021 player_a._attr_can_group_with = {"sonos_456"}
2022 player_a._cache.clear() # Clear cached properties after modifying attributes
2023
2024 player_b = MockPlayer(
2025 sonos_provider,
2026 "sonos_456",
2027 "Kitchen",
2028 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
2029 )
2030 player_b._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2031 player_b._cache.clear()
2032
2033 controller._players = {
2034 "sonos_123": player_a,
2035 "sonos_456": player_b,
2036 }
2037
2038 # Translate members for native grouping
2039 protocol_members, native_members, _, _ = controller._translate_members_for_protocols(
2040 parent_player=player_a,
2041 player_ids=["sonos_456"],
2042 parent_protocol_player=None,
2043 parent_protocol_domain=None,
2044 )
2045
2046 # Should use native grouping (same provider)
2047 assert len(native_members) == 1
2048 assert "sonos_456" in native_members
2049 assert len(protocol_members) == 0
2050
2051 def test_protocol_to_protocol_grouping(self, mock_mass: MagicMock) -> None:
2052 """Test that protocol players can group via shared protocol."""
2053 controller = PlayerController(mock_mass)
2054
2055 # Create two players with AirPlay protocol support
2056 sonos_provider = MockProvider("sonos", mass=mock_mass)
2057 wiim_provider = MockProvider("wiim", mass=mock_mass)
2058 airplay_provider = MockProvider("airplay", mass=mock_mass)
2059
2060 # Sonos player
2061 sonos_player = MockPlayer(
2062 sonos_provider,
2063 "sonos_123",
2064 "Living Room",
2065 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
2066 )
2067 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2068 sonos_player._cache.clear()
2069
2070 # WiiM player
2071 wiim_player = MockPlayer(
2072 wiim_provider,
2073 "wiim_456",
2074 "Bedroom",
2075 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
2076 )
2077 wiim_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2078 wiim_player._cache.clear()
2079
2080 # AirPlay protocol players
2081 sonos_airplay = MockPlayer(
2082 airplay_provider,
2083 "airplay_sonos",
2084 "Living Room (AirPlay)",
2085 player_type=PlayerType.PROTOCOL,
2086 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
2087 )
2088 sonos_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2089 sonos_airplay._attr_can_group_with = {"airplay_wiim"}
2090 sonos_airplay._cache.clear()
2091 sonos_airplay.update_state(signal_event=False)
2092
2093 wiim_airplay = MockPlayer(
2094 airplay_provider,
2095 "airplay_wiim",
2096 "Bedroom (AirPlay)",
2097 player_type=PlayerType.PROTOCOL,
2098 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
2099 )
2100
2101 # Link protocol players to native players
2102 sonos_player.set_linked_output_protocols(
2103 [
2104 LinkedOutputProtocol(
2105 output_protocol_id="airplay_sonos",
2106 protocol_domain="airplay",
2107 priority=10,
2108 )
2109 ]
2110 )
2111 wiim_player.set_linked_output_protocols(
2112 [
2113 LinkedOutputProtocol(
2114 output_protocol_id="airplay_wiim",
2115 protocol_domain="airplay",
2116 priority=10,
2117 )
2118 ]
2119 )
2120
2121 controller._players = {
2122 "sonos_123": sonos_player,
2123 "wiim_456": wiim_player,
2124 "airplay_sonos": sonos_airplay,
2125 "airplay_wiim": wiim_airplay,
2126 }
2127
2128 # Translate members for protocol grouping (via AirPlay)
2129 protocol_members, native_members, protocol_player, _ = (
2130 controller._translate_members_for_protocols(
2131 parent_player=sonos_player,
2132 player_ids=["wiim_456"],
2133 parent_protocol_player=sonos_airplay,
2134 parent_protocol_domain="airplay",
2135 )
2136 )
2137
2138 # Should use protocol grouping (AirPlay)
2139 assert len(protocol_members) == 1
2140 assert "airplay_wiim" in protocol_members
2141 assert len(native_members) == 0
2142 assert protocol_player == sonos_airplay
2143
2144 def test_hybrid_grouping(self, mock_mass: MagicMock) -> None:
2145 """Test hybrid grouping: native + protocol players in same group."""
2146 controller = PlayerController(mock_mass)
2147
2148 # Create Sonos players (native grouping capability)
2149 sonos_provider = MockProvider("sonos", instance_id="sonos_instance", mass=mock_mass)
2150 sonos_a = MockPlayer(
2151 sonos_provider,
2152 "sonos_123",
2153 "Living Room",
2154 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
2155 )
2156 sonos_a._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2157 sonos_a._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2158 sonos_a._attr_can_group_with = {"sonos_456"}
2159 sonos_a._cache.clear()
2160
2161 sonos_b = MockPlayer(
2162 sonos_provider,
2163 "sonos_456",
2164 "Kitchen",
2165 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
2166 )
2167 sonos_b._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2168 sonos_b._cache.clear()
2169
2170 # Create WiiM player with AirPlay protocol
2171 wiim_provider = MockProvider("wiim", instance_id="wiim_instance", mass=mock_mass)
2172 airplay_provider = MockProvider("airplay", instance_id="airplay_instance", mass=mock_mass)
2173
2174 wiim_player = MockPlayer(
2175 wiim_provider,
2176 "wiim_789",
2177 "Bedroom",
2178 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:03"},
2179 )
2180 wiim_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2181 wiim_player._cache.clear()
2182
2183 # AirPlay protocol players
2184 sonos_airplay = MockPlayer(
2185 airplay_provider,
2186 "airplay_sonos",
2187 "Living Room (AirPlay)",
2188 player_type=PlayerType.PROTOCOL,
2189 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
2190 )
2191 sonos_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2192 sonos_airplay._attr_can_group_with = {"airplay_wiim"}
2193 sonos_airplay._cache.clear()
2194 sonos_airplay.update_state(signal_event=False)
2195
2196 wiim_airplay = MockPlayer(
2197 airplay_provider,
2198 "airplay_wiim",
2199 "Bedroom (AirPlay)",
2200 player_type=PlayerType.PROTOCOL,
2201 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:03"},
2202 )
2203
2204 # Link AirPlay to Sonos A
2205 sonos_a.set_linked_output_protocols(
2206 [
2207 LinkedOutputProtocol(
2208 output_protocol_id="airplay_sonos",
2209 protocol_domain="airplay",
2210 priority=10,
2211 )
2212 ]
2213 )
2214 wiim_player.set_linked_output_protocols(
2215 [
2216 LinkedOutputProtocol(
2217 output_protocol_id="airplay_wiim",
2218 protocol_domain="airplay",
2219 priority=10,
2220 )
2221 ]
2222 )
2223 wiim_player.set_active_output_protocol("airplay_wiim")
2224 wiim_player.set_protocol_parent_id("airplay_wiim")
2225
2226 # Wire up mock_mass.players to controller so player lookups resolve
2227 mock_mass.players = controller
2228
2229 controller._players = {
2230 "sonos_123": sonos_a,
2231 "sonos_456": sonos_b,
2232 "wiim_789": wiim_player,
2233 "airplay_sonos": sonos_airplay,
2234 "airplay_wiim": wiim_airplay,
2235 }
2236
2237 # Group Sonos B (native) + WiiM (via AirPlay) to Sonos A
2238 protocol_members, native_members, _protocol_player, _ = (
2239 controller._translate_members_for_protocols(
2240 parent_player=sonos_a,
2241 player_ids=["sonos_456", "wiim_789"],
2242 parent_protocol_player=sonos_airplay,
2243 parent_protocol_domain="airplay",
2244 )
2245 )
2246
2247 # Should have hybrid group: native Sonos B + protocol WiiM
2248 assert len(native_members) == 1
2249 assert "sonos_456" in native_members
2250 assert len(protocol_members) == 1
2251 assert "airplay_wiim" in protocol_members
2252
2253 def test_protocol_selection_requires_set_members(self, mock_mass: MagicMock) -> None:
2254 """Test that only protocols with SET_MEMBERS support are selected for grouping."""
2255 controller = PlayerController(mock_mass)
2256
2257 sonos_provider = MockProvider("sonos", mass=mock_mass)
2258 wiim_provider = MockProvider("wiim", mass=mock_mass)
2259 dlna_provider = MockProvider("dlna", mass=mock_mass)
2260 airplay_provider = MockProvider("airplay", mass=mock_mass)
2261
2262 # Sonos player
2263 sonos_player = MockPlayer(
2264 sonos_provider,
2265 "sonos_123",
2266 "Living Room",
2267 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
2268 )
2269 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2270 sonos_player._cache.clear()
2271
2272 # WiiM player
2273 wiim_player = MockPlayer(
2274 wiim_provider,
2275 "wiim_456",
2276 "Bedroom",
2277 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
2278 )
2279 wiim_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2280 wiim_player._cache.clear()
2281
2282 # DLNA protocol (does NOT support SET_MEMBERS)
2283 sonos_dlna = MockPlayer(
2284 dlna_provider,
2285 "dlna_sonos",
2286 "Living Room (DLNA)",
2287 player_type=PlayerType.PROTOCOL,
2288 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
2289 )
2290 # Note: NO SET_MEMBERS feature
2291
2292 wiim_dlna = MockPlayer(
2293 dlna_provider,
2294 "dlna_wiim",
2295 "Bedroom (DLNA)",
2296 player_type=PlayerType.PROTOCOL,
2297 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
2298 )
2299
2300 # AirPlay protocol (DOES support SET_MEMBERS)
2301 sonos_airplay = MockPlayer(
2302 airplay_provider,
2303 "airplay_sonos",
2304 "Living Room (AirPlay)",
2305 player_type=PlayerType.PROTOCOL,
2306 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
2307 )
2308 sonos_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2309 sonos_airplay._attr_can_group_with = {"airplay_wiim"}
2310 sonos_airplay._cache.clear()
2311
2312 wiim_airplay = MockPlayer(
2313 airplay_provider,
2314 "airplay_wiim",
2315 "Bedroom (AirPlay)",
2316 player_type=PlayerType.PROTOCOL,
2317 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
2318 )
2319 wiim_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2320 wiim_airplay._attr_can_group_with = {"airplay_sonos"}
2321 wiim_airplay._cache.clear()
2322
2323 # Link protocols (DLNA has lower priority than AirPlay)
2324 sonos_player.set_linked_output_protocols(
2325 [
2326 LinkedOutputProtocol(
2327 output_protocol_id="dlna_sonos",
2328 protocol_domain="dlna",
2329 priority=50, # Lower priority (higher number)
2330 ),
2331 LinkedOutputProtocol(
2332 output_protocol_id="airplay_sonos",
2333 protocol_domain="airplay",
2334 priority=10, # Higher priority (lower number)
2335 ),
2336 ]
2337 )
2338 wiim_player.set_linked_output_protocols(
2339 [
2340 LinkedOutputProtocol(
2341 output_protocol_id="dlna_wiim",
2342 protocol_domain="dlna",
2343 priority=50,
2344 ),
2345 LinkedOutputProtocol(
2346 output_protocol_id="airplay_wiim",
2347 protocol_domain="airplay",
2348 priority=10,
2349 ),
2350 ]
2351 )
2352
2353 mock_mass.players = controller
2354 controller._players = {
2355 "sonos_123": sonos_player,
2356 "wiim_456": wiim_player,
2357 "dlna_sonos": sonos_dlna,
2358 "dlna_wiim": wiim_dlna,
2359 "airplay_sonos": sonos_airplay,
2360 "airplay_wiim": wiim_airplay,
2361 }
2362
2363 # Update state after modifying attributes
2364 sonos_dlna.update_state(signal_event=False)
2365 wiim_dlna.update_state(signal_event=False)
2366 sonos_airplay.update_state(signal_event=False)
2367 wiim_airplay.update_state(signal_event=False)
2368
2369 # Translate members - should skip DLNA (no SET_MEMBERS) and select AirPlay
2370 protocol_members, _native_members, protocol_player, protocol_domain = (
2371 controller._translate_members_for_protocols(
2372 parent_player=sonos_player,
2373 player_ids=["wiim_456"],
2374 parent_protocol_player=None,
2375 parent_protocol_domain=None,
2376 )
2377 )
2378
2379 # Should select AirPlay (supports SET_MEMBERS) not DLNA
2380 assert len(protocol_members) == 1
2381 assert "airplay_wiim" in protocol_members
2382 assert protocol_domain == "airplay"
2383 assert protocol_player == sonos_airplay
2384
2385 # A group already on DLNA must be moved off it as well, because DLNA cannot
2386 # group members itself
2387 protocol_members, _native_members, protocol_player, protocol_domain = (
2388 controller._translate_members_for_protocols(
2389 parent_player=sonos_player,
2390 player_ids=["wiim_456"],
2391 parent_protocol_player=sonos_dlna,
2392 parent_protocol_domain="dlna",
2393 )
2394 )
2395
2396 assert protocol_members == ["airplay_wiim"]
2397 assert protocol_domain == "airplay"
2398 assert protocol_player == sonos_airplay
2399
2400
2401class TestJoinActiveNativeSession:
2402 """
2403 Grouping a child onto a parent that is already playing natively.
2404
2405 A child's preferred output protocol must only steer protocol selection when the child
2406 initiates its own playback. When the child joins a parent that already holds an active
2407 native session, it should adopt native grouping if compatible, instead of forcing the
2408 whole group onto the child's preferred protocol.
2409 """
2410
2411 @staticmethod
2412 def _mark_native_playing(player: MockPlayer) -> None:
2413 """Put the player into a live native playback session."""
2414 player._attr_playback_state = PlaybackState.PLAYING
2415 player._cache.clear()
2416 player.set_active_output_protocol("native")
2417
2418 @staticmethod
2419 def _link_airplay(native_player: MockPlayer, airplay_id: str) -> None:
2420 """Link an AirPlay protocol player to a native player."""
2421 native_player.set_linked_output_protocols(
2422 [
2423 LinkedOutputProtocol(
2424 output_protocol_id=airplay_id,
2425 protocol_domain="airplay",
2426 priority=10,
2427 )
2428 ]
2429 )
2430
2431 def _build_topology(
2432 self, mock_mass: MagicMock
2433 ) -> tuple[PlayerController, dict[str, MockPlayer]]:
2434 """
2435 Build parent Sonos A + child Sonos B, both AirPlay-capable and natively groupable.
2436
2437 The parent also exposes an AirPlay protocol player that supports SET_MEMBERS, so the
2438 child's preferred AirPlay protocol *would* be selectable if it were given priority.
2439 """
2440 controller = PlayerController(mock_mass)
2441 sonos_provider = MockProvider("sonos", instance_id="sonos_instance", mass=mock_mass)
2442 airplay_provider = MockProvider("airplay", instance_id="airplay_instance", mass=mock_mass)
2443
2444 sonos_a = MockPlayer(
2445 sonos_provider,
2446 "sonos_a",
2447 "Office",
2448 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
2449 )
2450 sonos_a._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2451 sonos_a._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2452 sonos_a._attr_can_group_with = {"sonos_b"}
2453 sonos_a._cache.clear()
2454
2455 sonos_b = MockPlayer(
2456 sonos_provider,
2457 "sonos_b",
2458 "Bathroom",
2459 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
2460 )
2461 sonos_b._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2462 sonos_b._attr_can_group_with = {"sonos_a"}
2463 sonos_b._cache.clear()
2464
2465 airplay_a = MockPlayer(
2466 airplay_provider,
2467 "airplay_a",
2468 "Office (AirPlay)",
2469 player_type=PlayerType.PROTOCOL,
2470 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
2471 )
2472 airplay_a._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2473 airplay_a._attr_can_group_with = {"airplay_b"}
2474 airplay_a._cache.clear()
2475
2476 airplay_b = MockPlayer(
2477 airplay_provider,
2478 "airplay_b",
2479 "Bathroom (AirPlay)",
2480 player_type=PlayerType.PROTOCOL,
2481 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
2482 )
2483 airplay_b._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2484 airplay_b._attr_can_group_with = {"airplay_a"}
2485 airplay_b._cache.clear()
2486
2487 self._link_airplay(sonos_a, "airplay_a")
2488 self._link_airplay(sonos_b, "airplay_b")
2489
2490 mock_mass.players = controller
2491 players = {
2492 "sonos_a": sonos_a,
2493 "sonos_b": sonos_b,
2494 "airplay_a": airplay_a,
2495 "airplay_b": airplay_b,
2496 }
2497 controller._players = dict(players)
2498 for player in players.values():
2499 player.update_state(signal_event=False)
2500 return controller, players
2501
2502 def _add_airplay_only_child(
2503 self, controller: PlayerController, players: dict[str, MockPlayer], mock_mass: MagicMock
2504 ) -> None:
2505 """
2506 Add a WiiM child that can only group via AirPlay (no native grouping with Sonos).
2507
2508 Different provider instance and absent from the parent's can_group_with, so
2509 _can_use_native_grouping returns False for it.
2510 """
2511 wiim_provider = MockProvider("wiim", instance_id="wiim_instance", mass=mock_mass)
2512 airplay_provider = MockProvider("airplay", instance_id="airplay_instance", mass=mock_mass)
2513 wiim_c = MockPlayer(
2514 wiim_provider,
2515 "wiim_c",
2516 "Bedroom",
2517 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:03"},
2518 )
2519 wiim_c._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2520 wiim_c._cache.clear()
2521 airplay_c = MockPlayer(
2522 airplay_provider,
2523 "airplay_c",
2524 "Bedroom (AirPlay)",
2525 player_type=PlayerType.PROTOCOL,
2526 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:03"},
2527 )
2528 airplay_c._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2529 airplay_c._attr_can_group_with = {"airplay_a"}
2530 airplay_c._cache.clear()
2531 self._link_airplay(wiim_c, "airplay_c")
2532 # Allow the parent's AirPlay protocol to group with the new AirPlay child.
2533 players["airplay_a"]._attr_can_group_with = {"airplay_b", "airplay_c"}
2534 players["airplay_a"]._cache.clear()
2535 controller._players["wiim_c"] = wiim_c
2536 controller._players["airplay_c"] = airplay_c
2537 wiim_c.update_state(signal_event=False)
2538 airplay_c.update_state(signal_event=False)
2539
2540 def test_native_active_parent_ignores_child_preferred_protocol(
2541 self, mock_mass: MagicMock
2542 ) -> None:
2543 """A child joining a natively-playing parent groups natively, not via preferred AirPlay."""
2544
2545 def _get_raw(
2546 player_id: str, key: str, default: str | int | None = None
2547 ) -> str | int | None:
2548 if key == CONF_PREFERRED_OUTPUT_PROTOCOL and player_id == "sonos_b":
2549 return "airplay_b"
2550 if key == "min_volume":
2551 return 0
2552 if key == "max_volume":
2553 return 100
2554 return default
2555
2556 mock_mass.config.get_raw_player_config_value = MagicMock(side_effect=_get_raw)
2557
2558 controller, players = self._build_topology(mock_mass)
2559 # Parent A is already playing natively.
2560 self._mark_native_playing(players["sonos_a"])
2561
2562 protocol_members, native_members, _, _ = controller._translate_members_for_protocols(
2563 parent_player=players["sonos_a"],
2564 player_ids=["sonos_b"],
2565 parent_protocol_player=None,
2566 parent_protocol_domain=None,
2567 )
2568
2569 # Native grouping is used; the child's AirPlay preference is ignored on join.
2570 assert native_members == ["sonos_b"]
2571 assert protocol_members == []
2572
2573 def test_fresh_group_still_honors_child_preferred_protocol(self, mock_mass: MagicMock) -> None:
2574 """When the parent is not playing, the child's preferred protocol still steers selection."""
2575
2576 def _get_raw(
2577 player_id: str, key: str, default: str | int | None = None
2578 ) -> str | int | None:
2579 if key == CONF_PREFERRED_OUTPUT_PROTOCOL and player_id == "sonos_b":
2580 return "airplay_b"
2581 if key == "min_volume":
2582 return 0
2583 if key == "max_volume":
2584 return 100
2585 return default
2586
2587 mock_mass.config.get_raw_player_config_value = MagicMock(side_effect=_get_raw)
2588
2589 controller, players = self._build_topology(mock_mass)
2590 # Parent A has no active session (active_output_protocol stays None).
2591 assert players["sonos_a"].active_output_protocol is None
2592
2593 protocol_members, native_members, _, protocol_domain = (
2594 controller._translate_members_for_protocols(
2595 parent_player=players["sonos_a"],
2596 player_ids=["sonos_b"],
2597 parent_protocol_player=None,
2598 parent_protocol_domain=None,
2599 )
2600 )
2601
2602 # Same topology as the active-native case, but here the preference applies.
2603 assert protocol_members == ["airplay_b"]
2604 assert native_members == []
2605 assert protocol_domain == "airplay"
2606
2607 def test_idle_parent_with_stale_native_protocol_honors_child_preferred(
2608 self, mock_mass: MagicMock
2609 ) -> None:
2610 """A stopped parent (active protocol lingers briefly) does not force the native-join path."""
2611
2612 def _get_raw(
2613 player_id: str, key: str, default: str | int | None = None
2614 ) -> str | int | None:
2615 if key == CONF_PREFERRED_OUTPUT_PROTOCOL and player_id == "sonos_b":
2616 return "airplay_b"
2617 if key == "min_volume":
2618 return 0
2619 if key == "max_volume":
2620 return 100
2621 return default
2622
2623 mock_mass.config.get_raw_player_config_value = MagicMock(side_effect=_get_raw)
2624
2625 controller, players = self._build_topology(mock_mass)
2626 # Parent A stopped: active protocol still reads "native" but playback is idle.
2627 players["sonos_a"].set_active_output_protocol("native")
2628 assert players["sonos_a"].state.playback_state == PlaybackState.IDLE
2629
2630 protocol_members, native_members, _, protocol_domain = (
2631 controller._translate_members_for_protocols(
2632 parent_player=players["sonos_a"],
2633 player_ids=["sonos_b"],
2634 parent_protocol_player=None,
2635 parent_protocol_domain=None,
2636 )
2637 )
2638
2639 # No live session to join, so the child's preference applies.
2640 assert protocol_members == ["airplay_b"]
2641 assert native_members == []
2642 assert protocol_domain == "airplay"
2643
2644 def test_native_active_parent_airplay_only_child_uses_protocol(
2645 self, mock_mass: MagicMock
2646 ) -> None:
2647 """An AirPlay-only child (cannot group natively) still joins via its preferred protocol."""
2648
2649 def _get_raw(
2650 player_id: str, key: str, default: str | int | None = None
2651 ) -> str | int | None:
2652 if key == CONF_PREFERRED_OUTPUT_PROTOCOL and player_id == "wiim_c":
2653 return "airplay_c"
2654 if key == "min_volume":
2655 return 0
2656 if key == "max_volume":
2657 return 100
2658 return default
2659
2660 mock_mass.config.get_raw_player_config_value = MagicMock(side_effect=_get_raw)
2661
2662 controller, players = self._build_topology(mock_mass)
2663 self._add_airplay_only_child(controller, players, mock_mass)
2664 self._mark_native_playing(players["sonos_a"])
2665
2666 protocol_members, native_members, _, protocol_domain = (
2667 controller._translate_members_for_protocols(
2668 parent_player=players["sonos_a"],
2669 player_ids=["wiim_c"],
2670 parent_protocol_player=None,
2671 parent_protocol_domain=None,
2672 )
2673 )
2674
2675 # No native path exists for the WiiM, so it falls back to AirPlay grouping.
2676 assert protocol_members == ["airplay_c"]
2677 assert native_members == []
2678 assert protocol_domain == "airplay"
2679
2680 def test_native_active_parent_protocol_only_child_switches_via_common_protocol(
2681 self, mock_mass: MagicMock
2682 ) -> None:
2683 """
2684 A child with no native path (and no explicit preference) still forces the switch.
2685
2686 Even without a configured preferred protocol, a child that can only reach the group via
2687 a shared protocol (here AirPlay, which the natively-playing parent also supports) is
2688 grouped via that protocol - moving the group onto it.
2689 """
2690 controller, players = self._build_topology(mock_mass)
2691 self._add_airplay_only_child(controller, players, mock_mass)
2692 self._mark_native_playing(players["sonos_a"])
2693
2694 # No preferred_output_protocol override - the WiiM resolves via the common-protocol path.
2695 protocol_members, native_members, _, protocol_domain = (
2696 controller._translate_members_for_protocols(
2697 parent_player=players["sonos_a"],
2698 player_ids=["wiim_c"],
2699 parent_protocol_player=None,
2700 parent_protocol_domain=None,
2701 )
2702 )
2703
2704 assert protocol_members == ["airplay_c"]
2705 assert native_members == []
2706 assert protocol_domain == "airplay"
2707
2708 @pytest.mark.parametrize(
2709 "member_order",
2710 [["wiim_c", "sonos_b"], ["sonos_b", "wiim_c"]],
2711 )
2712 def test_native_active_parent_keeps_mixed_batch_cohesive(
2713 self, mock_mass: MagicMock, member_order: list[str]
2714 ) -> None:
2715 """
2716 A mixed batch stays cohesive on one protocol regardless of member order.
2717
2718 When an AirPlay-only child forces the group onto AirPlay, the natively-groupable Sonos
2719 child adopts that same protocol rather than splitting off into a native sub-group -
2720 whether it is added before or after the AirPlay-only child.
2721 """
2722 controller, players = self._build_topology(mock_mass)
2723 self._add_airplay_only_child(controller, players, mock_mass)
2724 self._mark_native_playing(players["sonos_a"])
2725
2726 protocol_members, native_members, _, protocol_domain = (
2727 controller._translate_members_for_protocols(
2728 parent_player=players["sonos_a"],
2729 player_ids=member_order,
2730 parent_protocol_player=None,
2731 parent_protocol_domain=None,
2732 )
2733 )
2734
2735 assert native_members == []
2736 assert set(protocol_members) == {"airplay_c", "airplay_b"}
2737 assert protocol_domain == "airplay"
2738
2739
2740class TestSessionBoundNativeGrouping:
2741 """
2742 Grouping a parent whose native grouping only works while it renders its own stream.
2743
2744 Such native members are attached to that very stream, so they cannot stay natively
2745 grouped once the group is moved onto one of the parent's output protocols. Parents
2746 with device-side native grouping are unaffected and keep their hybrid groups.
2747 """
2748
2749 @staticmethod
2750 def _link_bridge(player: MockPlayer, bridge_id: str) -> None:
2751 """Link a bridge protocol player to a native player."""
2752 player.set_linked_output_protocols(
2753 [
2754 LinkedOutputProtocol(
2755 output_protocol_id=bridge_id,
2756 protocol_domain="sendspin",
2757 priority=40,
2758 )
2759 ]
2760 )
2761
2762 def _build_topology(
2763 self,
2764 mock_mass: MagicMock,
2765 parent_class: type[MockPlayer],
2766 with_orphan: bool = False,
2767 ) -> tuple[PlayerController, dict[str, MockPlayer]]:
2768 """
2769 Build a leader with a natively groupable member and a bridge-only member.
2770
2771 The leader and its member speak the same (speaker) provider, so they group natively.
2772 Both also expose a bridge protocol player, which is the only way to reach the third
2773 member: a native player of the bridge domain.
2774
2775 :param mock_mass: The mocked MusicAssistant instance.
2776 :param parent_class: The player class to build the leader from.
2777 :param with_orphan: Add a second natively groupable member without a bridge protocol.
2778 """
2779 controller = PlayerController(mock_mass)
2780 speaker_provider = MockProvider("speaker", instance_id="speaker_instance", mass=mock_mass)
2781 bridge_provider = MockProvider("sendspin", instance_id="sendspin_instance", mass=mock_mass)
2782
2783 leader = parent_class(speaker_provider, "speaker_leader", "Living Room")
2784 leader._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2785 leader._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2786 leader._cache.clear()
2787
2788 member = MockPlayer(speaker_provider, "speaker_member", "Kitchen")
2789 member._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2790 member._cache.clear()
2791
2792 bridge_leader = MockPlayer(
2793 bridge_provider,
2794 "bridge_leader",
2795 "Living Room (Bridge)",
2796 player_type=PlayerType.PROTOCOL,
2797 )
2798 bridge_leader._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2799 bridge_leader._cache.clear()
2800 bridge_leader.set_protocol_parent_id("speaker_leader")
2801
2802 bridge_member = MockPlayer(
2803 bridge_provider,
2804 "bridge_member",
2805 "Kitchen (Bridge)",
2806 player_type=PlayerType.PROTOCOL,
2807 )
2808 bridge_member._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2809 bridge_member._cache.clear()
2810 bridge_member.set_protocol_parent_id("speaker_member")
2811
2812 # native player of the bridge domain: only reachable through the bridge protocol
2813 bridge_only = MockPlayer(bridge_provider, "bridge_only", "Voice Assistant")
2814 bridge_only._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2815 bridge_only._cache.clear()
2816
2817 self._link_bridge(leader, "bridge_leader")
2818 self._link_bridge(member, "bridge_member")
2819
2820 players: dict[str, MockPlayer] = {
2821 "speaker_leader": leader,
2822 "speaker_member": member,
2823 "bridge_leader": bridge_leader,
2824 "bridge_member": bridge_member,
2825 "bridge_only": bridge_only,
2826 }
2827 if with_orphan:
2828 orphan = MockPlayer(speaker_provider, "speaker_orphan", "Bedroom")
2829 orphan._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2830 orphan._cache.clear()
2831 players["speaker_orphan"] = orphan
2832
2833 mock_mass.players = controller
2834 controller._players = dict(players)
2835 for player in players.values():
2836 player.update_state(signal_event=False)
2837 return controller, players
2838
2839 @pytest.mark.parametrize(
2840 "member_order",
2841 [
2842 ["speaker_member", "bridge_only"],
2843 ["bridge_only", "speaker_member"],
2844 ],
2845 )
2846 def test_native_members_follow_the_group_protocol(
2847 self, mock_mass: MagicMock, member_order: list[str]
2848 ) -> None:
2849 """A natively groupable member moves onto the protocol the group ends up on."""
2850 controller, players = self._build_topology(mock_mass, SessionBoundMockPlayer)
2851
2852 protocol_members, native_members, _, protocol_domain = (
2853 controller._translate_members_for_protocols(
2854 parent_player=players["speaker_leader"],
2855 player_ids=member_order,
2856 parent_protocol_player=None,
2857 parent_protocol_domain=None,
2858 )
2859 )
2860
2861 assert native_members == []
2862 assert set(protocol_members) == {"bridge_only", "bridge_member"}
2863 assert protocol_domain == "sendspin"
2864
2865 def test_member_without_the_group_protocol_is_refused(
2866 self, mock_mass: MagicMock, caplog: pytest.LogCaptureFixture
2867 ) -> None:
2868 """A native member that lacks the group's protocol is dropped, the others still move."""
2869 controller, players = self._build_topology(
2870 mock_mass, SessionBoundMockPlayer, with_orphan=True
2871 )
2872
2873 with caplog.at_level(logging.WARNING):
2874 protocol_members, native_members, _, _ = controller._translate_members_for_protocols(
2875 parent_player=players["speaker_leader"],
2876 player_ids=["speaker_member", "speaker_orphan", "bridge_only"],
2877 parent_protocol_player=None,
2878 parent_protocol_domain=None,
2879 )
2880
2881 assert native_members == []
2882 assert set(protocol_members) == {"bridge_only", "bridge_member"}
2883 assert (
2884 "Cannot group Bedroom with Living Room: the group plays through the sendspin "
2885 "protocol, which Bedroom does not support" in caplog.text
2886 )
2887
2888 def test_device_side_parent_keeps_its_hybrid_group(self, mock_mass: MagicMock) -> None:
2889 """A parent with device-side native grouping keeps its members natively grouped."""
2890 controller, players = self._build_topology(mock_mass, MockPlayer)
2891
2892 protocol_members, native_members, _, protocol_domain = (
2893 controller._translate_members_for_protocols(
2894 parent_player=players["speaker_leader"],
2895 player_ids=["speaker_member", "bridge_only"],
2896 parent_protocol_player=None,
2897 parent_protocol_domain=None,
2898 )
2899 )
2900
2901 assert native_members == ["speaker_member"]
2902 assert protocol_members == ["bridge_only"]
2903 assert protocol_domain == "sendspin"
2904
2905
2906class TestCanGroupWith:
2907 """Tests for can_group_with property with three scenarios."""
2908
2909 def test_scenario_1_native_active_only_native_players(self, mock_mass: MagicMock) -> None:
2910 """Test Scenario 1: Native playback active -> all protocols shown (new behavior)."""
2911 controller = PlayerController(mock_mass)
2912
2913 sonos_provider = MockProvider("sonos", instance_id="sonos_instance", mass=mock_mass)
2914 airplay_provider = MockProvider("airplay", instance_id="airplay_instance", mass=mock_mass)
2915
2916 # Create Sonos player with native and AirPlay support
2917 sonos_player = MockPlayer(
2918 sonos_provider,
2919 "sonos_123",
2920 "Living Room",
2921 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
2922 )
2923 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2924 sonos_player._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2925 sonos_player._attr_can_group_with = {"sonos_456"}
2926 sonos_player._cache.clear()
2927 sonos_player.set_active_output_protocol("native")
2928
2929 # Create another Sonos player
2930 sonos_player_b = MockPlayer(
2931 sonos_provider,
2932 "sonos_456",
2933 "Kitchen",
2934 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
2935 )
2936
2937 # Create AirPlay protocol player
2938 sonos_airplay = MockPlayer(
2939 airplay_provider,
2940 "airplay_sonos",
2941 "Living Room (AirPlay)",
2942 player_type=PlayerType.PROTOCOL,
2943 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
2944 )
2945 sonos_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2946 sonos_airplay._attr_can_group_with = {"airplay_other"}
2947 sonos_airplay._cache.clear()
2948 sonos_airplay.set_protocol_parent_id("sonos_123")
2949
2950 sonos_player.set_linked_output_protocols(
2951 [
2952 LinkedOutputProtocol(
2953 output_protocol_id="airplay_sonos",
2954 protocol_domain="airplay",
2955 priority=10,
2956 )
2957 ]
2958 )
2959
2960 # Wire up mock_mass.players to controller so player lookups resolve
2961 mock_mass.players = controller
2962
2963 controller._players = {
2964 "sonos_123": sonos_player,
2965 "sonos_456": sonos_player_b,
2966 "airplay_sonos": sonos_airplay,
2967 }
2968
2969 # Update state after modifying attributes and registering with controller
2970 sonos_player.update_state(signal_event=False)
2971 sonos_player_b.update_state(signal_event=False)
2972 sonos_airplay.update_state(signal_event=False)
2973
2974 # Get can_group_with while native is active
2975 groupable = sonos_player.state.can_group_with
2976
2977 # NEW BEHAVIOR: Should show both native AND protocol players
2978 # even when native protocol is active
2979 assert "sonos_456" in groupable # Native Sonos player
2980 # Note: airplay_other is not registered in controller._players, so it won't appear
2981 # But the logic should still allow showing AirPlay options if they were registered
2982
2983 def test_scenario_2_protocol_active_hybrid_groups(self, mock_mass: MagicMock) -> None:
2984 """Test Scenario 2: Protocol active -> show all protocols (new behavior)."""
2985 controller = PlayerController(mock_mass)
2986
2987 sonos_provider = MockProvider("sonos", instance_id="sonos_instance", mass=mock_mass)
2988 airplay_provider = MockProvider("airplay", instance_id="airplay_instance", mass=mock_mass)
2989
2990 # Create Sonos player with AirPlay active
2991 sonos_player = MockPlayer(
2992 sonos_provider,
2993 "sonos_123",
2994 "Living Room",
2995 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
2996 )
2997 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
2998 sonos_player._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
2999 sonos_player._attr_can_group_with = {"sonos_456"}
3000 sonos_player._cache.clear()
3001
3002 # Create another Sonos player
3003 sonos_player_b = MockPlayer(
3004 sonos_provider,
3005 "sonos_456",
3006 "Kitchen",
3007 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
3008 )
3009
3010 # Create AirPlay protocol player
3011 sonos_airplay = MockPlayer(
3012 airplay_provider,
3013 "airplay_sonos",
3014 "Living Room (AirPlay)",
3015 player_type=PlayerType.PROTOCOL,
3016 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
3017 )
3018 sonos_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3019 sonos_airplay._attr_can_group_with = {"airplay_other"}
3020 sonos_airplay._cache.clear()
3021 sonos_airplay.set_protocol_parent_id("sonos_123")
3022
3023 # Create another device with AirPlay
3024 wiim_player = MockPlayer(
3025 sonos_provider,
3026 "wiim_789",
3027 "Bedroom",
3028 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:03"},
3029 )
3030
3031 airplay_other = MockPlayer(
3032 airplay_provider,
3033 "airplay_other",
3034 "Bedroom (AirPlay)",
3035 player_type=PlayerType.PROTOCOL,
3036 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:03"},
3037 )
3038 airplay_other._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3039 airplay_other._attr_can_group_with = {"airplay_sonos"}
3040 airplay_other._cache.clear()
3041 airplay_other.set_protocol_parent_id("wiim_789")
3042
3043 wiim_player.set_linked_output_protocols(
3044 [
3045 LinkedOutputProtocol(
3046 output_protocol_id="airplay_other",
3047 protocol_domain="airplay",
3048 priority=10,
3049 ),
3050 ]
3051 )
3052
3053 sonos_player.set_linked_output_protocols(
3054 [
3055 LinkedOutputProtocol(
3056 output_protocol_id="airplay_sonos",
3057 protocol_domain="airplay",
3058 priority=10,
3059 )
3060 ]
3061 )
3062 sonos_player.set_active_output_protocol("airplay_sonos")
3063
3064 # Wire up mock_mass.players to controller so player lookups resolve
3065 mock_mass.players = controller
3066
3067 controller._players = {
3068 "sonos_123": sonos_player,
3069 "sonos_456": sonos_player_b,
3070 "wiim_789": wiim_player,
3071 "airplay_sonos": sonos_airplay,
3072 "airplay_other": airplay_other,
3073 }
3074
3075 # Clear cache after setting linked protocols
3076 sonos_player._cache.clear()
3077 wiim_player._cache.clear()
3078
3079 # Refresh state after modifying attributes and registering with controller
3080 # (refresh_state: registration changed cross-player state without the
3081 # production fan-out running, as events are suppressed in this test)
3082 # IMPORTANT: Update protocol players FIRST, then parent players
3083 sonos_airplay.refresh_state(signal_event=False)
3084 airplay_other.refresh_state(signal_event=False)
3085 sonos_player.refresh_state(signal_event=False)
3086 sonos_player_b.refresh_state(signal_event=False)
3087 wiim_player.refresh_state(signal_event=False)
3088
3089 # Get can_group_with while AirPlay is active
3090 groupable = sonos_player.state.can_group_with
3091
3092 # NEW BEHAVIOR: Should show ALL protocols + native players
3093 # regardless of which protocol is active
3094 assert "sonos_456" in groupable # Native Sonos player
3095 assert "wiim_789" in groupable # Via airplay_other protocol
3096
3097 def test_scenario_3_no_active_output_all_protocols_shown(self, mock_mass: MagicMock) -> None:
3098 """Test Scenario 3: No active output -> show all compatible protocols + native."""
3099 controller = PlayerController(mock_mass)
3100
3101 sonos_provider = MockProvider("sonos", instance_id="sonos_instance", mass=mock_mass)
3102 airplay_provider = MockProvider("airplay", instance_id="airplay_instance", mass=mock_mass)
3103 dlna_provider = MockProvider("dlna", instance_id="dlna_instance", mass=mock_mass)
3104
3105 # Create Sonos player (no active protocol)
3106 sonos_player = MockPlayer(
3107 sonos_provider,
3108 "sonos_123",
3109 "Living Room",
3110 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
3111 )
3112 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
3113 sonos_player._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3114 sonos_player._attr_can_group_with = {"sonos_456"}
3115 sonos_player._cache.clear()
3116 # No active output protocol set
3117
3118 # Create another Sonos player
3119 sonos_player_b = MockPlayer(
3120 sonos_provider,
3121 "sonos_456",
3122 "Kitchen",
3123 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
3124 )
3125
3126 # Create AirPlay protocol player (supports SET_MEMBERS)
3127 sonos_airplay = MockPlayer(
3128 airplay_provider,
3129 "airplay_sonos",
3130 "Living Room (AirPlay)",
3131 player_type=PlayerType.PROTOCOL,
3132 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
3133 )
3134 sonos_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3135 sonos_airplay._attr_can_group_with = {"airplay_other"}
3136 sonos_airplay._cache.clear()
3137 sonos_airplay.set_protocol_parent_id("sonos_123")
3138
3139 # Create DLNA protocol player (does NOT support SET_MEMBERS)
3140 sonos_dlna = MockPlayer(
3141 dlna_provider,
3142 "dlna_sonos",
3143 "Living Room (DLNA)",
3144 player_type=PlayerType.PROTOCOL,
3145 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
3146 )
3147 # No SET_MEMBERS support
3148 sonos_dlna._attr_can_group_with = {"dlna_other"}
3149 sonos_dlna.set_protocol_parent_id("sonos_123")
3150
3151 # Another device
3152 wiim_player = MockPlayer(
3153 sonos_provider,
3154 "wiim_789",
3155 "Bedroom",
3156 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:03"},
3157 )
3158
3159 airplay_other = MockPlayer(
3160 airplay_provider,
3161 "airplay_other",
3162 "Bedroom (AirPlay)",
3163 player_type=PlayerType.PROTOCOL,
3164 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:03"},
3165 )
3166 airplay_other._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3167 airplay_other._attr_can_group_with = {"airplay_sonos"}
3168 airplay_other._cache.clear()
3169 airplay_other.set_protocol_parent_id("wiim_789")
3170
3171 sonos_player.set_linked_output_protocols(
3172 [
3173 LinkedOutputProtocol(
3174 output_protocol_id="airplay_sonos",
3175 protocol_domain="airplay",
3176 priority=10,
3177 ),
3178 LinkedOutputProtocol(
3179 output_protocol_id="dlna_sonos",
3180 protocol_domain="dlna",
3181 priority=50,
3182 ),
3183 ]
3184 )
3185
3186 wiim_player.set_linked_output_protocols(
3187 [
3188 LinkedOutputProtocol(
3189 output_protocol_id="airplay_other",
3190 protocol_domain="airplay",
3191 priority=10,
3192 ),
3193 ]
3194 )
3195
3196 # Clear cache after setting linked protocols (output_protocols is cached)
3197 sonos_player._cache.clear()
3198 wiim_player._cache.clear()
3199
3200 # Wire up mock_mass.players to controller so player lookups resolve
3201 mock_mass.players = controller
3202
3203 controller._players = {
3204 "sonos_123": sonos_player,
3205 "sonos_456": sonos_player_b,
3206 "wiim_789": wiim_player,
3207 "airplay_sonos": sonos_airplay,
3208 "airplay_other": airplay_other,
3209 "dlna_sonos": sonos_dlna,
3210 }
3211
3212 # Update state after modifying attributes and registering with controller
3213 # Note: set_linked_output_protocols calls trigger_player_update, but since mass.players
3214 # is a MagicMock, we need to manually call update_state
3215 # IMPORTANT: Update protocol players FIRST, then parent players, because parent players
3216 # access protocol_player.state.can_group_with during their update_state()
3217 sonos_airplay.update_state(signal_event=False)
3218 airplay_other.update_state(signal_event=False)
3219 sonos_dlna.update_state(signal_event=False)
3220 sonos_player.update_state(signal_event=False)
3221 sonos_player_b.update_state(signal_event=False)
3222 wiim_player.update_state(signal_event=False)
3223
3224 # Get can_group_with with no active protocol
3225 groupable = sonos_player.state.can_group_with
3226
3227 # Should show native players + AirPlay players (supports SET_MEMBERS)
3228 # but NOT DLNA players (no SET_MEMBERS support)
3229 assert "sonos_456" in groupable
3230 assert "wiim_789" in groupable # Via AirPlay protocol
3231 # DLNA players should not be shown since DLNA doesn't support SET_MEMBERS
3232
3233
3234class TestNativePlayerProtocolGrouping:
3235 """Tests for grouping between native PLAYER type and PROTOCOL type AirPlay players."""
3236
3237 def test_native_airplay_player_sees_protocol_players_as_visible_parents(
3238 self, mock_mass: MagicMock
3239 ) -> None:
3240 """Test that a native PLAYER type translates protocol players to visible parents."""
3241 controller = PlayerController(mock_mass)
3242
3243 airplay_provider = MockProvider("airplay", instance_id="airplay", mass=mock_mass)
3244 sonos_provider = MockProvider("sonos", instance_id="sonos", mass=mock_mass)
3245
3246 # HomePod: native AirPlay PLAYER (not PROTOCOL)
3247 homepod = MockPlayer(airplay_provider, "homepod_1", "Office")
3248 homepod._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3249 homepod._attr_can_group_with = {"airplay"} # Provider instance ID
3250 homepod._cache.clear()
3251
3252 # Sonos native player (visible to the user)
3253 sonos_player = MockPlayer(sonos_provider, "sonos_1", "Kitchen")
3254 sonos_player._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3255 sonos_player._cache.clear()
3256
3257 # AirPlay protocol player for the Sonos (hidden, linked to sonos_player)
3258 sonos_airplay = MockPlayer(
3259 airplay_provider,
3260 "airplay_sonos_1",
3261 "Kitchen (AirPlay)",
3262 player_type=PlayerType.PROTOCOL,
3263 )
3264 sonos_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3265 sonos_airplay._attr_can_group_with = {"airplay"}
3266 sonos_airplay._cache.clear()
3267 sonos_airplay.set_protocol_parent_id("sonos_1")
3268
3269 sonos_player.set_linked_output_protocols(
3270 [
3271 LinkedOutputProtocol(
3272 output_protocol_id="airplay_sonos_1",
3273 protocol_domain="airplay",
3274 priority=10,
3275 )
3276 ]
3277 )
3278
3279 mock_mass.players = controller
3280 mock_mass.get_provider = MagicMock(return_value=airplay_provider)
3281
3282 controller._players = {
3283 "homepod_1": homepod,
3284 "sonos_1": sonos_player,
3285 "airplay_sonos_1": sonos_airplay,
3286 }
3287
3288 # Mark players as initialized so they are returned by all_players()
3289 homepod.set_initialized()
3290 sonos_player.set_initialized()
3291 sonos_airplay.set_initialized()
3292
3293 # Update protocol players first, then parents
3294 sonos_airplay.update_state(signal_event=False)
3295 sonos_player.update_state(signal_event=False)
3296 homepod.update_state(signal_event=False)
3297
3298 groupable = homepod.state.can_group_with
3299
3300 # HomePod should see Sonos's VISIBLE player, not the hidden protocol player
3301 assert "sonos_1" in groupable
3302 assert "airplay_sonos_1" not in groupable # Hidden protocol ID must NOT appear
3303
3304 def test_protocol_linked_player_sees_native_airplay_player(self, mock_mass: MagicMock) -> None:
3305 """Test that a player with linked AirPlay protocol sees native PLAYER type players."""
3306 controller = PlayerController(mock_mass)
3307
3308 airplay_provider = MockProvider("airplay", instance_id="airplay", mass=mock_mass)
3309 sonos_provider = MockProvider("sonos", instance_id="sonos", mass=mock_mass)
3310
3311 # HomePod: native AirPlay PLAYER
3312 homepod = MockPlayer(airplay_provider, "homepod_1", "Office")
3313 homepod._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3314 homepod._attr_can_group_with = {"airplay"}
3315 homepod._cache.clear()
3316
3317 # Sonos native player (visible to the user)
3318 sonos_player = MockPlayer(sonos_provider, "sonos_1", "Kitchen")
3319 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
3320 sonos_player._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3321 sonos_player._attr_can_group_with = set() # No native Sonos grouping peers
3322 sonos_player._cache.clear()
3323
3324 # AirPlay protocol player for the Sonos (hidden, linked to sonos_player)
3325 sonos_airplay = MockPlayer(
3326 airplay_provider,
3327 "airplay_sonos_1",
3328 "Kitchen (AirPlay)",
3329 player_type=PlayerType.PROTOCOL,
3330 )
3331 sonos_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3332 sonos_airplay._attr_can_group_with = {"airplay"} # Provider instance ID
3333 sonos_airplay._cache.clear()
3334 sonos_airplay.set_protocol_parent_id("sonos_1")
3335
3336 sonos_player.set_linked_output_protocols(
3337 [
3338 LinkedOutputProtocol(
3339 output_protocol_id="airplay_sonos_1",
3340 protocol_domain="airplay",
3341 priority=10,
3342 )
3343 ]
3344 )
3345
3346 mock_mass.players = controller
3347 mock_mass.get_provider = MagicMock(return_value=airplay_provider)
3348
3349 controller._players = {
3350 "homepod_1": homepod,
3351 "sonos_1": sonos_player,
3352 "airplay_sonos_1": sonos_airplay,
3353 }
3354
3355 # Mark players as initialized so they are returned by all_players()
3356 homepod.set_initialized()
3357 sonos_player.set_initialized()
3358 sonos_airplay.set_initialized()
3359
3360 # Update protocol players first, then parents
3361 sonos_airplay.update_state(signal_event=False)
3362 homepod.update_state(signal_event=False)
3363 sonos_player.update_state(signal_event=False)
3364
3365 groupable = sonos_player.state.can_group_with
3366
3367 # Sonos should see HomePod via its linked AirPlay protocol's can_group_with
3368 assert "homepod_1" in groupable
3369
3370
3371class TestProtocolSwitchingDuringPlayback:
3372 """Tests for dynamic protocol switching when group members change during playback."""
3373
3374 def _build_session_bound_group(
3375 self, mock_mass: MagicMock, playback_state: PlaybackState
3376 ) -> tuple[PlayerController, dict[str, MockPlayer]]:
3377 """
3378 Build a leader that renders its own stream, one native member and a bridge-only player.
3379
3380 :param mock_mass: The mocked MusicAssistant instance.
3381 :param playback_state: The state the leader is in when the switch happens.
3382 :return: The controller and its players by ID.
3383 """
3384 controller = PlayerController(mock_mass)
3385 speaker_provider = MockProvider("speaker", instance_id="speaker_instance", mass=mock_mass)
3386 bridge_provider = MockProvider("sendspin", instance_id="sendspin_instance", mass=mock_mass)
3387
3388 leader = SessionBoundMockPlayer(speaker_provider, "speaker_leader", "Living Room")
3389 leader._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3390 leader._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
3391 leader._attr_group_members = ["speaker_leader", "speaker_member"]
3392 leader._attr_playback_state = playback_state
3393 leader._cache.clear()
3394
3395 member = MockPlayer(speaker_provider, "speaker_member", "Kitchen")
3396 member._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
3397 member._cache.clear()
3398
3399 bridge_only = MockPlayer(bridge_provider, "bridge_only", "Voice Assistant")
3400 bridge_only._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
3401 bridge_only._cache.clear()
3402
3403 players: dict[str, MockPlayer] = {
3404 "speaker_leader": leader,
3405 "speaker_member": member,
3406 "bridge_only": bridge_only,
3407 }
3408 for parent_id, bridge_id, bridge_name in (
3409 ("speaker_leader", "bridge_leader", "Living Room (Bridge)"),
3410 ("speaker_member", "bridge_member", "Kitchen (Bridge)"),
3411 ):
3412 bridge = MockPlayer(
3413 bridge_provider, bridge_id, bridge_name, player_type=PlayerType.PROTOCOL
3414 )
3415 bridge._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3416 bridge._cache.clear()
3417 bridge.set_protocol_parent_id(parent_id)
3418 players[bridge_id] = bridge
3419 players[parent_id].set_linked_output_protocols(
3420 [
3421 LinkedOutputProtocol(
3422 output_protocol_id=bridge_id,
3423 protocol_domain="sendspin",
3424 priority=40,
3425 )
3426 ]
3427 )
3428
3429 mock_mass.players = controller
3430 controller._players = dict(players)
3431 for registered_player in players.values():
3432 registered_player.update_state(signal_event=False)
3433 leader.set_active_output_protocol("native")
3434 return controller, players
3435
3436 async def test_no_protocol_set_during_grouping_without_playback(
3437 self, mock_mass: MagicMock
3438 ) -> None:
3439 """Test that no protocol is set when grouping players without active playback."""
3440 controller = PlayerController(mock_mass)
3441
3442 sonos_provider = MockProvider("sonos", instance_id="sonos_instance", mass=mock_mass)
3443 airplay_provider = MockProvider("airplay", instance_id="airplay_instance", mass=mock_mass)
3444
3445 # Create Sonos player with AirPlay support
3446 sonos_player = MockPlayer(
3447 sonos_provider,
3448 "sonos_123",
3449 "Living Room",
3450 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
3451 )
3452 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
3453 sonos_player._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3454 sonos_player._attr_can_group_with = {"sonos_456"}
3455
3456 # Create another Sonos player
3457 sonos_player_b = MockPlayer(
3458 sonos_provider,
3459 "sonos_456",
3460 "Kitchen",
3461 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
3462 )
3463 sonos_player_b._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3464
3465 # Create AirPlay protocol player
3466 sonos_airplay = MockPlayer(
3467 airplay_provider,
3468 "airplay_sonos",
3469 "Living Room (AirPlay)",
3470 player_type=PlayerType.PROTOCOL,
3471 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
3472 )
3473 sonos_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3474 sonos_airplay.set_protocol_parent_id("sonos_123")
3475
3476 sonos_player.set_linked_output_protocols(
3477 [
3478 LinkedOutputProtocol(
3479 output_protocol_id="airplay_sonos",
3480 protocol_domain="airplay",
3481 priority=10,
3482 )
3483 ]
3484 )
3485
3486 mock_mass.players = controller
3487 controller._players = {
3488 "sonos_123": sonos_player,
3489 "sonos_456": sonos_player_b,
3490 "airplay_sonos": sonos_airplay,
3491 }
3492
3493 # Group players via protocol (simulate grouping through AirPlay)
3494 # This should NOT set active_output_protocol anymore
3495 await controller._forward_protocol_set_members(
3496 parent_player=sonos_player,
3497 parent_protocol_player=sonos_airplay,
3498 protocol_members_to_add=["airplay_other"], # Add a protocol member
3499 protocol_members_to_remove=[],
3500 )
3501
3502 # NEW BEHAVIOR: Protocol should NOT be set during grouping without playback
3503 # After grouping, protocol should not be activated until playback starts
3504 assert sonos_player.active_output_protocol is None
3505
3506 async def test_protocol_selected_at_playback_time(self, mock_mass: MagicMock) -> None:
3507 """Test that protocol is selected when playback starts, not during grouping."""
3508 controller = PlayerController(mock_mass)
3509
3510 sonos_provider = MockProvider("sonos", instance_id="sonos_instance", mass=mock_mass)
3511 airplay_provider = MockProvider("airplay", instance_id="airplay_instance", mass=mock_mass)
3512
3513 # Create Sonos player with AirPlay support
3514 sonos_player = MockPlayer(
3515 sonos_provider,
3516 "sonos_123",
3517 "Living Room",
3518 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
3519 )
3520 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
3521 sonos_player._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3522
3523 # Create AirPlay protocol player with group members
3524 sonos_airplay = MockPlayer(
3525 airplay_provider,
3526 "airplay_sonos",
3527 "Living Room (AirPlay)",
3528 player_type=PlayerType.PROTOCOL,
3529 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
3530 )
3531 sonos_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3532 sonos_airplay._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
3533 sonos_airplay.set_protocol_parent_id("sonos_123")
3534 # Simulate that AirPlay protocol has group members (needs >1 for grouping check)
3535 sonos_airplay._attr_group_members = ["airplay_sonos", "airplay_other"]
3536
3537 sonos_player.set_linked_output_protocols(
3538 [
3539 LinkedOutputProtocol(
3540 output_protocol_id="airplay_sonos",
3541 protocol_domain="airplay",
3542 priority=10,
3543 )
3544 ]
3545 )
3546
3547 mock_mass.players = controller
3548 controller._players = {
3549 "sonos_123": sonos_player,
3550 "airplay_sonos": sonos_airplay,
3551 }
3552
3553 # Update state to apply group members to state
3554 sonos_airplay.update_state(signal_event=False)
3555 sonos_player.update_state(signal_event=False)
3556
3557 # Protocol should not be set yet
3558 assert sonos_player.active_output_protocol is None
3559
3560 # Select protocol for playback
3561 selected_player, output_protocol = controller._select_best_output_protocol(sonos_player)
3562
3563 # Should select AirPlay protocol because it has group members (Priority 1)
3564 assert selected_player == sonos_airplay
3565 assert output_protocol is not None
3566 assert output_protocol.output_protocol_id == "airplay_sonos"
3567
3568 async def test_no_restart_from_handle_set_members(self, mock_mass: MagicMock) -> None:
3569 """
3570 Test that _handle_set_members does NOT restart playback.
3571
3572 Protocol switching and playback restarts are handled in _forward_protocol_set_members,
3573 not in _handle_set_members. This test verifies that _handle_set_members doesn't
3574 trigger any redundant playback restarts.
3575 """
3576 controller = PlayerController(mock_mass)
3577
3578 sonos_provider = MockProvider("sonos", instance_id="sonos_instance", mass=mock_mass)
3579 airplay_provider = MockProvider("airplay", instance_id="airplay_instance", mass=mock_mass)
3580
3581 # Create Sonos player currently playing via AirPlay
3582 sonos_player = MockPlayer(
3583 sonos_provider,
3584 "sonos_123",
3585 "Living Room",
3586 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
3587 )
3588 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
3589 sonos_player._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3590 sonos_player._attr_playback_state = PlaybackState.PLAYING
3591 sonos_player._attr_group_members = ["sonos_123", "sonos_456"]
3592
3593 # Create another Sonos player in the group (member of sonos_123's group)
3594 sonos_player_b = MockPlayer(
3595 sonos_provider,
3596 "sonos_456",
3597 "Kitchen",
3598 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
3599 )
3600 sonos_player_b._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3601 # sonos_player_b's synced_to is derived from group_members, not a direct attribute
3602
3603 # Create AirPlay protocol player (was used for grouping)
3604 sonos_airplay = MockPlayer(
3605 airplay_provider,
3606 "airplay_sonos",
3607 "Living Room (AirPlay)",
3608 player_type=PlayerType.PROTOCOL,
3609 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
3610 )
3611 sonos_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3612 sonos_airplay.set_protocol_parent_id("sonos_123")
3613
3614 sonos_player.set_linked_output_protocols(
3615 [
3616 LinkedOutputProtocol(
3617 output_protocol_id="airplay_sonos",
3618 protocol_domain="airplay",
3619 priority=10,
3620 )
3621 ]
3622 )
3623
3624 mock_mass.players = controller
3625 controller._players = {
3626 "sonos_123": sonos_player,
3627 "sonos_456": sonos_player_b,
3628 "airplay_sonos": sonos_airplay,
3629 }
3630
3631 # Update state and set active output protocol AFTER registering with controller
3632 sonos_player.update_state(signal_event=False)
3633 sonos_player_b.update_state(signal_event=False)
3634 sonos_airplay.update_state(signal_event=False)
3635
3636 # Set active output protocol (must be done after controller is set up)
3637 sonos_player.set_active_output_protocol("airplay_sonos")
3638
3639 # Track if cmd_resume was called
3640 resume_called = False
3641
3642 async def mock_cmd_resume(
3643 player_id: str, # noqa: ARG001
3644 source: str | None = None, # noqa: ARG001
3645 media: PlayerMedia | None = None, # noqa: ARG001
3646 ) -> None:
3647 nonlocal resume_called
3648 resume_called = True
3649
3650 controller.cmd_resume = mock_cmd_resume # type: ignore[method-assign]
3651
3652 # Remove member - now only the parent player is left
3653 # After removal, _select_best_output_protocol would return native
3654 sonos_player._attr_group_members = ["sonos_123"]
3655 sonos_player._cache.clear()
3656
3657 # Call _handle_set_members directly to trigger the protocol change check
3658 await controller._handle_set_members(
3659 sonos_player,
3660 player_ids_to_add=None,
3661 player_ids_to_remove=["sonos_456"],
3662 )
3663
3664 # Playback should NOT have been restarted because we're going back to native
3665 assert not resume_called, "cmd_resume should not be called when switching to native"
3666
3667 @pytest.mark.parametrize("playback_state", [PlaybackState.PLAYING, PlaybackState.PAUSED])
3668 async def test_native_session_is_stopped_and_members_migrate(
3669 self, mock_mass: MagicMock, playback_state: PlaybackState
3670 ) -> None:
3671 """
3672 A parent that renders its own stream hands its native members over to the new protocol.
3673
3674 The members join the protocol group in the same call as the new member, after which
3675 the native session releases them and stops. Playback resumes only for a player that
3676 was playing, so adding a member to a paused group does not start it.
3677 """
3678 controller, players = self._build_session_bound_group(mock_mass, playback_state)
3679 leader = players["speaker_leader"]
3680 bridge_leader = players["bridge_leader"]
3681
3682 # record the sequence of provider level calls the switch performs
3683 calls: list[tuple[str, Any]] = []
3684 leader_set_members = leader.set_members
3685 bridge_set_members = bridge_leader.set_members
3686
3687 async def record_leader_set_members(
3688 player_ids_to_add: list[str] | None = None,
3689 player_ids_to_remove: list[str] | None = None,
3690 ) -> None:
3691 calls.append(("leader_set_members", player_ids_to_remove))
3692 await leader_set_members(player_ids_to_add, player_ids_to_remove)
3693
3694 async def record_bridge_set_members(
3695 player_ids_to_add: list[str] | None = None,
3696 player_ids_to_remove: list[str] | None = None,
3697 ) -> None:
3698 calls.append(("bridge_set_members", player_ids_to_add))
3699 await bridge_set_members(player_ids_to_add, player_ids_to_remove)
3700
3701 async def record_leader_stop() -> None:
3702 calls.append(("leader_stop", None))
3703
3704 leader.set_members = record_leader_set_members # type: ignore[method-assign]
3705 leader.stop = record_leader_stop # type: ignore[method-assign]
3706 bridge_leader.set_members = record_bridge_set_members # type: ignore[method-assign]
3707 controller.cmd_resume = AsyncMock() # type: ignore[method-assign]
3708 controller._handle_set_members = AsyncMock() # type: ignore[method-assign]
3709
3710 await controller._forward_protocol_set_members(
3711 parent_player=leader,
3712 parent_protocol_player=bridge_leader,
3713 protocol_members_to_add=["bridge_only"],
3714 protocol_members_to_remove=[],
3715 )
3716
3717 assert calls == [
3718 # the native member joins the protocol group together with the new member
3719 ("bridge_set_members", ["bridge_only", "bridge_member"]),
3720 ("leader_set_members", ["speaker_member"]),
3721 ("leader_stop", None),
3722 ]
3723 assert leader.active_output_protocol == "bridge_leader"
3724 # Only a player that was playing resumes: adding a member to a paused group
3725 # hands the output over without starting playback.
3726 if playback_state == PlaybackState.PLAYING:
3727 controller.cmd_resume.assert_awaited_once_with("speaker_leader")
3728 else:
3729 controller.cmd_resume.assert_not_awaited()
3730 controller._handle_set_members.assert_not_awaited()
3731
3732 async def test_idle_native_members_migrate_without_stopping_the_parent(
3733 self, mock_mass: MagicMock
3734 ) -> None:
3735 """
3736 An idle parent hands its native members over too, with no session to stop.
3737
3738 A native group outlives the session it was formed for, so the members are still
3739 attached to the parent when it switches protocol. Leaving them behind would keep
3740 them listed as grouped while nothing feeds them on the next play.
3741 """
3742 controller, players = self._build_session_bound_group(mock_mass, PlaybackState.IDLE)
3743 leader = players["speaker_leader"]
3744 bridge_leader = players["bridge_leader"]
3745
3746 calls: list[tuple[str, Any]] = []
3747 leader_set_members = leader.set_members
3748 bridge_set_members = bridge_leader.set_members
3749
3750 async def record_leader_set_members(
3751 player_ids_to_add: list[str] | None = None,
3752 player_ids_to_remove: list[str] | None = None,
3753 ) -> None:
3754 calls.append(("leader_set_members", player_ids_to_remove))
3755 await leader_set_members(player_ids_to_add, player_ids_to_remove)
3756
3757 async def record_bridge_set_members(
3758 player_ids_to_add: list[str] | None = None,
3759 player_ids_to_remove: list[str] | None = None,
3760 ) -> None:
3761 calls.append(("bridge_set_members", player_ids_to_add))
3762 await bridge_set_members(player_ids_to_add, player_ids_to_remove)
3763
3764 async def record_leader_stop() -> None:
3765 calls.append(("leader_stop", None))
3766
3767 leader.set_members = record_leader_set_members # type: ignore[method-assign]
3768 leader.stop = record_leader_stop # type: ignore[method-assign]
3769 bridge_leader.set_members = record_bridge_set_members # type: ignore[method-assign]
3770 controller.cmd_resume = AsyncMock() # type: ignore[method-assign]
3771
3772 await controller._forward_protocol_set_members(
3773 parent_player=leader,
3774 parent_protocol_player=bridge_leader,
3775 protocol_members_to_add=["bridge_only"],
3776 protocol_members_to_remove=[],
3777 )
3778
3779 # the native member joins the protocol group and is released from the parent,
3780 # but an idle parent has no session to stop and nothing to resume
3781 assert calls == [
3782 ("bridge_set_members", ["bridge_only", "bridge_member"]),
3783 ("leader_set_members", ["speaker_member"]),
3784 ]
3785 assert leader.active_output_protocol == "bridge_leader"
3786 controller.cmd_resume.assert_not_awaited()
3787
3788 async def test_joining_member_protocol_is_active_before_its_stream_starts(
3789 self, mock_mass: MagicMock
3790 ) -> None:
3791 """
3792 A joining member's parent knows which protocol carries its audio before its stream starts.
3793
3794 The member's stream is started from inside set_members, and providers resolve the
3795 member's volume control while starting it. A device that also exposes a higher
3796 priority sibling interface (e.g. a soundbar that is both Chromecast and AirPlay)
3797 would otherwise resolve volume to that sibling and apply its volume semantics to
3798 a stream it does not attenuate.
3799 """
3800 controller = PlayerController(mock_mass)
3801
3802 airplay_provider = MockProvider("airplay", instance_id="airplay", mass=mock_mass)
3803 cast_provider = MockProvider("chromecast", instance_id="chromecast", mass=mock_mass)
3804
3805 leader = MockPlayer(airplay_provider, "leader", "Kitchen")
3806 leader_airplay = MockPlayer(
3807 airplay_provider,
3808 "leader_airplay",
3809 "Kitchen (AirPlay)",
3810 player_type=PlayerType.PROTOCOL,
3811 )
3812 leader_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3813 leader_airplay.set_protocol_parent_id("leader")
3814
3815 # the joining device exposes both a Chromecast and an AirPlay interface, and has no
3816 # native volume of its own, so its volume control is one of the two protocol players
3817 joiner = MockPlayer(cast_provider, "joiner", "Living Room")
3818 joiner._attr_supported_features = set()
3819 joiner_cast = MockPlayer(
3820 cast_provider,
3821 "joiner_cast",
3822 "Living Room (Cast)",
3823 player_type=PlayerType.PROTOCOL,
3824 )
3825 joiner_cast.set_protocol_parent_id("joiner")
3826 joiner_airplay = MockPlayer(
3827 airplay_provider,
3828 "joiner_airplay",
3829 "Living Room (AirPlay)",
3830 player_type=PlayerType.PROTOCOL,
3831 )
3832 joiner_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3833 joiner_airplay.set_protocol_parent_id("joiner")
3834
3835 leader.set_linked_output_protocols(
3836 [
3837 LinkedOutputProtocol(
3838 output_protocol_id="leader_airplay",
3839 protocol_domain="airplay",
3840 priority=10,
3841 )
3842 ]
3843 )
3844 joiner.set_linked_output_protocols(
3845 [
3846 LinkedOutputProtocol(
3847 output_protocol_id="joiner_cast",
3848 protocol_domain="chromecast",
3849 priority=10,
3850 ),
3851 LinkedOutputProtocol(
3852 output_protocol_id="joiner_airplay",
3853 protocol_domain="airplay",
3854 priority=20,
3855 ),
3856 ]
3857 )
3858
3859 mock_mass.players = controller
3860 controller._players = {
3861 player.player_id: player
3862 for player in (leader, leader_airplay, joiner, joiner_cast, joiner_airplay)
3863 }
3864 for player in controller._players.values():
3865 player.update_state(signal_event=False)
3866
3867 # While the device sits idle its Chromecast interface owns the volume: the winner is
3868 # decided by the hardcoded per-domain control priority, not by the link priorities.
3869 assert joiner.volume_control == "joiner_cast"
3870
3871 observed_volume_controls: list[str] = []
3872
3873 async def record_set_members(
3874 player_ids_to_add: list[str] | None = None, # noqa: ARG001
3875 player_ids_to_remove: list[str] | None = None, # noqa: ARG001
3876 ) -> None:
3877 observed_volume_controls.append(joiner.volume_control)
3878
3879 leader_airplay.set_members = record_set_members # type: ignore[method-assign]
3880 controller._handle_set_members = AsyncMock() # type: ignore[method-assign]
3881
3882 await controller._forward_protocol_set_members(
3883 parent_player=leader,
3884 parent_protocol_player=leader_airplay,
3885 protocol_members_to_add=["joiner_airplay"],
3886 protocol_members_to_remove=[],
3887 )
3888
3889 assert observed_volume_controls == ["joiner_airplay"]
3890
3891
3892class TestNativeProtocolPlayerGrouping:
3893 """Tests for grouping with native protocol players (e.g., native AirPlay like Apple TV)."""
3894
3895 def test_native_airplay_groups_with_protocol_linked_player(self, mock_mass: MagicMock) -> None:
3896 """
3897 Test grouping a native AirPlay player (Apple TV) with a protocol-linked player (Sonos).
3898
3899 This tests the scenario where:
3900 - Apple TV is a native AirPlay PLAYER (not PROTOCOL type)
3901 - Sonos has AirPlay as a linked protocol
3902 - Apple TV groups with Sonos via the common AirPlay protocol
3903 """
3904 controller = PlayerController(mock_mass)
3905
3906 airplay_provider = MockProvider("airplay", instance_id="airplay", mass=mock_mass)
3907 sonos_provider = MockProvider("sonos", instance_id="sonos", mass=mock_mass)
3908
3909 # Apple TV: native AirPlay PLAYER (supports grouping via AirPlay)
3910 apple_tv = MockPlayer(airplay_provider, "apple_tv_1", "Apple TV Slaapkamer")
3911 apple_tv._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
3912 apple_tv._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3913 apple_tv._attr_can_group_with = {"airplay"} # Provider instance ID
3914 apple_tv._cache.clear()
3915
3916 # Sonos native player (visible)
3917 sonos_player = MockPlayer(sonos_provider, "sonos_badkamer", "Badkamer")
3918 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
3919 sonos_player._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3920 sonos_player._cache.clear()
3921
3922 # AirPlay protocol player for Sonos (hidden, linked to sonos)
3923 sonos_airplay = MockPlayer(
3924 airplay_provider,
3925 "airplay_sonos",
3926 "Badkamer (AirPlay)",
3927 player_type=PlayerType.PROTOCOL,
3928 )
3929 sonos_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
3930 sonos_airplay._attr_can_group_with = {"airplay"}
3931 sonos_airplay._cache.clear()
3932 sonos_airplay.set_protocol_parent_id("sonos_badkamer")
3933
3934 sonos_player.set_linked_output_protocols(
3935 [
3936 LinkedOutputProtocol(
3937 output_protocol_id="airplay_sonos",
3938 protocol_domain="airplay",
3939 priority=10,
3940 )
3941 ]
3942 )
3943
3944 mock_mass.players = controller
3945 controller._players = {
3946 "apple_tv_1": apple_tv,
3947 "sonos_badkamer": sonos_player,
3948 "airplay_sonos": sonos_airplay,
3949 }
3950
3951 # Update states
3952 sonos_airplay.update_state(signal_event=False)
3953 sonos_player.update_state(signal_event=False)
3954 apple_tv.update_state(signal_event=False)
3955
3956 # Translate members for grouping Sonos to Apple TV
3957 protocol_members, _native_members, protocol_player, protocol_domain = (
3958 controller._translate_members_for_protocols(
3959 parent_player=apple_tv,
3960 player_ids=["sonos_badkamer"],
3961 parent_protocol_player=None,
3962 parent_protocol_domain=None,
3963 )
3964 )
3965
3966 # Should find common AirPlay protocol
3967 assert len(protocol_members) == 1
3968 assert "airplay_sonos" in protocol_members
3969 assert protocol_domain == "airplay"
3970 # For native AirPlay player, protocol_player should be the Apple TV itself
3971 assert protocol_player == apple_tv
3972
3973 def test_get_output_protocol_by_domain_finds_native(self, mock_mass: MagicMock) -> None:
3974 """Test that get_output_protocol_by_domain finds native protocol."""
3975 controller = PlayerController(mock_mass)
3976
3977 airplay_provider = MockProvider("airplay", instance_id="airplay", mass=mock_mass)
3978
3979 # Native AirPlay player
3980 apple_tv = MockPlayer(airplay_provider, "apple_tv_1", "Apple TV")
3981 apple_tv._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
3982 apple_tv._cache.clear()
3983
3984 mock_mass.players = controller
3985 controller._players = {"apple_tv_1": apple_tv}
3986
3987 apple_tv.update_state(signal_event=False)
3988
3989 # Should find native AirPlay protocol
3990 protocol = apple_tv.get_output_protocol_by_domain("airplay")
3991 assert protocol is not None
3992 assert protocol.output_protocol_id == "native"
3993 assert protocol.protocol_domain == "airplay"
3994 assert protocol.is_native is True
3995
3996
3997class TestFinalGroupMembersTranslation:
3998 """Tests for __final_group_members translation of protocol player IDs."""
3999
4000 def test_final_group_members_translates_protocol_ids(self, mock_mass: MagicMock) -> None:
4001 """
4002 Test that __final_group_members translates protocol player IDs to visible IDs.
4003
4004 When a native AirPlay player (Apple TV) has protocol players in its group_members,
4005 the final state should show the visible parent player IDs instead.
4006 """
4007 controller = PlayerController(mock_mass)
4008
4009 airplay_provider = MockProvider("airplay", instance_id="airplay", mass=mock_mass)
4010 sonos_provider = MockProvider("sonos", instance_id="sonos", mass=mock_mass)
4011
4012 # Apple TV with group members containing a protocol player ID
4013 apple_tv = MockPlayer(airplay_provider, "apple_tv_1", "Apple TV")
4014 apple_tv._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4015 apple_tv._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
4016 apple_tv._attr_group_members = ["apple_tv_1", "airplay_sonos"]
4017 apple_tv._cache.clear()
4018
4019 # Sonos visible player
4020 sonos_player = MockPlayer(sonos_provider, "sonos_1", "Sonos")
4021 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4022 sonos_player._cache.clear()
4023
4024 # AirPlay protocol player for Sonos
4025 sonos_airplay = MockPlayer(
4026 airplay_provider,
4027 "airplay_sonos",
4028 "Sonos (AirPlay)",
4029 player_type=PlayerType.PROTOCOL,
4030 )
4031 sonos_airplay._cache.clear()
4032 sonos_airplay.set_protocol_parent_id("sonos_1")
4033
4034 mock_mass.players = controller
4035 controller._players = {
4036 "apple_tv_1": apple_tv,
4037 "sonos_1": sonos_player,
4038 "airplay_sonos": sonos_airplay,
4039 }
4040
4041 sonos_airplay.update_state(signal_event=False)
4042 sonos_player.update_state(signal_event=False)
4043 apple_tv.update_state(signal_event=False)
4044
4045 # Final group_members should show visible player IDs
4046 final_members = apple_tv.state.group_members
4047 assert "apple_tv_1" in final_members
4048 assert "sonos_1" in final_members
4049 # Protocol player ID should NOT appear in final state
4050 assert "airplay_sonos" not in final_members
4051
4052
4053class TestFinalActiveGroupTranslation:
4054 """Tests for __final_active_group with translated protocol player IDs."""
4055
4056 def test_active_group_uses_translated_group_members(self, mock_mass: MagicMock) -> None:
4057 """Test that visible players resolve active_group from translated group members."""
4058 controller = PlayerController(mock_mass)
4059
4060 group_provider = MockProvider(
4061 "universal_group", instance_id="universal_group", mass=mock_mass
4062 )
4063 airplay_provider = MockProvider("airplay", instance_id="airplay", mass=mock_mass)
4064 sonos_provider = MockProvider("sonos", instance_id="sonos", mass=mock_mass)
4065
4066 group_player = MockPlayer(
4067 group_provider,
4068 "group_1",
4069 "House Group",
4070 player_type=PlayerType.GROUP,
4071 )
4072 group_player._attr_playback_state = PlaybackState.PLAYING
4073 group_player._attr_group_members = ["airplay_sonos"]
4074 group_player._cache.clear()
4075
4076 sonos_player = MockPlayer(sonos_provider, "sonos_1", "Sonos")
4077 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4078 sonos_player._cache.clear()
4079
4080 sonos_airplay = MockPlayer(
4081 airplay_provider,
4082 "airplay_sonos",
4083 "Sonos (AirPlay)",
4084 player_type=PlayerType.PROTOCOL,
4085 )
4086 sonos_airplay.set_protocol_parent_id("sonos_1")
4087 sonos_airplay._cache.clear()
4088
4089 mock_mass.players = controller
4090 controller._players = {
4091 "group_1": group_player,
4092 "sonos_1": sonos_player,
4093 "airplay_sonos": sonos_airplay,
4094 }
4095
4096 group_player.set_initialized()
4097 sonos_player.set_initialized()
4098 sonos_airplay.set_initialized()
4099
4100 group_player.update_state(signal_event=False)
4101 sonos_airplay.update_state(signal_event=False)
4102 sonos_player.update_state(signal_event=False)
4103
4104 assert sonos_player.state.active_group == "group_1"
4105 assert sonos_airplay.state.active_group is None
4106
4107
4108class TestFinalSyncedToWithNativeProtocolParent:
4109 """Tests for __final_synced_to when sync parent is a native protocol player."""
4110
4111 def test_synced_to_native_airplay_player(self, mock_mass: MagicMock) -> None:
4112 """
4113 Test that synced_to correctly shows native AirPlay player as parent.
4114
4115 When a Sonos player's AirPlay protocol player is synced to a native AirPlay
4116 player (Apple TV), the Sonos's final synced_to should show the Apple TV.
4117 """
4118 controller = PlayerController(mock_mass)
4119
4120 airplay_provider = MockProvider("airplay", instance_id="airplay", mass=mock_mass)
4121 sonos_provider = MockProvider("sonos", instance_id="sonos", mass=mock_mass)
4122
4123 # Apple TV: native AirPlay PLAYER (the group leader)
4124 apple_tv = MockPlayer(airplay_provider, "apple_tv_1", "Apple TV")
4125 apple_tv._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4126 apple_tv._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
4127 apple_tv._attr_group_members = ["apple_tv_1", "airplay_sonos"]
4128 apple_tv._cache.clear()
4129
4130 # Sonos visible player
4131 sonos_player = MockPlayer(sonos_provider, "sonos_1", "Sonos")
4132 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4133 sonos_player._cache.clear()
4134
4135 # AirPlay protocol player for Sonos - synced to Apple TV
4136 sonos_airplay = MockPlayer(
4137 airplay_provider,
4138 "airplay_sonos",
4139 "Sonos (AirPlay)",
4140 player_type=PlayerType.PROTOCOL,
4141 )
4142 # Set group_members with Apple TV first to indicate synced_to Apple TV
4143 sonos_airplay._attr_group_members = ["apple_tv_1", "airplay_sonos"]
4144 sonos_airplay._cache.clear()
4145 sonos_airplay.set_protocol_parent_id("sonos_1")
4146
4147 sonos_player.set_linked_output_protocols(
4148 [
4149 LinkedOutputProtocol(
4150 output_protocol_id="airplay_sonos",
4151 protocol_domain="airplay",
4152 priority=10,
4153 )
4154 ]
4155 )
4156
4157 mock_mass.players = controller
4158 controller._players = {
4159 "apple_tv_1": apple_tv,
4160 "sonos_1": sonos_player,
4161 "airplay_sonos": sonos_airplay,
4162 }
4163
4164 apple_tv.set_initialized()
4165 sonos_player.set_initialized()
4166 sonos_airplay.set_initialized()
4167
4168 apple_tv.update_state(signal_event=False)
4169 sonos_airplay.update_state(signal_event=False)
4170 sonos_player.update_state(signal_event=False)
4171
4172 # Sonos's final synced_to should be Apple TV (visible player)
4173 assert sonos_player.state.synced_to == "apple_tv_1"
4174
4175
4176class TestUngroupTranslation:
4177 """Tests for translation when ungrouping from native protocol players."""
4178
4179 def test_ungroup_translates_visible_to_protocol_id(self, mock_mass: MagicMock) -> None:
4180 """
4181 Test that ungrouping correctly translates visible ID to protocol ID.
4182
4183 When ungrouping Sonos from Apple TV, the visible Sonos ID should be
4184 translated to its AirPlay protocol player ID for the removal.
4185 """
4186 controller = PlayerController(mock_mass)
4187
4188 airplay_provider = MockProvider("airplay", instance_id="airplay", mass=mock_mass)
4189 sonos_provider = MockProvider("sonos", instance_id="sonos", mass=mock_mass)
4190
4191 # Apple TV with Sonos's AirPlay protocol player in group_members
4192 apple_tv = MockPlayer(airplay_provider, "apple_tv_1", "Apple TV")
4193 apple_tv._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4194 apple_tv._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
4195 apple_tv._attr_group_members = ["apple_tv_1", "airplay_sonos"]
4196 apple_tv._cache.clear()
4197
4198 # Sonos visible player
4199 sonos_player = MockPlayer(sonos_provider, "sonos_1", "Sonos")
4200 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4201 sonos_player._cache.clear()
4202
4203 # AirPlay protocol player for Sonos
4204 sonos_airplay = MockPlayer(
4205 airplay_provider,
4206 "airplay_sonos",
4207 "Sonos (AirPlay)",
4208 player_type=PlayerType.PROTOCOL,
4209 )
4210 sonos_airplay._cache.clear()
4211 sonos_airplay.set_protocol_parent_id("sonos_1")
4212
4213 sonos_player.set_linked_output_protocols(
4214 [
4215 LinkedOutputProtocol(
4216 output_protocol_id="airplay_sonos",
4217 protocol_domain="airplay",
4218 priority=10,
4219 )
4220 ]
4221 )
4222
4223 mock_mass.players = controller
4224 controller._players = {
4225 "apple_tv_1": apple_tv,
4226 "sonos_1": sonos_player,
4227 "airplay_sonos": sonos_airplay,
4228 }
4229
4230 sonos_airplay.update_state(signal_event=False)
4231 sonos_player.update_state(signal_event=False)
4232 apple_tv.update_state(signal_event=False)
4233
4234 # Translate members for removal - visible ID should become protocol ID
4235 _protocol_members, native_members = controller._translate_members_to_remove_for_protocols(
4236 parent_player=apple_tv,
4237 player_ids=["sonos_1"], # Visible player ID
4238 parent_protocol_player=None,
4239 parent_protocol_domain=None,
4240 )
4241
4242 # Should translate to the protocol player ID for native removal
4243 assert "airplay_sonos" in native_members
4244 assert "sonos_1" not in native_members
4245
4246
4247class TestNativeProtocolDomainPlayerGrouping:
4248 """
4249 Tests for grouping with native protocol-domain players.
4250
4251 This tests the scenario where a player's native provider domain IS the protocol
4252 domain (e.g., a sendspin web player with PlayerType.PLAYER and provider.domain="sendspin"),
4253 rather than having the protocol as a linked protocol player.
4254 """
4255
4256 def test_native_protocol_player_groups_via_active_protocol(self, mock_mass: MagicMock) -> None:
4257 """
4258 Test grouping a native protocol player via the parent's active protocol.
4259
4260 Scenario: Kantoor (has sendspin linked protocol, active) groups with
4261 Web player (native sendspin PlayerType.PLAYER).
4262 This should use Priority 2 (parent's active protocol).
4263 """
4264 controller = PlayerController(mock_mass)
4265
4266 sonos_provider = MockProvider("sonos", instance_id="sonos", mass=mock_mass)
4267 sendspin_provider = MockProvider("sendspin", instance_id="sendspin", mass=mock_mass)
4268
4269 # Kantoor: native Sonos player with sendspin as linked protocol
4270 kantoor = MockPlayer(sonos_provider, "sonos_kantoor", "Kantoor")
4271 kantoor._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4272 kantoor._cache.clear()
4273
4274 # Sendspin protocol player linked to Kantoor
4275 sendspin_kantoor = MockPlayer(
4276 sendspin_provider,
4277 "sendspin_kantoor",
4278 "Kantoor (Sendspin)",
4279 player_type=PlayerType.PROTOCOL,
4280 )
4281 sendspin_kantoor._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
4282 sendspin_kantoor._attr_can_group_with = {"sendspin"}
4283 sendspin_kantoor._cache.clear()
4284 sendspin_kantoor.set_protocol_parent_id("sonos_kantoor")
4285
4286 # Web player: native sendspin player (PlayerType.PLAYER, standalone)
4287 web_player = MockPlayer(sendspin_provider, "sendspin_web", "Web (Chrome on Mac)")
4288 web_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4289 web_player._cache.clear()
4290
4291 # Link sendspin protocol to Kantoor
4292 kantoor.set_linked_output_protocols(
4293 [
4294 LinkedOutputProtocol(
4295 output_protocol_id="sendspin_kantoor",
4296 protocol_domain="sendspin",
4297 priority=40,
4298 )
4299 ]
4300 )
4301
4302 mock_mass.players = controller
4303 controller._players = {
4304 "sonos_kantoor": kantoor,
4305 "sendspin_kantoor": sendspin_kantoor,
4306 "sendspin_web": web_player,
4307 }
4308
4309 # Update states
4310 sendspin_kantoor.update_state(signal_event=False)
4311 kantoor.update_state(signal_event=False)
4312 web_player.update_state(signal_event=False)
4313
4314 # Group Web player with Kantoor, with sendspin as active protocol
4315 protocol_members, native_members, protocol_player, _ = (
4316 controller._translate_members_for_protocols(
4317 parent_player=kantoor,
4318 player_ids=["sendspin_web"],
4319 parent_protocol_player=sendspin_kantoor,
4320 parent_protocol_domain="sendspin",
4321 )
4322 )
4323
4324 # Web player's own player_id should be in protocol_members
4325 assert len(protocol_members) == 1
4326 assert "sendspin_web" in protocol_members
4327 assert len(native_members) == 0
4328 assert protocol_player == sendspin_kantoor
4329
4330 def test_native_protocol_player_groups_via_common_protocol(self, mock_mass: MagicMock) -> None:
4331 """
4332 Test grouping a native protocol player via common protocol search (Priority 4).
4333
4334 Same scenario but without a pre-set active protocol â the common protocol
4335 search should find sendspin as the shared protocol.
4336 """
4337 controller = PlayerController(mock_mass)
4338
4339 sonos_provider = MockProvider("sonos", instance_id="sonos", mass=mock_mass)
4340 sendspin_provider = MockProvider("sendspin", instance_id="sendspin", mass=mock_mass)
4341
4342 # Kantoor: native Sonos player with sendspin as linked protocol
4343 kantoor = MockPlayer(sonos_provider, "sonos_kantoor", "Kantoor")
4344 kantoor._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4345 kantoor._cache.clear()
4346
4347 # Sendspin protocol player linked to Kantoor
4348 sendspin_kantoor = MockPlayer(
4349 sendspin_provider,
4350 "sendspin_kantoor",
4351 "Kantoor (Sendspin)",
4352 player_type=PlayerType.PROTOCOL,
4353 )
4354 sendspin_kantoor._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
4355 sendspin_kantoor._attr_can_group_with = {"sendspin"}
4356 sendspin_kantoor._cache.clear()
4357 sendspin_kantoor.set_protocol_parent_id("sonos_kantoor")
4358
4359 # Web player: native sendspin player (PlayerType.PLAYER, standalone)
4360 web_player = MockPlayer(sendspin_provider, "sendspin_web", "Web (Chrome on Mac)")
4361 web_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4362 web_player._cache.clear()
4363
4364 # Link sendspin protocol to Kantoor
4365 kantoor.set_linked_output_protocols(
4366 [
4367 LinkedOutputProtocol(
4368 output_protocol_id="sendspin_kantoor",
4369 protocol_domain="sendspin",
4370 priority=40,
4371 )
4372 ]
4373 )
4374
4375 mock_mass.players = controller
4376 controller._players = {
4377 "sonos_kantoor": kantoor,
4378 "sendspin_kantoor": sendspin_kantoor,
4379 "sendspin_web": web_player,
4380 }
4381
4382 # Update states
4383 sendspin_kantoor.update_state(signal_event=False)
4384 kantoor.update_state(signal_event=False)
4385 web_player.update_state(signal_event=False)
4386
4387 # Group Web player with Kantoor, without pre-set active protocol
4388 protocol_members, native_members, protocol_player, protocol_domain = (
4389 controller._translate_members_for_protocols(
4390 parent_player=kantoor,
4391 player_ids=["sendspin_web"],
4392 parent_protocol_player=None,
4393 parent_protocol_domain=None,
4394 )
4395 )
4396
4397 # Should find common sendspin protocol via Priority 4
4398 assert len(protocol_members) == 1
4399 assert "sendspin_web" in protocol_members
4400 assert len(native_members) == 0
4401 assert protocol_domain == "sendspin"
4402 assert protocol_player == sendspin_kantoor
4403
4404 def test_ungroup_native_protocol_player(self, mock_mass: MagicMock) -> None:
4405 """
4406 Test ungrouping a native protocol player from a protocol-linked parent.
4407
4408 When ungrouping a native sendspin web player from Kantoor's sendspin group,
4409 the web player's own player_id should be used for removal.
4410 """
4411 controller = PlayerController(mock_mass)
4412
4413 sonos_provider = MockProvider("sonos", instance_id="sonos", mass=mock_mass)
4414 sendspin_provider = MockProvider("sendspin", instance_id="sendspin", mass=mock_mass)
4415
4416 # Kantoor with sendspin linked protocol
4417 kantoor = MockPlayer(sonos_provider, "sonos_kantoor", "Kantoor")
4418 kantoor._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4419 kantoor._cache.clear()
4420
4421 # Sendspin protocol player linked to Kantoor, with web player in group
4422 sendspin_kantoor = MockPlayer(
4423 sendspin_provider,
4424 "sendspin_kantoor",
4425 "Kantoor (Sendspin)",
4426 player_type=PlayerType.PROTOCOL,
4427 )
4428 sendspin_kantoor._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
4429 sendspin_kantoor._attr_group_members = ["sendspin_kantoor", "sendspin_web"]
4430 sendspin_kantoor._cache.clear()
4431 sendspin_kantoor.set_protocol_parent_id("sonos_kantoor")
4432
4433 # Web player: native sendspin player
4434 web_player = MockPlayer(sendspin_provider, "sendspin_web", "Web (Chrome on Mac)")
4435 web_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4436 web_player._cache.clear()
4437
4438 kantoor.set_linked_output_protocols(
4439 [
4440 LinkedOutputProtocol(
4441 output_protocol_id="sendspin_kantoor",
4442 protocol_domain="sendspin",
4443 priority=40,
4444 )
4445 ]
4446 )
4447
4448 mock_mass.players = controller
4449 controller._players = {
4450 "sonos_kantoor": kantoor,
4451 "sendspin_kantoor": sendspin_kantoor,
4452 "sendspin_web": web_player,
4453 }
4454
4455 sendspin_kantoor.update_state(signal_event=False)
4456 kantoor.update_state(signal_event=False)
4457 web_player.update_state(signal_event=False)
4458
4459 # Translate removal â web player's own player_id should be used
4460 protocol_members, native_members = controller._translate_members_to_remove_for_protocols(
4461 parent_player=kantoor,
4462 player_ids=["sendspin_web"],
4463 parent_protocol_player=sendspin_kantoor,
4464 parent_protocol_domain="sendspin",
4465 )
4466
4467 # Web player's player_id should be in protocol removal list
4468 assert "sendspin_web" in protocol_members
4469 assert len(native_members) == 0
4470
4471 def test_filter_protocol_members_accepts_native_protocol_player(
4472 self, mock_mass: MagicMock
4473 ) -> None:
4474 """
4475 Test that _filter_protocol_members accepts native protocol-domain players.
4476
4477 A PlayerType.PLAYER with matching provider domain should pass through the
4478 filter, not just PlayerType.PROTOCOL players.
4479 """
4480 controller = PlayerController(mock_mass)
4481
4482 sendspin_provider = MockProvider("sendspin", instance_id="sendspin", mass=mock_mass)
4483
4484 # Protocol player (the parent's linked sendspin)
4485 sendspin_parent = MockPlayer(
4486 sendspin_provider,
4487 "sendspin_parent",
4488 "Parent (Sendspin)",
4489 player_type=PlayerType.PROTOCOL,
4490 )
4491 sendspin_parent._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
4492 sendspin_parent._cache.clear()
4493
4494 # Native sendspin web player (PlayerType.PLAYER)
4495 web_player = MockPlayer(sendspin_provider, "sendspin_web", "Web (Chrome on Mac)")
4496 web_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4497 web_player._cache.clear()
4498
4499 # Another protocol type sendspin player
4500 sendspin_other = MockPlayer(
4501 sendspin_provider,
4502 "sendspin_other",
4503 "Other (Sendspin)",
4504 player_type=PlayerType.PROTOCOL,
4505 )
4506 sendspin_other._cache.clear()
4507
4508 mock_mass.players = controller
4509 controller._players = {
4510 "sendspin_parent": sendspin_parent,
4511 "sendspin_web": web_player,
4512 "sendspin_other": sendspin_other,
4513 }
4514
4515 sendspin_parent.update_state(signal_event=False)
4516 web_player.update_state(signal_event=False)
4517 sendspin_other.update_state(signal_event=False)
4518
4519 # Both native and protocol players should pass through the filter
4520 filtered = controller._filter_protocol_members(
4521 ["sendspin_web", "sendspin_other"],
4522 sendspin_parent,
4523 )
4524
4525 assert "sendspin_web" in filtered
4526 assert "sendspin_other" in filtered
4527 assert len(filtered) == 2
4528
4529 def test_sendspin_visualizer_groups_via_common_protocol(self, mock_mass: MagicMock) -> None:
4530 """
4531 Test grouping a sendspin visualizer (e.g. Hue light) with a sendspin-bridged parent.
4532
4533 Visualizer players have no PLAY_MEDIA so they are not native players, but the
4534 Sendspin provider advertises a self-referential sendspin output protocol on them
4535 (is_native=True) so the common-protocol search (Priority 4) can match them against
4536 any parent that has a sendspin bridge linked.
4537 """
4538 controller = PlayerController(mock_mass)
4539
4540 sonos_provider = MockProvider("sonos", instance_id="sonos", mass=mock_mass)
4541 sendspin_provider = MockProvider("sendspin", instance_id="sendspin", mass=mock_mass)
4542
4543 # Mancave: native Sonos parent with sendspin bridge linked
4544 mancave = MockPlayer(sonos_provider, "sonos_mancave", "Mancave")
4545 mancave._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
4546 mancave._cache.clear()
4547
4548 # Sendspin bridge protocol player linked to Mancave
4549 sendspin_bridge = MockPlayer(
4550 sendspin_provider,
4551 "spb_mancave",
4552 "Mancave (AirPlay)",
4553 player_type=PlayerType.PROTOCOL,
4554 )
4555 sendspin_bridge._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
4556 sendspin_bridge._attr_can_group_with = {"sendspin"}
4557 sendspin_bridge._cache.clear()
4558 sendspin_bridge.set_protocol_parent_id("sonos_mancave")
4559
4560 # Hue visualizer: sendspin provider, no PLAY_MEDIA, has SET_MEMBERS, type LIGHT
4561 hue_light = MockPlayer(
4562 sendspin_provider,
4563 "hue-mancave",
4564 "Hue: Mancave",
4565 player_type=PlayerType.LIGHT,
4566 )
4567 hue_light._attr_supported_features = {PlayerFeature.SET_MEMBERS}
4568 hue_light._cache.clear()
4569
4570 mancave.set_linked_output_protocols(
4571 [
4572 LinkedOutputProtocol(
4573 output_protocol_id="spb_mancave",
4574 protocol_domain="sendspin",
4575 priority=40,
4576 )
4577 ]
4578 )
4579
4580 mock_mass.players = controller
4581 controller._players = {
4582 "sonos_mancave": mancave,
4583 "spb_mancave": sendspin_bridge,
4584 "hue-mancave": hue_light,
4585 }
4586
4587 sendspin_bridge.update_state(signal_event=False)
4588 mancave.update_state(signal_event=False)
4589 hue_light.update_state(signal_event=False)
4590
4591 protocol_members, native_members, protocol_player, protocol_domain = (
4592 controller._translate_members_for_protocols(
4593 parent_player=mancave,
4594 player_ids=["hue-mancave"],
4595 parent_protocol_player=None,
4596 parent_protocol_domain=None,
4597 )
4598 )
4599
4600 # Priority 4 should match sendspinâsendspin and route via the bridge,
4601 # using the visualizer's player_id directly (is_native=True).
4602 assert protocol_members == ["hue-mancave"]
4603 assert native_members == []
4604 assert protocol_domain == "sendspin"
4605 assert protocol_player == sendspin_bridge
4606
4607
4608class TestEnrichPlayerIdentifiers:
4609 """Tests for MAC address enrichment via ARP lookup."""
4610
4611 @pytest.mark.asyncio
4612 async def test_no_ip_skips_enrichment(self, mock_mass: MagicMock) -> None:
4613 """Test that enrichment is skipped when no IP address is available."""
4614 provider = MockProvider("sendspin", mass=mock_mass)
4615 # Sendspin bridge player has MAC but no IP
4616 player = MockPlayer(
4617 provider,
4618 "spb_62e5974593d3",
4619 "Apple TV (Sendspin)",
4620 player_type=PlayerType.PROTOCOL,
4621 identifiers={IdentifierType.MAC_ADDRESS: "62:E5:97:45:93:D3"},
4622 )
4623
4624 await enrich_device_mac_address(player.device_info)
4625
4626 # MAC should remain unchanged (no IP = no ARP lookup)
4627 assert player.device_info.identifiers[IdentifierType.MAC_ADDRESS] == "62:E5:97:45:93:D3"
4628
4629 @pytest.mark.asyncio
4630 async def test_valid_hardware_mac_skips_enrichment(self, mock_mass: MagicMock) -> None:
4631 """Test that a valid, non-locally-administered MAC skips enrichment."""
4632 provider = MockProvider("sonos", mass=mock_mass)
4633 player = MockPlayer(
4634 provider,
4635 "sonos_123",
4636 "Sonos Speaker",
4637 player_type=PlayerType.PLAYER,
4638 identifiers={
4639 IdentifierType.MAC_ADDRESS: "54:78:C9:E6:0D:A0",
4640 IdentifierType.IP_ADDRESS: "192.168.1.100",
4641 },
4642 )
4643
4644 await enrich_device_mac_address(player.device_info)
4645
4646 # MAC should remain unchanged (valid hardware MAC, not locally administered)
4647 assert player.device_info.identifiers[IdentifierType.MAC_ADDRESS] == "54:78:C9:E6:0D:A0"
4648
4649 @pytest.mark.asyncio
4650 async def test_locally_administered_bit_difference_replaces_mac(
4651 self, mock_mass: MagicMock
4652 ) -> None:
4653 """
4654 Test that ARP MAC replaces reported MAC when only the locally-administered bit differs.
4655
4656 Example: AirPlay reports 56:78:C9:E6:0D:A0, ARP resolves 54:78:C9:E6:0D:A0.
4657 These differ only in bit 1 of the first octet (locally-administered bit).
4658 """
4659 provider = MockProvider("airplay", mass=mock_mass)
4660 player = MockPlayer(
4661 provider,
4662 "ap_5678c9e60da0",
4663 "WiiM Pro (AirPlay)",
4664 player_type=PlayerType.PROTOCOL,
4665 identifiers={
4666 IdentifierType.MAC_ADDRESS: "56:78:C9:E6:0D:A0",
4667 IdentifierType.IP_ADDRESS: "192.168.1.50",
4668 },
4669 )
4670
4671 with patch(
4672 "music_assistant.helpers.util.resolve_real_mac_address",
4673 new_callable=AsyncMock,
4674 return_value="54:78:C9:E6:0D:A0",
4675 ):
4676 await enrich_device_mac_address(player.device_info)
4677
4678 # MAC should be replaced with the ARP-resolved hardware MAC
4679 assert player.device_info.identifiers[IdentifierType.MAC_ADDRESS] == "54:78:C9:E6:0D:A0"
4680
4681 @pytest.mark.asyncio
4682 async def test_completely_different_mac_replaced_by_arp(self, mock_mass: MagicMock) -> None:
4683 """
4684 Test that ARP result always replaces a locally-administered MAC.
4685
4686 Even when the ARP MAC is completely different from the reported MAC
4687 (e.g., Apple devices with random private MACs), the ARP result is used
4688 because it's the hardware truth that reliably unifies protocols.
4689 Sendspin bridges match via AIRPLAY_ID/CAST_UUID, not MAC.
4690 """
4691 provider = MockProvider("airplay", mass=mock_mass)
4692 player = MockPlayer(
4693 provider,
4694 "ap62e5974593d3",
4695 "Apple TV (AirPlay)",
4696 player_type=PlayerType.PLAYER,
4697 identifiers={
4698 IdentifierType.MAC_ADDRESS: "62:E5:97:45:93:D3",
4699 IdentifierType.IP_ADDRESS: "192.168.1.200",
4700 },
4701 )
4702
4703 with patch(
4704 "music_assistant.helpers.util.resolve_real_mac_address",
4705 new_callable=AsyncMock,
4706 return_value="C0:95:6D:51:34:E0",
4707 ):
4708 await enrich_device_mac_address(player.device_info)
4709
4710 # MAC should be replaced with ARP result (hardware truth)
4711 assert player.device_info.identifiers[IdentifierType.MAC_ADDRESS] == "C0:95:6D:51:34:E0"
4712
4713 @pytest.mark.asyncio
4714 async def test_no_reported_mac_uses_arp_result(self, mock_mass: MagicMock) -> None:
4715 """Test that ARP MAC is used when no MAC was reported at all."""
4716 provider = MockProvider("chromecast", mass=mock_mass)
4717 player = MockPlayer(
4718 provider,
4719 "cc_123",
4720 "Chromecast",
4721 player_type=PlayerType.PROTOCOL,
4722 identifiers={IdentifierType.IP_ADDRESS: "192.168.1.75"},
4723 )
4724
4725 with patch(
4726 "music_assistant.helpers.util.resolve_real_mac_address",
4727 new_callable=AsyncMock,
4728 return_value="AA:BB:CC:DD:EE:FF",
4729 ):
4730 await enrich_device_mac_address(player.device_info)
4731
4732 # MAC should be set from ARP since there was none before
4733 assert player.device_info.identifiers[IdentifierType.MAC_ADDRESS] == "AA:BB:CC:DD:EE:FF"
4734
4735 @pytest.mark.asyncio
4736 async def test_invalid_mac_replaced_by_arp(self, mock_mass: MagicMock) -> None:
4737 """Test that an invalid MAC (00:00:00:00:00:00) is replaced by ARP result."""
4738 provider = MockProvider("dlna", mass=mock_mass)
4739 player = MockPlayer(
4740 provider,
4741 "dlna_123",
4742 "DLNA Device",
4743 player_type=PlayerType.PROTOCOL,
4744 identifiers={
4745 IdentifierType.MAC_ADDRESS: "00:00:00:00:00:00",
4746 IdentifierType.IP_ADDRESS: "192.168.1.60",
4747 },
4748 )
4749
4750 with patch(
4751 "music_assistant.helpers.util.resolve_real_mac_address",
4752 new_callable=AsyncMock,
4753 return_value="11:22:33:44:55:66",
4754 ):
4755 await enrich_device_mac_address(player.device_info)
4756
4757 # Invalid MAC should be replaced
4758 assert player.device_info.identifiers[IdentifierType.MAC_ADDRESS] == "11:22:33:44:55:66"
4759
4760 @pytest.mark.asyncio
4761 async def test_arp_returns_none_no_change(self, mock_mass: MagicMock) -> None:
4762 """Test that MAC is unchanged when ARP lookup returns None."""
4763 provider = MockProvider("airplay", mass=mock_mass)
4764 player = MockPlayer(
4765 provider,
4766 "ap_123",
4767 "AirPlay Device",
4768 player_type=PlayerType.PROTOCOL,
4769 identifiers={
4770 IdentifierType.MAC_ADDRESS: "62:E5:97:45:93:D3",
4771 IdentifierType.IP_ADDRESS: "192.168.1.100",
4772 },
4773 )
4774
4775 with patch(
4776 "music_assistant.helpers.util.resolve_real_mac_address",
4777 new_callable=AsyncMock,
4778 return_value=None,
4779 ):
4780 await enrich_device_mac_address(player.device_info)
4781
4782 # MAC should remain unchanged
4783 assert player.device_info.identifiers[IdentifierType.MAC_ADDRESS] == "62:E5:97:45:93:D3"
4784
4785 @pytest.mark.asyncio
4786 async def test_ipv6_mapped_ipv4_normalized(self, mock_mass: MagicMock) -> None:
4787 """Test that IPv6-mapped IPv4 addresses are normalized."""
4788 provider = MockProvider("airplay", mass=mock_mass)
4789 player = MockPlayer(
4790 provider,
4791 "ap_123",
4792 "AirPlay Device",
4793 player_type=PlayerType.PROTOCOL,
4794 identifiers={
4795 IdentifierType.MAC_ADDRESS: "54:78:C9:E6:0D:A0",
4796 IdentifierType.IP_ADDRESS: "::ffff:192.168.1.100",
4797 },
4798 )
4799
4800 await enrich_device_mac_address(player.device_info)
4801
4802 # IP should be normalized to IPv4
4803 assert player.device_info.identifiers[IdentifierType.IP_ADDRESS] == "192.168.1.100"
4804
4805
4806def _create_universal_player(
4807 mock_mass: MagicMock,
4808 player_id: str,
4809 name: str,
4810 protocol_player_ids: list[str],
4811 identifiers: dict[IdentifierType, str] | None = None,
4812) -> UniversalPlayer:
4813 """Create a UniversalPlayer for testing."""
4814 universal_provider = create_mock_universal_provider(mock_mass)
4815 # Set up config so provider.instance_id works
4816 provider_config = MagicMock()
4817 provider_config.instance_id = "universal_player"
4818 provider_config.name = None
4819 universal_provider.config = provider_config
4820 mock_mass.config.get_base_player_config.return_value = create_mock_config(name)
4821
4822 device_info = DeviceInfo(
4823 model="Universal Player",
4824 manufacturer="Music Assistant",
4825 )
4826 if identifiers:
4827 for conn_type, value in identifiers.items():
4828 device_info.add_identifier(conn_type, value)
4829
4830 player = UniversalPlayer(
4831 provider=universal_provider,
4832 player_id=player_id,
4833 name=name,
4834 device_info=device_info,
4835 protocol_player_ids=protocol_player_ids,
4836 )
4837 player._attr_available = True
4838 player._cache.clear()
4839 player.set_initialized()
4840 return player
4841
4842
4843class TestProtocolToUniversalIdentifierFallback:
4844 """
4845 Tests for Fix 1: identifier-based fallback matching for Universal Players.
4846
4847 When a new protocol player (like Sendspin bridge) registers and its ID isn't
4848 in the Universal Player's stored _protocol_player_ids list, the system should
4849 fall back to identifier matching (MAC address) to find the correct parent.
4850 """
4851
4852 def test_new_protocol_matches_universal_by_mac(self, mock_mass: MagicMock) -> None:
4853 """Test that a new protocol player matches a Universal Player by MAC address."""
4854 controller = PlayerController(mock_mass)
4855
4856 # No cached parent_id for the sendspin player
4857 def mock_config_get(_key: str, default: str | None = None) -> str | None:
4858 return default
4859
4860 mock_mass.config.get.side_effect = mock_config_get
4861
4862 # Create existing universal player with known MAC (from AirPlay)
4863 universal = _create_universal_player(
4864 mock_mass,
4865 "up_62e5974593d3",
4866 "Apple TV",
4867 protocol_player_ids=["ap62e5974593d3"],
4868 identifiers={IdentifierType.MAC_ADDRESS: "62:E5:97:45:93:D3"},
4869 )
4870
4871 # Create AirPlay protocol player (already linked)
4872 airplay_provider = MockProvider("airplay", mass=mock_mass)
4873 airplay_player = MockPlayer(
4874 airplay_provider,
4875 "ap62e5974593d3",
4876 "Apple TV (AirPlay)",
4877 player_type=PlayerType.PROTOCOL,
4878 identifiers={IdentifierType.MAC_ADDRESS: "62:E5:97:45:93:D3"},
4879 )
4880 airplay_player.set_protocol_parent_id("up_62e5974593d3")
4881
4882 # Create NEW Sendspin bridge player with same MAC (not yet in _protocol_player_ids)
4883 sendspin_provider = MockProvider("sendspin", mass=mock_mass)
4884 sendspin_player = MockPlayer(
4885 sendspin_provider,
4886 "spb_62e5974593d3",
4887 "Apple TV (Sendspin)",
4888 player_type=PlayerType.PROTOCOL,
4889 identifiers={IdentifierType.MAC_ADDRESS: "62:E5:97:45:93:D3"},
4890 )
4891
4892 mock_mass.players = controller
4893 controller._players = {
4894 "up_62e5974593d3": universal,
4895 "ap62e5974593d3": airplay_player,
4896 "spb_62e5974593d3": sendspin_player,
4897 }
4898
4899 # Initialize players so all_players() returns them
4900 airplay_player.set_initialized()
4901 sendspin_player.set_initialized()
4902
4903 # Try to link Sendspin player
4904 controller._try_link_protocol_to_native(sendspin_player)
4905
4906 # Should be linked to the universal player via identifier matching
4907 assert sendspin_player.protocol_parent_id == "up_62e5974593d3"
4908
4909 # Should be added to universal player's protocol list
4910 assert "spb_62e5974593d3" in universal._protocol_player_ids
4911
4912 # Should have a linked output protocol
4913 assert any(
4914 link.output_protocol_id == "spb_62e5974593d3"
4915 for link in universal.linked_output_protocols
4916 )
4917
4918 def test_new_protocol_no_match_skips_universal(self, mock_mass: MagicMock) -> None:
4919 """Test that a protocol player with different MAC doesn't match the wrong Universal."""
4920 controller = PlayerController(mock_mass)
4921
4922 # No cached parent_id
4923 def mock_config_get(_key: str, default: str | None = None) -> str | None:
4924 return default
4925
4926 mock_mass.config.get.side_effect = mock_config_get
4927
4928 # Create universal player for Device A
4929 universal = _create_universal_player(
4930 mock_mass,
4931 "up_aabbccddeeff",
4932 "Device A",
4933 protocol_player_ids=["ap_aabbccddeeff"],
4934 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
4935 )
4936
4937 # Create protocol player for a completely different device
4938 sendspin_provider = MockProvider("sendspin", mass=mock_mass)
4939 sendspin_player = MockPlayer(
4940 sendspin_provider,
4941 "spb_112233445566",
4942 "Device B (Sendspin)",
4943 player_type=PlayerType.PROTOCOL,
4944 identifiers={IdentifierType.MAC_ADDRESS: "11:22:33:44:55:66"},
4945 )
4946
4947 mock_mass.players = controller
4948 controller._players = {
4949 "up_aabbccddeeff": universal,
4950 "spb_112233445566": sendspin_player,
4951 }
4952
4953 sendspin_player.set_initialized()
4954
4955 controller._try_link_protocol_to_native(sendspin_player)
4956
4957 # Should NOT be linked to the wrong universal player
4958 assert sendspin_player.protocol_parent_id != "up_aabbccddeeff"
4959
4960 def test_known_protocol_id_still_works(self, mock_mass: MagicMock) -> None:
4961 """Test that the existing path (player_id in _protocol_player_ids) still works."""
4962 controller = PlayerController(mock_mass)
4963
4964 # No cached parent_id
4965 def mock_config_get(_key: str, default: str | None = None) -> str | None:
4966 return default
4967
4968 mock_mass.config.get.side_effect = mock_config_get
4969
4970 airplay_provider = MockProvider("airplay", mass=mock_mass)
4971 airplay_player = MockPlayer(
4972 airplay_provider,
4973 "ap_aabbccddeeff",
4974 "AirPlay Device",
4975 player_type=PlayerType.PROTOCOL,
4976 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
4977 )
4978
4979 # Universal player already has this player_id in its list
4980 universal = _create_universal_player(
4981 mock_mass,
4982 "up_aabbccddeeff",
4983 "Device",
4984 protocol_player_ids=["ap_aabbccddeeff"],
4985 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
4986 )
4987
4988 mock_mass.players = controller
4989 controller._players = {
4990 "up_aabbccddeeff": universal,
4991 "ap_aabbccddeeff": airplay_player,
4992 }
4993
4994 airplay_player.set_initialized()
4995
4996 controller._try_link_protocol_to_native(airplay_player)
4997
4998 # Should be linked via the existing stored ID path
4999 assert airplay_player.protocol_parent_id == "up_aabbccddeeff"
5000
5001
5002class TestCachedParentIdentifierCopying:
5003 """
5004 Tests for Fix 2: identifier copying when restoring cached parent links.
5005
5006 When a protocol player reconnects and links to a Universal Player via the
5007 cached_parent_id fast path, identifiers must be copied to the Universal Player.
5008 Restored Universal Players start with empty identifiers, so without this copy,
5009 subsequent protocol players (like Sendspin bridges) cannot match by identifiers.
5010 """
5011
5012 def test_identifiers_copied_on_cached_parent_restore(self, mock_mass: MagicMock) -> None:
5013 """Test that identifiers are copied from protocol player to Universal Player on restore."""
5014 controller = PlayerController(mock_mass)
5015
5016 # Mock config to return cached parent_id
5017 def mock_config_get(key: str, default: str | None = None) -> str | None:
5018 if "protocol_parent_id" in str(key):
5019 return "up_62e5974593d3"
5020 return default
5021
5022 mock_mass.config.get.side_effect = mock_config_get
5023
5024 # Create restored universal player with EMPTY identifiers (simulates restart)
5025 universal = _create_universal_player(
5026 mock_mass,
5027 "up_62e5974593d3",
5028 "Apple TV",
5029 protocol_player_ids=["ap62e5974593d3"],
5030 # No identifiers - simulates restored state
5031 )
5032
5033 # Create AirPlay protocol player reconnecting with its identifiers
5034 airplay_provider = MockProvider("airplay", mass=mock_mass)
5035 airplay_player = MockPlayer(
5036 airplay_provider,
5037 "ap62e5974593d3",
5038 "Apple TV (AirPlay)",
5039 player_type=PlayerType.PROTOCOL,
5040 identifiers={
5041 IdentifierType.MAC_ADDRESS: "62:E5:97:45:93:D3",
5042 IdentifierType.IP_ADDRESS: "192.168.1.200",
5043 },
5044 )
5045
5046 mock_mass.players = controller
5047 controller._players = {
5048 "up_62e5974593d3": universal,
5049 "ap62e5974593d3": airplay_player,
5050 }
5051
5052 # Link protocol player via cached parent path
5053 controller._try_link_protocol_to_native(airplay_player)
5054
5055 # Should be linked
5056 assert airplay_player.protocol_parent_id == "up_62e5974593d3"
5057
5058 # Universal player should now have the MAC from the protocol player
5059 assert (
5060 universal.device_info.identifiers.get(IdentifierType.MAC_ADDRESS) == "62:E5:97:45:93:D3"
5061 )
5062
5063 def test_sendspin_matches_after_identifier_copy(self, mock_mass: MagicMock) -> None:
5064 """
5065 Test the full scenario: AirPlay restores, copies identifiers, Sendspin matches.
5066
5067 AirPlay restores via cache, copies identifiers to the Universal Player,
5068 then the Sendspin bridge matches the Universal Player by MAC.
5069 This is the end-to-end test for the combined Fix 2 + Fix 1 interaction.
5070 """
5071 controller = PlayerController(mock_mass)
5072
5073 # Step 1: Mock config - AirPlay has cached parent, Sendspin does not
5074 def mock_config_get(key: str, default: str | None = None) -> str | None:
5075 if "ap62e5974593d3" in str(key) and "protocol_parent_id" in str(key):
5076 return "up_62e5974593d3"
5077 return default
5078
5079 mock_mass.config.get.side_effect = mock_config_get
5080
5081 # Create restored universal player with empty identifiers
5082 universal = _create_universal_player(
5083 mock_mass,
5084 "up_62e5974593d3",
5085 "Apple TV",
5086 protocol_player_ids=["ap62e5974593d3"],
5087 )
5088
5089 # Create AirPlay protocol player
5090 airplay_provider = MockProvider("airplay", mass=mock_mass)
5091 airplay_player = MockPlayer(
5092 airplay_provider,
5093 "ap62e5974593d3",
5094 "Apple TV (AirPlay)",
5095 player_type=PlayerType.PROTOCOL,
5096 identifiers={IdentifierType.MAC_ADDRESS: "62:E5:97:45:93:D3"},
5097 )
5098
5099 # Create Sendspin bridge player with same MAC
5100 sendspin_provider = MockProvider("sendspin", mass=mock_mass)
5101 sendspin_player = MockPlayer(
5102 sendspin_provider,
5103 "spb_62e5974593d3",
5104 "Apple TV (Sendspin)",
5105 player_type=PlayerType.PROTOCOL,
5106 identifiers={IdentifierType.MAC_ADDRESS: "62:E5:97:45:93:D3"},
5107 )
5108
5109 mock_mass.players = controller
5110 controller._players = {
5111 "up_62e5974593d3": universal,
5112 "ap62e5974593d3": airplay_player,
5113 "spb_62e5974593d3": sendspin_player,
5114 }
5115
5116 # Initialize players so all_players() returns them
5117 airplay_player.set_initialized()
5118 sendspin_player.set_initialized()
5119
5120 # Step 2: AirPlay reconnects first - links via cached parent_id
5121 controller._try_link_protocol_to_native(airplay_player)
5122
5123 # Verify AirPlay linked and identifiers copied
5124 assert airplay_player.protocol_parent_id == "up_62e5974593d3"
5125 assert (
5126 universal.device_info.identifiers.get(IdentifierType.MAC_ADDRESS) == "62:E5:97:45:93:D3"
5127 )
5128
5129 # Step 3: Sendspin registers next - should match Universal Player by MAC
5130 controller._try_link_protocol_to_native(sendspin_player)
5131
5132 # Sendspin should be linked to the SAME universal player
5133 assert sendspin_player.protocol_parent_id == "up_62e5974593d3"
5134 assert "spb_62e5974593d3" in universal._protocol_player_ids
5135
5136 def test_non_universal_parent_skips_identifier_copy(self, mock_mass: MagicMock) -> None:
5137 """Test that identifier copy is only done for Universal Players, not native players."""
5138 controller = PlayerController(mock_mass)
5139
5140 # Mock config to return cached parent_id pointing to a native player
5141 def mock_config_get(key: str, default: str | None = None) -> str | None:
5142 if "protocol_parent_id" in str(key):
5143 return "sonos_123"
5144 return default
5145
5146 mock_mass.config.get.side_effect = mock_config_get
5147
5148 # Create native Sonos player
5149 sonos_provider = MockProvider("sonos", mass=mock_mass)
5150 sonos_player = MockPlayer(
5151 sonos_provider,
5152 "sonos_123",
5153 "Sonos Speaker",
5154 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5155 )
5156 original_mac = sonos_player.device_info.identifiers[IdentifierType.MAC_ADDRESS]
5157
5158 # Create DLNA protocol player with different MAC
5159 dlna_provider = MockProvider("dlna", mass=mock_mass)
5160 dlna_player = MockPlayer(
5161 dlna_provider,
5162 "dlna_123",
5163 "Sonos DLNA",
5164 player_type=PlayerType.PROTOCOL,
5165 identifiers={IdentifierType.MAC_ADDRESS: "11:22:33:44:55:66"},
5166 )
5167
5168 mock_mass.players = controller
5169 controller._players = {
5170 "sonos_123": sonos_player,
5171 "dlna_123": dlna_player,
5172 }
5173
5174 controller._try_link_protocol_to_native(dlna_player)
5175
5176 # Should be linked
5177 assert dlna_player.protocol_parent_id == "sonos_123"
5178
5179 # Native player's MAC should NOT be overwritten
5180 assert sonos_player.device_info.identifiers[IdentifierType.MAC_ADDRESS] == original_mac
5181
5182
5183class TestEnrichAndMatchIntegration:
5184 """
5185 Integration tests for the interaction between MAC enrichment and identifier matching.
5186
5187 These tests verify that Fix 3 (preserving original MAC when ARP resolves a
5188 completely different address) works correctly with the identifier matching system.
5189 """
5190
5191 @pytest.mark.asyncio
5192 async def test_apple_device_sendspin_matches_via_airplay_id(self, mock_mass: MagicMock) -> None:
5193 """
5194 Test the full Apple device scenario end-to-end.
5195
5196 1. AirPlay player registers with private MAC 62:E5:97:45:93:D3
5197 2. ARP resolves to hardware MAC C0:95:6D:51:34:E0 (always used)
5198 3. Sendspin bridge matches via AIRPLAY_ID, not MAC
5199 """
5200 controller = PlayerController(mock_mass)
5201
5202 # Create AirPlay player (Apple TV - native PLAYER type)
5203 airplay_provider = MockProvider("airplay", mass=mock_mass)
5204 airplay_player = MockPlayer(
5205 airplay_provider,
5206 "ap62e5974593d3",
5207 "Apple TV",
5208 player_type=PlayerType.PLAYER,
5209 identifiers={
5210 IdentifierType.MAC_ADDRESS: "62:E5:97:45:93:D3",
5211 IdentifierType.AIRPLAY_ID: "62:E5:97:45:93:D3",
5212 IdentifierType.IP_ADDRESS: "192.168.1.200",
5213 },
5214 )
5215
5216 # ARP enrichment replaces MAC with hardware truth
5217 with patch(
5218 "music_assistant.helpers.util.resolve_real_mac_address",
5219 new_callable=AsyncMock,
5220 return_value="C0:95:6D:51:34:E0",
5221 ):
5222 await enrich_device_mac_address(airplay_player.device_info)
5223
5224 # MAC replaced with ARP result
5225 assert (
5226 airplay_player.device_info.identifiers[IdentifierType.MAC_ADDRESS]
5227 == "C0:95:6D:51:34:E0"
5228 )
5229
5230 # Create Sendspin bridge player with AIRPLAY_ID (how Sendspin actually matches)
5231 sendspin_provider = MockProvider("sendspin", mass=mock_mass)
5232 sendspin_player = MockPlayer(
5233 sendspin_provider,
5234 "spb_62e5974593d3",
5235 "Apple TV (Sendspin)",
5236 player_type=PlayerType.PROTOCOL,
5237 identifiers={IdentifierType.AIRPLAY_ID: "62:E5:97:45:93:D3"},
5238 )
5239
5240 # Identifiers match via AIRPLAY_ID
5241 assert controller._identifiers_match(airplay_player, sendspin_player, "sendspin") is True
5242
5243 @pytest.mark.asyncio
5244 async def test_wiim_device_mac_replaced_still_matches(self, mock_mass: MagicMock) -> None:
5245 """
5246 Test that WiiM devices match after ARP enrichment.
5247
5248 WiiM AirPlay reports 56:78:C9:E6:0D:A0 (locally administered), ARP resolves to
5249 54:78:C9:E6:0D:A0 (hardware). The MAC is always replaced with the ARP result.
5250 """
5251 controller = PlayerController(mock_mass)
5252
5253 # Create AirPlay player (WiiM - PROTOCOL type)
5254 airplay_provider = MockProvider("airplay", mass=mock_mass)
5255 airplay_player = MockPlayer(
5256 airplay_provider,
5257 "ap_5678c9e60da0",
5258 "WiiM Pro (AirPlay)",
5259 player_type=PlayerType.PROTOCOL,
5260 identifiers={
5261 IdentifierType.MAC_ADDRESS: "56:78:C9:E6:0D:A0",
5262 IdentifierType.IP_ADDRESS: "192.168.1.50",
5263 },
5264 )
5265
5266 # ARP resolves MAC that differs only in locally-administered bit
5267 with patch(
5268 "music_assistant.helpers.util.resolve_real_mac_address",
5269 new_callable=AsyncMock,
5270 return_value="54:78:C9:E6:0D:A0",
5271 ):
5272 await enrich_device_mac_address(airplay_player.device_info)
5273
5274 # MAC should be replaced (only bit difference)
5275 assert (
5276 airplay_player.device_info.identifiers[IdentifierType.MAC_ADDRESS]
5277 == "54:78:C9:E6:0D:A0"
5278 )
5279
5280 # DLNA player also reports hardware MAC
5281 dlna_provider = MockProvider("dlna", mass=mock_mass)
5282 dlna_player = MockPlayer(
5283 dlna_provider,
5284 "dlna_5478c9e60da0",
5285 "WiiM Pro (DLNA)",
5286 player_type=PlayerType.PROTOCOL,
5287 identifiers={IdentifierType.MAC_ADDRESS: "54:78:C9:E6:0D:A0"},
5288 )
5289
5290 # Should match by MAC
5291 assert controller._identifiers_match(airplay_player, dlna_player, "dlna") is True
5292
5293
5294class TestDuplicateProtocolPrevention:
5295 """
5296 Tests for preventing duplicate protocol domain linking.
5297
5298 When multiple instances of the same protocol (e.g., two AirPlay or ShairPort-Sync
5299 instances, or multi-zone Bluesound players) run on the same host, they share the
5300 same IP/MAC. These must NOT all bind to the same parent player â each should get
5301 its own separate universal player.
5302 """
5303
5304 def test_parent_has_active_protocol_from_domain_empty(self, mock_mass: MagicMock) -> None:
5305 """Test helper returns False when parent has no linked protocols."""
5306 controller = PlayerController(mock_mass)
5307
5308 sonos_provider = MockProvider("sonos")
5309 sonos_player = MockPlayer(
5310 sonos_provider, "sonos_1", "Sonos Speaker", player_type=PlayerType.PLAYER
5311 )
5312
5313 assert controller._parent_has_active_protocol_from_domain(sonos_player, "airplay") is False
5314
5315 def test_parent_has_active_protocol_from_domain_true(self, mock_mass: MagicMock) -> None:
5316 """Test helper returns True when parent has an active link from the given domain."""
5317 controller = PlayerController(mock_mass)
5318
5319 sonos_provider = MockProvider("sonos")
5320 sonos_player = MockPlayer(
5321 sonos_provider, "sonos_1", "Sonos Speaker", player_type=PlayerType.PLAYER
5322 )
5323
5324 airplay_provider = MockProvider("airplay")
5325 airplay_player = MockPlayer(
5326 airplay_provider,
5327 "ap_1",
5328 "AirPlay 1",
5329 player_type=PlayerType.PROTOCOL,
5330 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5331 )
5332 airplay_player._attr_available = True
5333 airplay_player._cache.clear()
5334 airplay_player.update_state(signal_event=False)
5335
5336 # Register players
5337 controller._players = {
5338 "sonos_1": sonos_player,
5339 "ap_1": airplay_player,
5340 }
5341 airplay_player.set_initialized()
5342 sonos_player.set_initialized()
5343
5344 # Add a protocol link
5345 controller._add_protocol_link(sonos_player, airplay_player, "airplay")
5346
5347 assert controller._parent_has_active_protocol_from_domain(sonos_player, "airplay") is True
5348 assert controller._parent_has_active_protocol_from_domain(sonos_player, "dlna") is False
5349
5350 def test_parent_has_active_protocol_excludes_player_id(self, mock_mass: MagicMock) -> None:
5351 """Test helper excludes the specified player_id from the check."""
5352 controller = PlayerController(mock_mass)
5353
5354 sonos_provider = MockProvider("sonos")
5355 sonos_player = MockPlayer(
5356 sonos_provider, "sonos_1", "Sonos Speaker", player_type=PlayerType.PLAYER
5357 )
5358
5359 airplay_provider = MockProvider("airplay")
5360 airplay_player = MockPlayer(
5361 airplay_provider,
5362 "ap_1",
5363 "AirPlay 1",
5364 player_type=PlayerType.PROTOCOL,
5365 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5366 )
5367 airplay_player._attr_available = True
5368 airplay_player._cache.clear()
5369 airplay_player.update_state(signal_event=False)
5370
5371 controller._players = {
5372 "sonos_1": sonos_player,
5373 "ap_1": airplay_player,
5374 }
5375 airplay_player.set_initialized()
5376 sonos_player.set_initialized()
5377
5378 controller._add_protocol_link(sonos_player, airplay_player, "airplay")
5379
5380 # Should return False when the only match is the excluded player
5381 assert (
5382 controller._parent_has_active_protocol_from_domain(
5383 sonos_player, "airplay", exclude_player_id="ap_1"
5384 )
5385 is False
5386 )
5387
5388 def test_add_protocol_link_refuses_duplicate_domain(self, mock_mass: MagicMock) -> None:
5389 """Test that _add_protocol_link refuses when domain already has an active link."""
5390 controller = PlayerController(mock_mass)
5391
5392 sonos_provider = MockProvider("sonos")
5393 sonos_player = MockPlayer(
5394 sonos_provider, "sonos_1", "Sonos Speaker", player_type=PlayerType.PLAYER
5395 )
5396
5397 airplay_provider = MockProvider("airplay")
5398 ap1 = MockPlayer(
5399 airplay_provider,
5400 "ap_1",
5401 "AirPlay 1",
5402 player_type=PlayerType.PROTOCOL,
5403 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5404 )
5405 ap2 = MockPlayer(
5406 airplay_provider,
5407 "ap_2",
5408 "AirPlay 2",
5409 player_type=PlayerType.PROTOCOL,
5410 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5411 )
5412
5413 # Both available
5414 ap1._attr_available = True
5415 ap1._cache.clear()
5416 ap1.update_state(signal_event=False)
5417 ap2._attr_available = True
5418 ap2._cache.clear()
5419 ap2.update_state(signal_event=False)
5420
5421 controller._players = {
5422 "sonos_1": sonos_player,
5423 "ap_1": ap1,
5424 "ap_2": ap2,
5425 }
5426 ap1.set_initialized()
5427 ap2.set_initialized()
5428 sonos_player.set_initialized()
5429
5430 # Link first AirPlay - should succeed
5431 controller._add_protocol_link(sonos_player, ap1, "airplay")
5432 assert ap1.protocol_parent_id == "sonos_1"
5433 assert len(sonos_player.linked_output_protocols) == 1
5434
5435 # Link second AirPlay - should be refused (domain already active)
5436 controller._add_protocol_link(sonos_player, ap2, "airplay")
5437 assert ap2.protocol_parent_id is None
5438 assert len(sonos_player.linked_output_protocols) == 1
5439 assert sonos_player.linked_output_protocols[0].output_protocol_id == "ap_1"
5440
5441 def test_add_protocol_link_allows_different_domains(self, mock_mass: MagicMock) -> None:
5442 """Test that _add_protocol_link allows links from different protocol domains."""
5443 controller = PlayerController(mock_mass)
5444
5445 sonos_provider = MockProvider("sonos")
5446 sonos_player = MockPlayer(
5447 sonos_provider, "sonos_1", "Sonos Speaker", player_type=PlayerType.PLAYER
5448 )
5449
5450 airplay_provider = MockProvider("airplay")
5451 ap1 = MockPlayer(
5452 airplay_provider,
5453 "ap_1",
5454 "AirPlay",
5455 player_type=PlayerType.PROTOCOL,
5456 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5457 )
5458
5459 dlna_provider = MockProvider("dlna")
5460 dlna1 = MockPlayer(
5461 dlna_provider,
5462 "dlna_1",
5463 "DLNA",
5464 player_type=PlayerType.PROTOCOL,
5465 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5466 )
5467
5468 ap1._attr_available = True
5469 ap1._cache.clear()
5470 ap1.update_state(signal_event=False)
5471 dlna1._attr_available = True
5472 dlna1._cache.clear()
5473 dlna1.update_state(signal_event=False)
5474
5475 controller._players = {
5476 "sonos_1": sonos_player,
5477 "ap_1": ap1,
5478 "dlna_1": dlna1,
5479 }
5480 ap1.set_initialized()
5481 dlna1.set_initialized()
5482 sonos_player.set_initialized()
5483
5484 # Link AirPlay - should succeed
5485 controller._add_protocol_link(sonos_player, ap1, "airplay")
5486 assert ap1.protocol_parent_id == "sonos_1"
5487
5488 # Link DLNA - should also succeed (different domain)
5489 controller._add_protocol_link(sonos_player, dlna1, "dlna")
5490 assert dlna1.protocol_parent_id == "sonos_1"
5491 assert len(sonos_player.linked_output_protocols) == 2
5492
5493 def test_add_protocol_link_allows_replacing_removed_player(self, mock_mass: MagicMock) -> None:
5494 """Test that a new link can replace a stale one after the old player is removed."""
5495 controller = PlayerController(mock_mass)
5496
5497 sonos_provider = MockProvider("sonos")
5498 sonos_player = MockPlayer(
5499 sonos_provider, "sonos_1", "Sonos Speaker", player_type=PlayerType.PLAYER
5500 )
5501
5502 airplay_provider = MockProvider("airplay")
5503 ap1 = MockPlayer(
5504 airplay_provider,
5505 "ap_1",
5506 "AirPlay 1",
5507 player_type=PlayerType.PROTOCOL,
5508 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5509 )
5510 ap2 = MockPlayer(
5511 airplay_provider,
5512 "ap_2",
5513 "AirPlay 2",
5514 player_type=PlayerType.PROTOCOL,
5515 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5516 )
5517
5518 ap1._attr_available = True
5519 ap1._cache.clear()
5520 ap1.update_state(signal_event=False)
5521 ap2._attr_available = True
5522 ap2._cache.clear()
5523 ap2.update_state(signal_event=False)
5524
5525 controller._players = {
5526 "sonos_1": sonos_player,
5527 "ap_1": ap1,
5528 "ap_2": ap2,
5529 }
5530 ap1.set_initialized()
5531 ap2.set_initialized()
5532 sonos_player.set_initialized()
5533
5534 # Link first AirPlay
5535 controller._add_protocol_link(sonos_player, ap1, "airplay")
5536 assert ap1.protocol_parent_id == "sonos_1"
5537
5538 # Remove first AirPlay from registry (provider cleaned up stale player)
5539 del controller._players["ap_1"]
5540
5541 # Link second AirPlay - should succeed since first was removed
5542 controller._add_protocol_link(sonos_player, ap2, "airplay")
5543 assert ap2.protocol_parent_id == "sonos_1"
5544
5545 def test_add_protocol_link_blocks_when_existing_still_registered(
5546 self, mock_mass: MagicMock
5547 ) -> None:
5548 """Test that a new link is blocked when the old player is still registered."""
5549 controller = PlayerController(mock_mass)
5550
5551 sonos_provider = MockProvider("sonos")
5552 sonos_player = MockPlayer(
5553 sonos_provider, "sonos_1", "Sonos Speaker", player_type=PlayerType.PLAYER
5554 )
5555
5556 snap_provider = MockProvider("snapcast")
5557 snap1 = MockPlayer(
5558 snap_provider,
5559 "snap_1",
5560 "Snapcast 1",
5561 player_type=PlayerType.PROTOCOL,
5562 identifiers={IdentifierType.MAC_ADDRESS: "D0:11:E5:00:67:2F"},
5563 )
5564 snap2 = MockPlayer(
5565 snap_provider,
5566 "snap_2",
5567 "Snapcast 2",
5568 player_type=PlayerType.PROTOCOL,
5569 identifiers={IdentifierType.MAC_ADDRESS: "D0:11:E5:00:67:2F"},
5570 )
5571
5572 # Both unavailable
5573 snap1._attr_available = False
5574 snap1._cache.clear()
5575 snap1.update_state(signal_event=False)
5576 snap2._attr_available = False
5577 snap2._cache.clear()
5578 snap2.update_state(signal_event=False)
5579
5580 controller._players = {
5581 "sonos_1": sonos_player,
5582 "snap_1": snap1,
5583 "snap_2": snap2,
5584 }
5585 snap1.set_initialized()
5586 snap2.set_initialized()
5587 sonos_player.set_initialized()
5588
5589 # Link first snapcast
5590 controller._add_protocol_link(sonos_player, snap1, "snapcast")
5591 assert snap1.protocol_parent_id == "sonos_1"
5592
5593 # Try to link second snapcast - should be BLOCKED (snap1 still registered)
5594 controller._add_protocol_link(sonos_player, snap2, "snapcast")
5595 assert snap2.protocol_parent_id is None
5596
5597 def test_try_link_protocol_to_native_skips_duplicate_domain(self, mock_mass: MagicMock) -> None:
5598 """Test that _try_link_protocol_to_native falls through when domain is duplicate."""
5599 controller = PlayerController(mock_mass)
5600
5601 sonos_provider = MockProvider("sonos")
5602 sonos_player = MockPlayer(
5603 sonos_provider,
5604 "sonos_1",
5605 "Sonos Speaker",
5606 player_type=PlayerType.PLAYER,
5607 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5608 )
5609
5610 airplay_provider = MockProvider("airplay")
5611 ap1 = MockPlayer(
5612 airplay_provider,
5613 "ap_1",
5614 "AirPlay 1",
5615 player_type=PlayerType.PROTOCOL,
5616 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5617 )
5618 ap2 = MockPlayer(
5619 airplay_provider,
5620 "ap_2",
5621 "AirPlay 2",
5622 player_type=PlayerType.PROTOCOL,
5623 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5624 )
5625
5626 ap1._attr_available = True
5627 ap1._cache.clear()
5628 ap1.update_state(signal_event=False)
5629 ap2._attr_available = True
5630 ap2._cache.clear()
5631 ap2.update_state(signal_event=False)
5632
5633 controller._players = {
5634 "sonos_1": sonos_player,
5635 "ap_1": ap1,
5636 "ap_2": ap2,
5637 }
5638 ap1.set_initialized()
5639 ap2.set_initialized()
5640 sonos_player.set_initialized()
5641
5642 # Link first AirPlay to native player
5643 controller._add_protocol_link(sonos_player, ap1, "airplay")
5644 assert ap1.protocol_parent_id == "sonos_1"
5645
5646 # Mock _schedule_protocol_evaluation to track if it's called
5647 with patch.object(controller, "_schedule_protocol_evaluation") as mock_schedule:
5648 controller._try_link_protocol_to_native(ap2)
5649
5650 # ap2 should NOT have been linked to sonos
5651 assert ap2.protocol_parent_id is None
5652 # ap2 should be scheduled for delayed evaluation (which will create its own
5653 # universal player)
5654 mock_schedule.assert_called_once_with(ap2)
5655
5656 def test_try_link_protocols_to_native_skips_duplicate_domain(
5657 self, mock_mass: MagicMock
5658 ) -> None:
5659 """Test that _try_link_protocols_to_native skips protocol players with duplicate domain."""
5660 controller = PlayerController(mock_mass)
5661
5662 # Config.get returns {} for CONF_PLAYERS dict lookups
5663 mock_mass.config.get = MagicMock(side_effect=lambda _key, default=None: default or {})
5664
5665 sonos_provider = MockProvider("sonos")
5666 sonos_player = MockPlayer(
5667 sonos_provider,
5668 "sonos_1",
5669 "Sonos Speaker",
5670 player_type=PlayerType.PLAYER,
5671 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5672 )
5673
5674 airplay_provider = MockProvider("airplay")
5675 ap1 = MockPlayer(
5676 airplay_provider,
5677 "ap_1",
5678 "AirPlay 1",
5679 player_type=PlayerType.PROTOCOL,
5680 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5681 )
5682 ap2 = MockPlayer(
5683 airplay_provider,
5684 "ap_2",
5685 "AirPlay 2",
5686 player_type=PlayerType.PROTOCOL,
5687 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5688 )
5689
5690 dlna_provider = MockProvider("dlna")
5691 dlna_player = MockPlayer(
5692 dlna_provider,
5693 "dlna_1",
5694 "DLNA",
5695 player_type=PlayerType.PROTOCOL,
5696 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5697 )
5698
5699 ap1._attr_available = True
5700 ap1._cache.clear()
5701 ap1.update_state(signal_event=False)
5702 ap2._attr_available = True
5703 ap2._cache.clear()
5704 ap2.update_state(signal_event=False)
5705 dlna_player._attr_available = True
5706 dlna_player._cache.clear()
5707 dlna_player.update_state(signal_event=False)
5708
5709 controller._players = {
5710 "ap_1": ap1,
5711 "ap_2": ap2,
5712 "dlna_1": dlna_player,
5713 "sonos_1": sonos_player,
5714 }
5715 ap1.set_initialized()
5716 ap2.set_initialized()
5717 dlna_player.set_initialized()
5718 sonos_player.set_initialized()
5719
5720 # Call _try_link_protocols_to_native for the Sonos player
5721 # It should link ap1 and dlna but NOT ap2 (duplicate airplay domain)
5722 controller._try_link_protocols_to_native(sonos_player)
5723
5724 # First AirPlay should be linked
5725 assert ap1.protocol_parent_id == "sonos_1"
5726 # DLNA should be linked (different domain)
5727 assert dlna_player.protocol_parent_id == "sonos_1"
5728 # Second AirPlay should NOT be linked (duplicate domain)
5729 assert ap2.protocol_parent_id is None
5730 assert len(sonos_player.linked_output_protocols) == 2
5731
5732 def test_normal_multi_protocol_device_still_works(self, mock_mass: MagicMock) -> None:
5733 """Test that a device with AirPlay+DLNA (different protocols) still links correctly."""
5734 controller = PlayerController(mock_mass)
5735
5736 # Config.get returns {} for CONF_PLAYERS dict lookups
5737 mock_mass.config.get = MagicMock(side_effect=lambda _key, default=None: default or {})
5738
5739 sonos_provider = MockProvider("sonos")
5740 sonos_player = MockPlayer(
5741 sonos_provider,
5742 "sonos_1",
5743 "Sonos Speaker",
5744 player_type=PlayerType.PLAYER,
5745 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5746 )
5747
5748 airplay_provider = MockProvider("airplay")
5749 ap = MockPlayer(
5750 airplay_provider,
5751 "ap_1",
5752 "AirPlay",
5753 player_type=PlayerType.PROTOCOL,
5754 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5755 )
5756
5757 dlna_provider = MockProvider("dlna")
5758 dlna = MockPlayer(
5759 dlna_provider,
5760 "dlna_1",
5761 "DLNA",
5762 player_type=PlayerType.PROTOCOL,
5763 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5764 )
5765
5766 ap._attr_available = True
5767 ap._cache.clear()
5768 ap.update_state(signal_event=False)
5769 dlna._attr_available = True
5770 dlna._cache.clear()
5771 dlna.update_state(signal_event=False)
5772
5773 controller._players = {
5774 "sonos_1": sonos_player,
5775 "ap_1": ap,
5776 "dlna_1": dlna,
5777 }
5778 ap.set_initialized()
5779 dlna.set_initialized()
5780 sonos_player.set_initialized()
5781
5782 # Link both protocols
5783 controller._try_link_protocols_to_native(sonos_player)
5784
5785 assert ap.protocol_parent_id == "sonos_1"
5786 assert dlna.protocol_parent_id == "sonos_1"
5787 assert len(sonos_player.linked_output_protocols) == 2
5788
5789 def test_cached_parent_restore_refuses_duplicate_domain(self, mock_mass: MagicMock) -> None:
5790 """Test that restoring a cached parent is refused when domain already has active link."""
5791 controller = PlayerController(mock_mass)
5792
5793 sonos_provider = MockProvider("sonos")
5794 sonos_player = MockPlayer(
5795 sonos_provider,
5796 "sonos_1",
5797 "Sonos Speaker",
5798 player_type=PlayerType.PLAYER,
5799 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5800 )
5801
5802 airplay_provider = MockProvider("airplay")
5803 ap1 = MockPlayer(
5804 airplay_provider,
5805 "ap_1",
5806 "AirPlay 1",
5807 player_type=PlayerType.PROTOCOL,
5808 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5809 )
5810 ap2 = MockPlayer(
5811 airplay_provider,
5812 "ap_2",
5813 "AirPlay 2",
5814 player_type=PlayerType.PROTOCOL,
5815 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
5816 )
5817
5818 ap1._attr_available = True
5819 ap1._cache.clear()
5820 ap1.update_state(signal_event=False)
5821 ap2._attr_available = True
5822 ap2._cache.clear()
5823 ap2.update_state(signal_event=False)
5824
5825 controller._players = {
5826 "sonos_1": sonos_player,
5827 "ap_1": ap1,
5828 "ap_2": ap2,
5829 }
5830 ap1.set_initialized()
5831 ap2.set_initialized()
5832 sonos_player.set_initialized()
5833
5834 # Link first AirPlay
5835 controller._add_protocol_link(sonos_player, ap1, "airplay")
5836 assert ap1.protocol_parent_id == "sonos_1"
5837
5838 # Simulate ap2 having a cached parent from previous session
5839 with (
5840 patch.object(
5841 controller,
5842 "_get_cached_protocol_parent_id",
5843 return_value="sonos_1",
5844 ),
5845 patch.object(controller, "_schedule_protocol_evaluation") as mock_schedule,
5846 ):
5847 controller._try_link_protocol_to_native(ap2)
5848
5849 # ap2 should NOT have been linked (domain already active on sonos_1)
5850 assert ap2.protocol_parent_id is None
5851 # ap2 should be scheduled for delayed evaluation
5852 mock_schedule.assert_called_once_with(ap2)
5853
5854
5855class TestUniversalPlayerMerging:
5856 """Tests for merging universal players when identifiers overlap."""
5857
5858 def test_merge_universal_players_on_identifier_copy(self, mock_mass: MagicMock) -> None:
5859 """
5860 Test that two universal players merge when they share a MAC after identifier copy.
5861
5862 Simulates the Edifier scenario: DLNA creates a UUID-based universal player,
5863 AirPlay creates a MAC-based universal player. When ARP enrichment adds the
5864 real MAC to the DLNA player and it's copied to the DLNA universal player,
5865 the two universal players should merge because they now share the same MAC.
5866 """
5867 controller = PlayerController(mock_mass)
5868 up_provider = create_mock_universal_provider(mock_mass)
5869
5870 # Universal player 1: from DLNA (UUID-based, no MAC initially)
5871 up1 = UniversalPlayer(
5872 provider=up_provider,
5873 player_id="upf15fff97f002",
5874 name="Speaker Liv",
5875 device_info=DeviceInfo(model="DLNA Speaker", manufacturer="Edifier"),
5876 protocol_player_ids=["dlna_uuid_1"],
5877 )
5878 up1._attr_device_info.add_identifier(
5879 IdentifierType.UUID, "FF97F002-783E-6505-6579-F15FFF97F002"
5880 )
5881 up1._cache.clear()
5882 up1.update_state(signal_event=False)
5883 up1.set_initialized()
5884
5885 # Universal player 2: from AirPlay (MAC-based)
5886 up2 = UniversalPlayer(
5887 provider=up_provider,
5888 player_id="up50411c2f00ee",
5889 name="Speaker Liv",
5890 device_info=DeviceInfo(model="AirPlay Speaker", manufacturer="Edifier"),
5891 protocol_player_ids=["ap_1", "spb_1"],
5892 )
5893 up2._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "50:41:1C:2F:00:EE")
5894 up2._attr_device_info.add_identifier(IdentifierType.AIRPLAY_ID, "52:41:1C:2F:00:EE")
5895 up2._cache.clear()
5896 up2.update_state(signal_event=False)
5897 up2.set_initialized()
5898
5899 # Create mock DLNA protocol player (has MAC from ARP enrichment)
5900 dlna_provider = MockProvider("dlna", mass=mock_mass)
5901 dlna_player = MockPlayer(
5902 dlna_provider,
5903 "dlna_uuid_1",
5904 "Speaker Liv DLNA",
5905 player_type=PlayerType.PROTOCOL,
5906 identifiers={
5907 IdentifierType.UUID: "FF97F002-783E-6505-6579-F15FFF97F002",
5908 IdentifierType.MAC_ADDRESS: "50:41:1C:2F:00:EE", # From ARP
5909 IdentifierType.IP_ADDRESS: "192.168.1.80",
5910 },
5911 )
5912 dlna_player.set_initialized()
5913
5914 # Create mock AirPlay protocol player
5915 airplay_provider = MockProvider("airplay", mass=mock_mass)
5916 ap_player = MockPlayer(
5917 airplay_provider,
5918 "ap_1",
5919 "Speaker Liv AirPlay",
5920 player_type=PlayerType.PROTOCOL,
5921 identifiers={
5922 IdentifierType.MAC_ADDRESS: "50:41:1C:2F:00:EE",
5923 IdentifierType.AIRPLAY_ID: "52:41:1C:2F:00:EE",
5924 },
5925 )
5926 ap_player.set_initialized()
5927
5928 # Link protocols to their respective universal players
5929 controller._players = {
5930 "upf15fff97f002": up1,
5931 "up50411c2f00ee": up2,
5932 "dlna_uuid_1": dlna_player,
5933 "ap_1": ap_player,
5934 }
5935
5936 # Link DLNA to up1
5937 controller._add_protocol_link(up1, dlna_player, "dlna")
5938 assert dlna_player.protocol_parent_id == "upf15fff97f002"
5939
5940 # Link AirPlay to up2
5941 controller._add_protocol_link(up2, ap_player, "airplay")
5942 assert ap_player.protocol_parent_id == "up50411c2f00ee"
5943
5944 # Now simulate what happens when DLNA player copies identifiers to up1
5945 # (this happens in _try_restore_cached_parent or _try_link_to_existing_player)
5946 for conn_type, value in dlna_player.device_info.identifiers.items():
5947 up1.device_info.add_identifier(conn_type, value)
5948
5949 # up1 now has MAC 50:41:1C:2F:00:EE which matches up2
5950 assert up1.device_info.identifiers.get(IdentifierType.MAC_ADDRESS) == "50:41:1C:2F:00:EE"
5951
5952 # Call merge check
5953 controller._check_merge_universal_players(up1)
5954
5955 # Both UPs have one linked protocol -> equal-count merge falls through to
5956 # the deterministic tiebreaker on player_id. "up50411c2f00ee" (up2) is
5957 # lex-smaller than "upf15fff97f002" (up1), so up2 absorbs up1.
5958
5959 # up2 (lex-smaller player_id) should have absorbed up1's DLNA link
5960 protocol_domains = {link.protocol_domain for link in up2.linked_output_protocols}
5961 assert "dlna" in protocol_domains
5962 assert "airplay" in protocol_domains
5963
5964 # up1 should have no more protocol links
5965 assert len(up1.linked_output_protocols) == 0
5966
5967 # DLNA player should now be linked to up2 (was on up1 before merge)
5968 assert dlna_player.protocol_parent_id == "up50411c2f00ee"
5969
5970 # AirPlay player should still be linked to up2
5971 assert ap_player.protocol_parent_id == "up50411c2f00ee"
5972
5973 # up2 should have protocol player IDs from both
5974 assert "dlna_uuid_1" in up2._protocol_player_ids
5975 assert "ap_1" in up2._protocol_player_ids
5976
5977 # Unregister should have been called for up1
5978 mock_mass.create_task.assert_called()
5979
5980 def test_no_merge_when_identifiers_dont_match(self, mock_mass: MagicMock) -> None:
5981 """Test that universal players are not merged when identifiers don't overlap."""
5982 controller = PlayerController(mock_mass)
5983 up_provider = create_mock_universal_provider(mock_mass)
5984
5985 up1 = UniversalPlayer(
5986 provider=up_provider,
5987 player_id="up_1",
5988 name="Speaker A",
5989 device_info=DeviceInfo(model="Model A", manufacturer="Maker A"),
5990 protocol_player_ids=["dlna_1"],
5991 )
5992 up1._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:01")
5993 up1._cache.clear()
5994 up1.update_state(signal_event=False)
5995 up1.set_initialized()
5996
5997 up2 = UniversalPlayer(
5998 provider=up_provider,
5999 player_id="up_2",
6000 name="Speaker B",
6001 device_info=DeviceInfo(model="Model B", manufacturer="Maker B"),
6002 protocol_player_ids=["ap_1"],
6003 )
6004 up2._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:02")
6005 up2._cache.clear()
6006 up2.update_state(signal_event=False)
6007 up2.set_initialized()
6008
6009 controller._players = {"up_1": up1, "up_2": up2}
6010
6011 # Call merge - should do nothing since MACs are different
6012 controller._check_merge_universal_players(up1)
6013
6014 # Both players should remain untouched
6015 assert "up_1" in controller._players
6016 assert "up_2" in controller._players
6017
6018 def test_merge_keeps_player_with_more_protocols(self, mock_mass: MagicMock) -> None:
6019 """Test that of two equally old universal players, the one with more links wins."""
6020 controller = PlayerController(mock_mass)
6021 up_provider = create_mock_universal_provider(mock_mass)
6022
6023 # up1 has only 1 protocol link (DLNA)
6024 up1 = UniversalPlayer(
6025 provider=up_provider,
6026 player_id="up_small",
6027 name="Small Player",
6028 device_info=DeviceInfo(model="Test", manufacturer="Test"),
6029 protocol_player_ids=["dlna_1"],
6030 )
6031 up1._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
6032 up1._cache.clear()
6033 up1.update_state(signal_event=False)
6034 up1.set_initialized()
6035
6036 # up2 has 2 protocol links (AirPlay + Sendspin)
6037 up2 = UniversalPlayer(
6038 provider=up_provider,
6039 player_id="up_big",
6040 name="Big Player",
6041 device_info=DeviceInfo(model="Test", manufacturer="Test"),
6042 protocol_player_ids=["ap_1", "spb_1"],
6043 )
6044 up2._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
6045 up2._cache.clear()
6046 up2.update_state(signal_event=False)
6047 up2.set_initialized()
6048
6049 # Create protocol players
6050 dlna_provider = MockProvider("dlna", mass=mock_mass)
6051 dlna_player = MockPlayer(
6052 dlna_provider,
6053 "dlna_1",
6054 "DLNA",
6055 player_type=PlayerType.PROTOCOL,
6056 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
6057 )
6058 dlna_player.set_initialized()
6059
6060 airplay_provider = MockProvider("airplay", mass=mock_mass)
6061 ap_player = MockPlayer(
6062 airplay_provider,
6063 "ap_1",
6064 "AirPlay",
6065 player_type=PlayerType.PROTOCOL,
6066 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
6067 )
6068 ap_player.set_initialized()
6069
6070 sendspin_provider = MockProvider("sendspin", mass=mock_mass)
6071 spb_player = MockPlayer(
6072 sendspin_provider,
6073 "spb_1",
6074 "Sendspin",
6075 player_type=PlayerType.PROTOCOL,
6076 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
6077 )
6078 spb_player.set_initialized()
6079
6080 controller._players = {
6081 "up_small": up1,
6082 "up_big": up2,
6083 "dlna_1": dlna_player,
6084 "ap_1": ap_player,
6085 "spb_1": spb_player,
6086 }
6087
6088 # Link DLNA to small, AirPlay+Sendspin to big
6089 controller._add_protocol_link(up1, dlna_player, "dlna")
6090 controller._add_protocol_link(up2, ap_player, "airplay")
6091 controller._add_protocol_link(up2, spb_player, "sendspin")
6092
6093 # Merge from the small player's perspective
6094 controller._check_merge_universal_players(up1)
6095
6096 # up2 (bigger) should have absorbed up1's DLNA link
6097 protocol_domains = {link.protocol_domain for link in up2.linked_output_protocols}
6098 assert "airplay" in protocol_domains
6099 assert "sendspin" in protocol_domains
6100 assert "dlna" in protocol_domains
6101
6102 # DLNA player should now point to up_big
6103 assert dlna_player.protocol_parent_id == "up_big"
6104
6105 # up1 should have no more links
6106 assert len(up1.linked_output_protocols) == 0
6107
6108 def test_merge_keeps_the_older_player_with_fewer_protocols(self, mock_mass: MagicMock) -> None:
6109 """
6110 The oldest universal player wins even when it serves fewer protocols.
6111
6112 Its player id is the one API consumers have been bound to the longest, and the
6113 links of the absorbed player move over anyway. A player stored before ids were
6114 minted has no creation moment at all, which must count as the oldest of the two.
6115 """
6116 controller = PlayerController(mock_mass)
6117 up_provider = create_mock_universal_provider(mock_mass)
6118 _wire_nested_config(
6119 mock_mass,
6120 {
6121 CONF_PLAYERS: {
6122 # the established player, from before player ids were minted
6123 "up_old": {"player_id": "up_old", "enabled": True, "values": {}},
6124 "up_new": {
6125 "player_id": "up_new",
6126 "enabled": True,
6127 "values": {CONF_CREATED_AT: 9000},
6128 },
6129 }
6130 },
6131 )
6132
6133 players: dict[str, UniversalPlayer] = {}
6134 for player_id, protocol_ids in (("up_old", ["dlna_1"]), ("up_new", ["ap_1", "spb_1"])):
6135 player = UniversalPlayer(
6136 provider=up_provider,
6137 player_id=player_id,
6138 name=player_id,
6139 device_info=DeviceInfo(model="Test", manufacturer="Test"),
6140 protocol_player_ids=protocol_ids,
6141 )
6142 player._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
6143 player._cache.clear()
6144 player.update_state(signal_event=False)
6145 player.set_initialized()
6146 players[player_id] = player
6147
6148 protocol_players: dict[str, MockPlayer] = {}
6149 for protocol_id, domain in (("dlna_1", "dlna"), ("ap_1", "airplay"), ("spb_1", "sendspin")):
6150 protocol_player = MockPlayer(
6151 MockProvider(domain, mass=mock_mass),
6152 protocol_id,
6153 domain,
6154 player_type=PlayerType.PROTOCOL,
6155 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
6156 )
6157 protocol_player.set_initialized()
6158 protocol_players[protocol_id] = protocol_player
6159
6160 controller._players = {**players, **protocol_players}
6161 controller._add_protocol_link(players["up_old"], protocol_players["dlna_1"], "dlna")
6162 controller._add_protocol_link(players["up_new"], protocol_players["ap_1"], "airplay")
6163 controller._add_protocol_link(players["up_new"], protocol_players["spb_1"], "sendspin")
6164
6165 controller._check_merge_universal_players(players["up_new"])
6166
6167 domains = {link.protocol_domain for link in players["up_old"].linked_output_protocols}
6168 assert domains == {"dlna", "airplay", "sendspin"}
6169 assert protocol_players["ap_1"].protocol_parent_id == "up_old"
6170 assert len(players["up_new"].linked_output_protocols) == 0
6171
6172 @staticmethod
6173 def _setup_merge_tiebreak(
6174 mock_mass: MagicMock, created_at: dict[str, int]
6175 ) -> tuple[PlayerController, UniversalPlayer, UniversalPlayer, MockPlayer, MockPlayer]:
6176 """
6177 Set up two universal players of one device, each with a single protocol link.
6178
6179 :param mock_mass: The mocked MusicAssistant instance to wire.
6180 :param created_at: Stored creation timestamp per universal player id.
6181 :return: Tuple of (controller, up_aaa, up_bbb, its DLNA player, its AirPlay player).
6182 """
6183 controller = PlayerController(mock_mass)
6184 up_provider = create_mock_universal_provider(mock_mass)
6185 _wire_nested_config(
6186 mock_mass,
6187 {
6188 CONF_PLAYERS: {
6189 player_id: {
6190 "player_id": player_id,
6191 "provider": "universal_player",
6192 "enabled": True,
6193 "values": {CONF_CREATED_AT: timestamp},
6194 }
6195 for player_id, timestamp in created_at.items()
6196 }
6197 },
6198 )
6199
6200 # up_a: lex-smaller player_id, one protocol link (DLNA)
6201 up_a = UniversalPlayer(
6202 provider=up_provider,
6203 player_id="up_aaa",
6204 name="Player A",
6205 device_info=DeviceInfo(model="Test", manufacturer="Test"),
6206 protocol_player_ids=["dlna_1"],
6207 )
6208 up_a._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
6209 up_a._cache.clear()
6210 up_a.update_state(signal_event=False)
6211 up_a.set_initialized()
6212
6213 # up_b: lex-larger player_id, one protocol link (AirPlay)
6214 up_b = UniversalPlayer(
6215 provider=up_provider,
6216 player_id="up_bbb",
6217 name="Player B",
6218 device_info=DeviceInfo(model="Test", manufacturer="Test"),
6219 protocol_player_ids=["ap_1"],
6220 )
6221 up_b._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
6222 up_b._cache.clear()
6223 up_b.update_state(signal_event=False)
6224 up_b.set_initialized()
6225
6226 # Create protocol players
6227 dlna_provider = MockProvider("dlna", mass=mock_mass)
6228 dlna_player = MockPlayer(
6229 dlna_provider,
6230 "dlna_1",
6231 "DLNA",
6232 player_type=PlayerType.PROTOCOL,
6233 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
6234 )
6235 dlna_player.set_initialized()
6236
6237 airplay_provider = MockProvider("airplay", mass=mock_mass)
6238 ap_player = MockPlayer(
6239 airplay_provider,
6240 "ap_1",
6241 "AirPlay",
6242 player_type=PlayerType.PROTOCOL,
6243 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
6244 )
6245 ap_player.set_initialized()
6246
6247 controller._players = {
6248 "up_aaa": up_a,
6249 "up_bbb": up_b,
6250 "dlna_1": dlna_player,
6251 "ap_1": ap_player,
6252 }
6253
6254 controller._add_protocol_link(up_a, dlna_player, "dlna")
6255 controller._add_protocol_link(up_b, ap_player, "airplay")
6256
6257 return controller, up_a, up_b, dlna_player, ap_player
6258
6259 def test_merge_deterministic_tiebreaker_on_equal_link_counts(
6260 self, mock_mass: MagicMock
6261 ) -> None:
6262 """Test that merges of equally old players resolve to the lex-smaller player_id."""
6263 controller, up_a, up_b, _, ap_player = self._setup_merge_tiebreak(
6264 mock_mass, {"up_aaa": 1000, "up_bbb": 1000}
6265 )
6266
6267 # Call merge from the lex-larger side. Under the old non-deterministic
6268 # behavior the caller (up_b) would have won. With the tiebreaker the
6269 # lex-smaller player_id (up_a) wins regardless of which side calls.
6270 controller._check_merge_universal_players(up_b)
6271
6272 # up_a (lex-smaller) should have absorbed up_b's AirPlay link
6273 protocol_domains = {link.protocol_domain for link in up_a.linked_output_protocols}
6274 assert protocol_domains == {"dlna", "airplay"}
6275
6276 # AirPlay player should now point to up_aaa
6277 assert ap_player.protocol_parent_id == "up_aaa"
6278
6279 # up_b should have no more links
6280 assert len(up_b.linked_output_protocols) == 0
6281
6282 def test_merge_tiebreaker_prefers_the_older_universal_player(
6283 self, mock_mass: MagicMock
6284 ) -> None:
6285 """Test that the player that has been around longest absorbs the other one."""
6286 controller, up_a, up_b, dlna_player, _ = self._setup_merge_tiebreak(
6287 mock_mass, {"up_aaa": 2000, "up_bbb": 1000}
6288 )
6289
6290 controller._check_merge_universal_players(up_a)
6291
6292 # up_b is older, so it wins despite its lex-larger player_id
6293 protocol_domains = {link.protocol_domain for link in up_b.linked_output_protocols}
6294 assert protocol_domains == {"dlna", "airplay"}
6295 assert dlna_player.protocol_parent_id == "up_bbb"
6296 assert len(up_a.linked_output_protocols) == 0
6297
6298 async def test_merge_preserves_moved_protocols_during_parent_cleanup(
6299 self, mock_mass: MagicMock
6300 ) -> None:
6301 """Moved protocol ownership must survive the removed parent's permanent cleanup."""
6302 controller = PlayerController(mock_mass)
6303 up_provider = create_mock_universal_provider(mock_mass)
6304
6305 config_store: dict[str, object] = {
6306 "players/up_keep": {"enabled": True},
6307 "players/up_remove": {"enabled": True},
6308 "players/ap_keep": {"enabled": True},
6309 "players/dlna_live": {"enabled": True},
6310 "players/dlna_cached": {
6311 "enabled": True,
6312 "provider": "dlna--test",
6313 "player_type": "protocol",
6314 "values": {"protocol_parent_id": "up_remove"},
6315 },
6316 }
6317
6318 def config_get(key: str, default: object = None) -> object:
6319 return config_store.get(key, default)
6320
6321 def config_set(key: str, value: object) -> None:
6322 config_store[key] = value
6323
6324 def config_remove(key: str) -> None:
6325 config_store.pop(key, None)
6326
6327 scheduled_tasks: list[Awaitable[object]] = []
6328
6329 def capture_task(task: Awaitable[object], *_args: Any, **_kwargs: Any) -> None:
6330 scheduled_tasks.append(task)
6331
6332 mock_mass.config.get = MagicMock(side_effect=config_get)
6333 mock_mass.config.set = MagicMock(side_effect=config_set)
6334 mock_mass.config.remove = MagicMock(side_effect=config_remove)
6335 mock_mass.players = controller
6336 mock_mass.player_queues = MagicMock()
6337 mock_mass.call_later = MagicMock()
6338 mock_mass.loop = MagicMock()
6339 mock_mass.create_task = MagicMock(side_effect=capture_task)
6340
6341 keep = UniversalPlayer(
6342 provider=up_provider,
6343 player_id="up_keep",
6344 name="Keep",
6345 device_info=DeviceInfo(model="Test", manufacturer="Test"),
6346 protocol_player_ids=["ap_keep"],
6347 )
6348 keep._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
6349 keep._cache.clear()
6350 keep.update_state(signal_event=False)
6351 keep.set_initialized()
6352
6353 remove = UniversalPlayer(
6354 provider=up_provider,
6355 player_id="up_remove",
6356 name="Remove",
6357 device_info=DeviceInfo(model="Test", manufacturer="Test"),
6358 protocol_player_ids=["dlna_live", "dlna_cached"],
6359 )
6360 remove._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
6361 remove._cache.clear()
6362 remove.update_state(signal_event=False)
6363 remove.set_initialized()
6364
6365 airplay_provider = MockProvider("airplay", mass=mock_mass)
6366 ap_keep = MockPlayer(
6367 airplay_provider,
6368 "ap_keep",
6369 "AirPlay",
6370 player_type=PlayerType.PROTOCOL,
6371 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
6372 )
6373 ap_keep.set_initialized()
6374
6375 dlna_provider = MockProvider("dlna", mass=mock_mass)
6376 dlna_live = MockPlayer(
6377 dlna_provider,
6378 "dlna_live",
6379 "DLNA",
6380 player_type=PlayerType.PROTOCOL,
6381 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
6382 )
6383 dlna_live.set_initialized()
6384
6385 controller._players = {
6386 "up_keep": keep,
6387 "up_remove": remove,
6388 "ap_keep": ap_keep,
6389 "dlna_live": dlna_live,
6390 }
6391
6392 controller._add_protocol_link(keep, ap_keep, "airplay")
6393 controller._add_protocol_link(remove, dlna_live, "dlna")
6394
6395 with patch.object(controller, "_save_universal_player_data"):
6396 controller._check_merge_universal_players(keep)
6397
6398 assert dlna_live.protocol_parent_id == "up_keep"
6399 assert config_store["players/dlna_cached/values/protocol_parent_id"] == "up_keep"
6400 unregister_tasks = [t for t in scheduled_tasks if "unregister" in repr(t)]
6401 assert len(unregister_tasks) == 1
6402
6403 await unregister_tasks[0]
6404
6405 assert "up_remove" not in controller._players
6406 assert dlna_live.protocol_parent_id == "up_keep"
6407 assert "dlna_cached" in keep._protocol_player_ids
6408 assert config_store["players/dlna_cached/values/protocol_parent_id"] == "up_keep"
6409
6410 def test_no_merge_same_domain_protocols_on_same_ip(self, mock_mass: MagicMock) -> None:
6411 """
6412 Test that UPs with same-domain protocols on the same IP are NOT merged.
6413
6414 Scenario: 3 squeezelite instances on the same VM (same IP, different real MACs).
6415 Each gets its own universal player. The merge check must NOT merge them,
6416 because merging would combine protocols from the same domain.
6417
6418 Reproduces: https://github.com/music-assistant/support/issues/5266
6419 """
6420 controller = PlayerController(mock_mass)
6421 up_provider = create_mock_universal_provider(mock_mass)
6422
6423 # Create 3 universal players, each with one squeezelite protocol
6424 squeeze_provider = MockProvider("squeezelite", mass=mock_mass)
6425 ups = []
6426 protocols = []
6427 for i in range(1, 4):
6428 mac = f"00:00:00:00:00:{i:02X}"
6429 up = UniversalPlayer(
6430 provider=up_provider,
6431 player_id=f"up00000000000{i}",
6432 name=f"Zone {i}",
6433 device_info=DeviceInfo(model="Squeezelite", manufacturer="Test"),
6434 protocol_player_ids=[mac],
6435 )
6436 up._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, mac)
6437 up._attr_device_info.add_identifier(IdentifierType.IP_ADDRESS, "192.168.1.50")
6438 up._cache.clear()
6439 up.update_state(signal_event=False)
6440 up.set_initialized()
6441 ups.append(up)
6442
6443 proto = MockPlayer(
6444 squeeze_provider,
6445 mac,
6446 f"squeezeplay: {mac}",
6447 player_type=PlayerType.PROTOCOL,
6448 identifiers={
6449 IdentifierType.MAC_ADDRESS: mac,
6450 IdentifierType.IP_ADDRESS: "192.168.1.50",
6451 },
6452 )
6453 proto.set_initialized()
6454 protocols.append(proto)
6455
6456 controller._players = {}
6457 for up in ups:
6458 controller._players[up.player_id] = up
6459 for proto in protocols:
6460 controller._players[proto.player_id] = proto
6461
6462 # Link each protocol to its UP
6463 for up, proto in zip(ups, protocols, strict=True):
6464 controller._add_protocol_link(up, proto, "squeezelite")
6465
6466 # Verify initial state: each protocol linked to its own UP
6467 for up, proto in zip(ups, protocols, strict=True):
6468 assert proto.protocol_parent_id == up.player_id
6469
6470 # Now run merge check on each UP - none should merge
6471 with patch.object(controller, "_save_universal_player_data"):
6472 for up in ups:
6473 controller._check_merge_universal_players(up)
6474
6475 # All 3 UPs must still exist with their original protocol links
6476 for up, proto in zip(ups, protocols, strict=True):
6477 assert proto.protocol_parent_id == up.player_id, (
6478 f"Protocol {proto.player_id} should still be linked to {up.player_id}, "
6479 f"but is linked to {proto.protocol_parent_id}"
6480 )
6481 assert len(up.linked_output_protocols) == 1, (
6482 f"UP {up.player_id} should have exactly 1 protocol, "
6483 f"but has {len(up.linked_output_protocols)}"
6484 )
6485
6486 @staticmethod
6487 def _setup_merge_scenario(
6488 mock_mass: MagicMock, config_store: dict[str, Any]
6489 ) -> tuple[PlayerController, UniversalPlayer, list[Awaitable[object]]]:
6490 """
6491 Wire a merge scenario for the config carry-over tests.
6492
6493 Universal players 'up_keep' and 'up_remove' share a MAC; with equal
6494 link counts the deterministic tiebreaker keeps 'up_keep' and removes
6495 'up_remove', so 'up_remove' is the loser whose config is carried over.
6496 """
6497 controller = PlayerController(mock_mass)
6498 up_provider = create_mock_universal_provider(mock_mass)
6499
6500 def config_get(key: str, default: object = None) -> object:
6501 return config_store.get(key, default)
6502
6503 def config_set(key: str, value: object) -> None:
6504 config_store[key] = value
6505
6506 def config_remove(key: str) -> None:
6507 config_store.pop(key, None)
6508
6509 scheduled_tasks: list[Awaitable[object]] = []
6510
6511 def capture_task(task: Awaitable[object], *_args: Any, **_kwargs: Any) -> None:
6512 scheduled_tasks.append(task)
6513
6514 mock_mass.config.get = MagicMock(side_effect=config_get)
6515 mock_mass.config.set = MagicMock(side_effect=config_set)
6516 mock_mass.config.remove = MagicMock(side_effect=config_remove)
6517 mock_mass.players = controller
6518 mock_mass.player_queues = MagicMock()
6519 mock_mass.call_later = MagicMock()
6520 mock_mass.loop = MagicMock()
6521 mock_mass.create_task = MagicMock(side_effect=capture_task)
6522
6523 keep = UniversalPlayer(
6524 provider=up_provider,
6525 player_id="up_keep",
6526 name="Keep (Universal)",
6527 device_info=DeviceInfo(model="Test", manufacturer="Test"),
6528 protocol_player_ids=["ap_keep"],
6529 )
6530 keep._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
6531 keep._cache.clear()
6532 keep.update_state(signal_event=False)
6533 keep.set_initialized()
6534
6535 remove = UniversalPlayer(
6536 provider=up_provider,
6537 player_id="up_remove",
6538 name="Remove (Universal)",
6539 device_info=DeviceInfo(model="Test", manufacturer="Test"),
6540 protocol_player_ids=["dlna_live"],
6541 )
6542 remove._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
6543 remove._cache.clear()
6544 remove.update_state(signal_event=False)
6545 remove.set_initialized()
6546
6547 ap_keep = MockPlayer(
6548 MockProvider("airplay", mass=mock_mass),
6549 "ap_keep",
6550 "AirPlay",
6551 player_type=PlayerType.PROTOCOL,
6552 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
6553 )
6554 ap_keep.set_initialized()
6555
6556 dlna_live = MockPlayer(
6557 MockProvider("dlna", mass=mock_mass),
6558 "dlna_live",
6559 "DLNA",
6560 player_type=PlayerType.PROTOCOL,
6561 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
6562 )
6563 dlna_live.set_initialized()
6564
6565 controller._players = {
6566 "up_keep": keep,
6567 "up_remove": remove,
6568 "ap_keep": ap_keep,
6569 "dlna_live": dlna_live,
6570 }
6571 controller._add_protocol_link(keep, ap_keep, "airplay")
6572 controller._add_protocol_link(remove, dlna_live, "dlna")
6573 return controller, keep, scheduled_tasks
6574
6575 async def test_merge_carries_over_universal_config(self, mock_mass: MagicMock) -> None:
6576 """Merge migrates name, values, DSP and queue settings from loser to keeper."""
6577 config_store: dict[str, Any] = {
6578 "players/up_keep": {
6579 "enabled": True,
6580 "name": "Keep (Universal)",
6581 "default_name": "Keep (Universal)",
6582 "values": {"volume_control": "keep_ctrl"},
6583 },
6584 "players/up_remove": {
6585 "enabled": True,
6586 "name": "Living Room",
6587 "default_name": "Remove (Universal)",
6588 "values": {
6589 "hide_in_ui": True,
6590 "volume_control": "remove_ctrl",
6591 "device_info": {"model": "Test", "manufacturer": "Test"},
6592 },
6593 },
6594 "players/ap_keep": {"enabled": True},
6595 "players/dlna_live": {"enabled": True},
6596 "player_dsp/up_remove": {"enabled": True, "filters": []},
6597 "player_queues/up_remove": {
6598 "queue_id": "up_remove",
6599 "values": {"crossfade_duration": 5},
6600 },
6601 }
6602 controller, keep, scheduled_tasks = self._setup_merge_scenario(mock_mass, config_store)
6603
6604 with patch.object(controller, "_save_universal_player_data"):
6605 controller._check_merge_universal_players(keep)
6606
6607 # the custom display name and non-conflicting values moved onto the keeper
6608 assert config_store["players/up_keep/name"] == "Living Room"
6609 assert config_store["players/up_keep/values/hide_in_ui"] is True
6610 # values the keeper has explicitly set are not overwritten
6611 assert "players/up_keep/values/volume_control" not in config_store
6612 # wrapper bookkeeping is not carried over
6613 assert "players/up_keep/values/device_info" not in config_store
6614 # DSP moved wholesale and queue settings moved and re-keyed onto the keeper
6615 assert config_store["player_dsp/up_keep"] == {"enabled": True, "filters": []}
6616 assert config_store["player_queues/up_keep"] == {
6617 "queue_id": "up_keep",
6618 "values": {"crossfade_duration": 5},
6619 }
6620 assert "player_queues/up_remove" not in config_store
6621 # the keeper's in-place config gets reloaded to apply the migrated values
6622 assert any("_reapply_player_config" in repr(t) for t in scheduled_tasks)
6623
6624 # and the losing universal player is still permanently removed
6625 unregister_tasks = [t for t in scheduled_tasks if "unregister" in repr(t)]
6626 assert len(unregister_tasks) == 1
6627 await unregister_tasks[0]
6628 assert "up_remove" not in controller._players
6629
6630 def test_merge_keeps_keeper_explicit_values(self, mock_mass: MagicMock) -> None:
6631 """Values explicitly set on the keeper win over the losing player's."""
6632 config_store: dict[str, Any] = {
6633 "players/up_keep": {
6634 "enabled": True,
6635 "name": "Kitchen",
6636 "default_name": "Keep (Universal)",
6637 "values": {"hide_in_ui": False},
6638 },
6639 "players/up_remove": {
6640 "enabled": True,
6641 "name": "Living Room",
6642 "default_name": "Remove (Universal)",
6643 "values": {"hide_in_ui": True, "flow_mode": True},
6644 },
6645 "players/ap_keep": {"enabled": True},
6646 "players/dlna_live": {"enabled": True},
6647 "player_dsp/up_keep": {"enabled": False, "filters": ["keep"]},
6648 "player_dsp/up_remove": {"enabled": True, "filters": ["remove"]},
6649 }
6650 controller, keep, _ = self._setup_merge_scenario(mock_mass, config_store)
6651
6652 with patch.object(controller, "_save_universal_player_data"):
6653 controller._check_merge_universal_players(keep)
6654
6655 # the keeper's own custom name and DSP config win
6656 assert "players/up_keep/name" not in config_store
6657 assert config_store["players/up_keep"]["name"] == "Kitchen"
6658 assert config_store["player_dsp/up_keep"] == {"enabled": False, "filters": ["keep"]}
6659 # the keeper's explicit value is not overwritten
6660 assert "players/up_keep/values/hide_in_ui" not in config_store
6661 # non-conflicting values still migrate
6662 assert config_store["players/up_keep/values/flow_mode"] is True
6663
6664 def test_merge_does_not_carry_over_the_creation_moment(self, mock_mass: MagicMock) -> None:
6665 """
6666 The absorbed player's creation moment stays behind.
6667
6668 It is bookkeeping of that wrapper alone; copying it onto the keeper would let a
6669 later merge discard the keeper's older - and therefore established - player id.
6670 """
6671 config_store: dict[str, Any] = {
6672 "players/up_keep": {
6673 "enabled": True,
6674 "name": "Keep (Universal)",
6675 "default_name": "Keep (Universal)",
6676 "values": {},
6677 },
6678 "players/up_remove": {
6679 "enabled": True,
6680 "name": "Remove (Universal)",
6681 "default_name": "Remove (Universal)",
6682 "values": {CONF_CREATED_AT: 5000},
6683 },
6684 "players/ap_keep": {"enabled": True},
6685 "players/dlna_live": {"enabled": True},
6686 }
6687 controller, keep, _ = self._setup_merge_scenario(mock_mass, config_store)
6688
6689 with patch.object(controller, "_save_universal_player_data"):
6690 controller._check_merge_universal_players(keep)
6691
6692 assert f"players/up_keep/values/{CONF_CREATED_AT}" not in config_store
6693 assert CONF_CREATED_AT not in config_store["players/up_keep"]["values"]
6694
6695 def test_merge_repoints_group_memberships(self, mock_mass: MagicMock) -> None:
6696 """Merge re-points group memberships from the removed wrapper to the keeper."""
6697 config_store: dict[str, Any] = {
6698 "players/up_keep": {
6699 "enabled": True,
6700 "name": "Keep (Universal)",
6701 "default_name": "Keep (Universal)",
6702 "values": {},
6703 },
6704 "players/up_remove": {
6705 "enabled": True,
6706 "name": "Remove (Universal)",
6707 "default_name": "Remove (Universal)",
6708 "values": {},
6709 },
6710 "players/ap_keep": {"enabled": True},
6711 "players/dlna_live": {"enabled": True},
6712 # nested players dict scanned by _update_group_memberships
6713 "players": {
6714 "group_1": {
6715 "enabled": True,
6716 "values": {
6717 "group_members": ["up_remove", "other"],
6718 "allowed_members": ["up_remove"],
6719 },
6720 },
6721 "group_2": {
6722 "enabled": True,
6723 # keeper already listed -> no duplicate after re-point
6724 "values": {"group_members": ["up_keep", "up_remove"]},
6725 },
6726 },
6727 }
6728 controller, keep, _ = self._setup_merge_scenario(mock_mass, config_store)
6729
6730 with patch.object(controller, "_save_universal_player_data"):
6731 controller._check_merge_universal_players(keep)
6732
6733 assert config_store["players/group_1/values/group_members"] == ["up_keep", "other"]
6734 assert config_store["players/group_1/values/allowed_members"] == ["up_keep"]
6735 # no duplicate when the keeper is already a member
6736 assert config_store["players/group_2/values/group_members"] == ["up_keep"]
6737
6738 async def test_merge_stops_playing_loser_before_unregister(self, mock_mass: MagicMock) -> None:
6739 """A playing losing wrapper is stopped before it is permanently removed."""
6740 config_store: dict[str, Any] = {
6741 "players/up_keep": {"enabled": True},
6742 "players/up_remove": {"enabled": True},
6743 "players/ap_keep": {"enabled": True},
6744 "players/dlna_live": {"enabled": True},
6745 }
6746 controller, keep, scheduled_tasks = self._setup_merge_scenario(mock_mass, config_store)
6747 controller._players["up_remove"]._attr_playback_state = PlaybackState.PLAYING
6748
6749 call_order: list[str] = []
6750 mock_mass.player_queues.stop = AsyncMock(
6751 side_effect=lambda *_a, **_k: call_order.append("stop")
6752 )
6753
6754 with patch.object(controller, "_save_universal_player_data"):
6755 controller._check_merge_universal_players(keep)
6756
6757 task = next(t for t in scheduled_tasks if "unregister" in repr(t))
6758
6759 def _record_unregister(*_a: Any, **_k: Any) -> None:
6760 call_order.append("unregister")
6761
6762 with patch.object(controller, "unregister", new=AsyncMock(side_effect=_record_unregister)):
6763 await task
6764
6765 assert call_order == ["stop", "unregister"]
6766 mock_mass.player_queues.stop.assert_awaited_once_with("up_remove")
6767
6768 async def test_merge_hands_the_user_filters_to_the_keeper(self, mock_mass: MagicMock) -> None:
6769 """The absorbed wrapper hands its access filter entries to the keeper."""
6770 config_store: dict[str, Any] = {
6771 "players/up_keep": {"enabled": True},
6772 "players/up_remove": {"enabled": True},
6773 "players/ap_keep": {"enabled": True},
6774 "players/dlna_live": {"enabled": True},
6775 }
6776 controller, keep, scheduled_tasks = self._setup_merge_scenario(mock_mass, config_store)
6777
6778 with patch.object(controller, "_save_universal_player_data"):
6779 controller._check_merge_universal_players(keep)
6780
6781 task = next(t for t in scheduled_tasks if "unregister" in repr(t))
6782 with patch.object(controller, "unregister", new=AsyncMock()) as mock_unregister:
6783 await task
6784
6785 mock_unregister.assert_awaited_once_with(
6786 "up_remove", permanent=True, replacement_player_id="up_keep"
6787 )
6788
6789 async def test_merge_idle_loser_not_stopped(self, mock_mass: MagicMock) -> None:
6790 """An idle losing wrapper is removed without a stop command."""
6791 config_store: dict[str, Any] = {
6792 "players/up_keep": {"enabled": True},
6793 "players/up_remove": {"enabled": True},
6794 "players/ap_keep": {"enabled": True},
6795 "players/dlna_live": {"enabled": True},
6796 }
6797 controller, keep, scheduled_tasks = self._setup_merge_scenario(mock_mass, config_store)
6798 mock_mass.player_queues.stop = AsyncMock()
6799
6800 with patch.object(controller, "_save_universal_player_data"):
6801 controller._check_merge_universal_players(keep)
6802
6803 task = next(t for t in scheduled_tasks if "unregister" in repr(t))
6804 await task
6805
6806 mock_mass.player_queues.stop.assert_not_awaited()
6807 assert "up_remove" not in controller._players
6808
6809
6810class TestUniversalPlayerReplacement:
6811 """Tests for replacing a universal player with a native player."""
6812
6813 @pytest.mark.parametrize(
6814 ("airplay_registered", "missing_protocol_id", "missing_domain", "missing_enabled"),
6815 [
6816 (True, "dlna_cached", "dlna", True),
6817 (True, "dlna_cached", "dlna", False),
6818 (False, "spb_cached", "sendspin", False),
6819 ],
6820 )
6821 async def test_replace_migrates_missing_cached_protocol_during_parent_cleanup(
6822 self,
6823 mock_mass: MagicMock,
6824 airplay_registered: bool,
6825 missing_protocol_id: str,
6826 missing_domain: str,
6827 missing_enabled: bool,
6828 ) -> None:
6829 """Missing cached protocol ownership must survive replacement and cleanup."""
6830 controller = PlayerController(mock_mass)
6831 up_provider = create_mock_universal_provider(mock_mass)
6832
6833 missing_values = {"protocol_parent_id": "up_old"}
6834 if missing_domain == "sendspin":
6835 missing_values[CONF_UNDERLYING_PLAYER_ID] = "ap_live"
6836 config_store: dict[str, Any] = {
6837 CONF_PLAYERS: {
6838 "sonos_1": {"enabled": True, "values": {}},
6839 "up_old": {"enabled": airplay_registered, "values": {}},
6840 "ap_live": {
6841 "enabled": airplay_registered,
6842 "provider": "airplay--test",
6843 "player_type": "protocol",
6844 "values": {"protocol_parent_id": "up_old"},
6845 },
6846 missing_protocol_id: {
6847 "enabled": missing_enabled,
6848 "provider": f"{missing_domain}--test",
6849 "player_type": "protocol",
6850 "values": missing_values,
6851 },
6852 }
6853 }
6854 _wire_nested_config(mock_mass, config_store)
6855
6856 scheduled_tasks: list[Awaitable[object]] = []
6857
6858 def capture_task(task: Awaitable[object], *_args: Any, **_kwargs: Any) -> None:
6859 scheduled_tasks.append(task)
6860
6861 mock_mass.players = controller
6862 mock_mass.player_queues = MagicMock()
6863 mock_mass.call_later = MagicMock()
6864 mock_mass.loop = MagicMock()
6865 mock_mass.create_task = MagicMock(side_effect=capture_task)
6866
6867 universal = UniversalPlayer(
6868 provider=up_provider,
6869 player_id="up_old",
6870 name="Old Universal",
6871 device_info=DeviceInfo(model="Test", manufacturer="Test"),
6872 protocol_player_ids=["ap_live", missing_protocol_id],
6873 )
6874 universal._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
6875 universal._cache.clear()
6876 universal.update_state(signal_event=False)
6877
6878 native_provider = MockProvider("sonos", mass=mock_mass)
6879 native = MockPlayer(
6880 native_provider,
6881 "sonos_1",
6882 "Sonos",
6883 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
6884 )
6885 native.set_initialized()
6886
6887 airplay_provider = MockProvider("airplay", mass=mock_mass)
6888 ap_live = MockPlayer(
6889 airplay_provider,
6890 "ap_live",
6891 "AirPlay",
6892 player_type=PlayerType.PROTOCOL,
6893 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
6894 )
6895 ap_live.set_initialized()
6896
6897 controller._players = {"up_old": universal, "sonos_1": native}
6898 if airplay_registered:
6899 controller._players["ap_live"] = ap_live
6900 controller._add_protocol_link(universal, ap_live, "airplay")
6901 else:
6902 universal.set_linked_output_protocols(
6903 [
6904 LinkedOutputProtocol(
6905 output_protocol_id="ap_live",
6906 protocol_domain="airplay",
6907 priority=10,
6908 )
6909 ]
6910 )
6911 universal.set_linked_output_protocols(
6912 [
6913 *universal.linked_output_protocols,
6914 LinkedOutputProtocol(
6915 output_protocol_id=missing_protocol_id,
6916 protocol_domain=missing_domain,
6917 priority=20,
6918 derived_from="ap_live" if missing_domain == "sendspin" else None,
6919 ),
6920 ]
6921 )
6922
6923 controller._check_replace_universal_player(native)
6924
6925 if airplay_registered:
6926 assert ap_live.protocol_parent_id == "sonos_1"
6927 else:
6928 assert (
6929 config_store[CONF_PLAYERS]["ap_live"]["values"][CONF_PROTOCOL_PARENT_ID]
6930 == "sonos_1"
6931 )
6932 assert set(config_store[CONF_PLAYERS]["sonos_1"]["values"]["linked_protocol_ids"]) == {
6933 "ap_live",
6934 missing_protocol_id,
6935 }
6936 assert (
6937 config_store[CONF_PLAYERS][missing_protocol_id]["values"][CONF_PROTOCOL_PARENT_ID]
6938 == "sonos_1"
6939 )
6940 unregister_tasks = [t for t in scheduled_tasks if "unregister" in repr(t)]
6941 assert len(unregister_tasks) == 1
6942
6943 await unregister_tasks[0]
6944
6945 assert "up_old" not in controller._players
6946 if airplay_registered:
6947 assert ap_live.protocol_parent_id == "sonos_1"
6948 else:
6949 assert (
6950 config_store[CONF_PLAYERS]["ap_live"]["values"][CONF_PROTOCOL_PARENT_ID]
6951 == "sonos_1"
6952 )
6953 assert (
6954 config_store[CONF_PLAYERS][missing_protocol_id]["values"][CONF_PROTOCOL_PARENT_ID]
6955 == "sonos_1"
6956 )
6957 assert set(config_store[CONF_PLAYERS]["sonos_1"]["values"]["linked_protocol_ids"]) == {
6958 "ap_live",
6959 missing_protocol_id,
6960 }
6961
6962 def test_replace_keeps_universal_when_all_links_refused(self, mock_mass: MagicMock) -> None:
6963 """
6964 Keep the universal player when no link could migrate.
6965
6966 If the native player already has an active link from the same protocol
6967 domain as every protocol on the universal player, each `_add_protocol_link`
6968 call refuses and leaves the protocol's parent unchanged. The universal player
6969 must NOT be permanently unregistered in that case, otherwise it disappears
6970 from the UI on restart.
6971 """
6972 controller = PlayerController(mock_mass)
6973 up_provider = create_mock_universal_provider(mock_mass)
6974
6975 config_store: dict[str, object] = {
6976 "players/cast_1": {"enabled": True},
6977 "players/up_old": {"enabled": True},
6978 "players/spb_old": {"enabled": True},
6979 "players/spb_new": {"enabled": True},
6980 }
6981
6982 def config_get(key: str, default: object = None) -> object:
6983 return config_store.get(key, default)
6984
6985 def config_set(key: str, value: object) -> None:
6986 config_store[key] = value
6987
6988 def config_remove(key: str) -> None:
6989 config_store.pop(key, None)
6990
6991 scheduled_tasks: list[Awaitable[object]] = []
6992
6993 def capture_task(task: Awaitable[object], *_args: Any, **_kwargs: Any) -> None:
6994 scheduled_tasks.append(task)
6995
6996 mock_mass.config.get = MagicMock(side_effect=config_get)
6997 mock_mass.config.set = MagicMock(side_effect=config_set)
6998 mock_mass.config.remove = MagicMock(side_effect=config_remove)
6999 mock_mass.players = controller
7000 mock_mass.player_queues = MagicMock()
7001 mock_mass.call_later = MagicMock()
7002 mock_mass.loop = MagicMock()
7003 mock_mass.create_task = MagicMock(side_effect=capture_task)
7004
7005 universal = UniversalPlayer(
7006 provider=up_provider,
7007 player_id="up_old",
7008 name="Soundbar (Universal)",
7009 device_info=DeviceInfo(model="Test", manufacturer="Test"),
7010 protocol_player_ids=["spb_old"],
7011 )
7012 universal._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
7013 universal._cache.clear()
7014 universal.update_state(signal_event=False)
7015 universal.set_initialized()
7016
7017 cast_provider = MockProvider("cast", mass=mock_mass)
7018 native = MockPlayer(
7019 cast_provider,
7020 "cast_1",
7021 "Soundbar",
7022 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
7023 )
7024 native.set_initialized()
7025
7026 sendspin_provider = MockProvider("sendspin", mass=mock_mass)
7027 spb_old = MockPlayer(
7028 sendspin_provider,
7029 "spb_old",
7030 "Soundbar (Sendspin)",
7031 player_type=PlayerType.PROTOCOL,
7032 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
7033 )
7034 spb_old.set_initialized()
7035 spb_new = MockPlayer(
7036 sendspin_provider,
7037 "spb_new",
7038 "Soundbar (Sendspin v2)",
7039 player_type=PlayerType.PROTOCOL,
7040 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
7041 )
7042 spb_new.set_initialized()
7043
7044 controller._players = {
7045 "up_old": universal,
7046 "cast_1": native,
7047 "spb_old": spb_old,
7048 "spb_new": spb_new,
7049 }
7050
7051 controller._add_protocol_link(universal, spb_old, "sendspin")
7052 controller._add_protocol_link(native, spb_new, "sendspin")
7053
7054 controller._check_replace_universal_player(native)
7055
7056 unregister_tasks = [t for t in scheduled_tasks if "unregister" in repr(t)]
7057 assert unregister_tasks == []
7058 assert "up_old" in controller._players
7059 assert spb_old.protocol_parent_id == "up_old"
7060 assert any(
7061 link.output_protocol_id == "spb_old" for link in universal.linked_output_protocols
7062 )
7063
7064 def test_replace_keeps_universal_when_some_links_refused(self, mock_mass: MagicMock) -> None:
7065 """
7066 Keep the universal player when only some of its links could migrate.
7067
7068 The native player already owns the sendspin domain, so the universal player's
7069 sendspin link is refused while its airplay link migrates. The universal player
7070 must be kept (holding the refused link) instead of being unregistered, which
7071 would orphan the refused protocol during cleanup.
7072 """
7073 controller = PlayerController(mock_mass)
7074 up_provider = create_mock_universal_provider(mock_mass)
7075
7076 config_store: dict[str, object] = {
7077 "players/cast_1": {"enabled": True},
7078 "players/up_old": {"enabled": True},
7079 "players/spb_old": {"enabled": True},
7080 "players/spb_new": {"enabled": True},
7081 "players/ap_old": {"enabled": True},
7082 }
7083
7084 def config_get(key: str, default: object = None) -> object:
7085 return config_store.get(key, default)
7086
7087 def config_set(key: str, value: object) -> None:
7088 config_store[key] = value
7089
7090 def config_remove(key: str) -> None:
7091 config_store.pop(key, None)
7092
7093 scheduled_tasks: list[Awaitable[object]] = []
7094
7095 def capture_task(task: Awaitable[object], *_args: Any, **_kwargs: Any) -> None:
7096 scheduled_tasks.append(task)
7097
7098 mock_mass.config.get = MagicMock(side_effect=config_get)
7099 mock_mass.config.set = MagicMock(side_effect=config_set)
7100 mock_mass.config.remove = MagicMock(side_effect=config_remove)
7101 mock_mass.players = controller
7102 mock_mass.player_queues = MagicMock()
7103 mock_mass.call_later = MagicMock()
7104 mock_mass.loop = MagicMock()
7105 mock_mass.create_task = MagicMock(side_effect=capture_task)
7106
7107 universal = UniversalPlayer(
7108 provider=up_provider,
7109 player_id="up_old",
7110 name="Soundbar (Universal)",
7111 device_info=DeviceInfo(model="Test", manufacturer="Test"),
7112 protocol_player_ids=["spb_old", "ap_old"],
7113 )
7114 universal._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
7115 universal._cache.clear()
7116 universal.update_state(signal_event=False)
7117 universal.set_initialized()
7118
7119 cast_provider = MockProvider("cast", mass=mock_mass)
7120 native = MockPlayer(
7121 cast_provider,
7122 "cast_1",
7123 "Soundbar",
7124 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
7125 )
7126 native.set_initialized()
7127
7128 sendspin_provider = MockProvider("sendspin", mass=mock_mass)
7129 spb_old = MockPlayer(
7130 sendspin_provider,
7131 "spb_old",
7132 "Soundbar (Sendspin)",
7133 player_type=PlayerType.PROTOCOL,
7134 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
7135 )
7136 spb_old.set_initialized()
7137 spb_new = MockPlayer(
7138 sendspin_provider,
7139 "spb_new",
7140 "Soundbar (Sendspin v2)",
7141 player_type=PlayerType.PROTOCOL,
7142 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
7143 )
7144 spb_new.set_initialized()
7145
7146 airplay_provider = MockProvider("airplay", mass=mock_mass)
7147 ap_old = MockPlayer(
7148 airplay_provider,
7149 "ap_old",
7150 "Soundbar (AirPlay)",
7151 player_type=PlayerType.PROTOCOL,
7152 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
7153 )
7154 ap_old.set_initialized()
7155
7156 controller._players = {
7157 "up_old": universal,
7158 "cast_1": native,
7159 "spb_old": spb_old,
7160 "spb_new": spb_new,
7161 "ap_old": ap_old,
7162 }
7163
7164 controller._add_protocol_link(universal, spb_old, "sendspin")
7165 controller._add_protocol_link(universal, ap_old, "airplay")
7166 controller._add_protocol_link(native, spb_new, "sendspin")
7167
7168 controller._check_replace_universal_player(native)
7169
7170 unregister_tasks = [t for t in scheduled_tasks if "unregister" in repr(t)]
7171 assert unregister_tasks == []
7172 assert "up_old" in controller._players
7173 # The refused sendspin link stays owned by the universal player.
7174 assert spb_old.protocol_parent_id == "up_old"
7175 assert any(
7176 link.output_protocol_id == "spb_old" for link in universal.linked_output_protocols
7177 )
7178 # The airplay link migrated to the native player and left the universal player.
7179 assert ap_old.protocol_parent_id == "cast_1"
7180 assert any(link.output_protocol_id == "ap_old" for link in native.linked_output_protocols)
7181 assert all(
7182 link.output_protocol_id != "ap_old" for link in universal.linked_output_protocols
7183 )
7184
7185 def test_replace_keeps_cached_protocols_when_a_link_is_refused(
7186 self, mock_mass: MagicMock
7187 ) -> None:
7188 """
7189 Keep cached-only protocol ownership on a universal player that survives.
7190
7191 The native player refuses the sendspin link, so the universal player stays in
7192 charge. Ownership that only exists in config must not be handed over, so a
7193 protocol derived from a refused one keeps pointing at the parent it will link to.
7194 """
7195 controller = PlayerController(mock_mass)
7196 up_provider = create_mock_universal_provider(mock_mass)
7197
7198 config_store: dict[str, Any] = {
7199 "players/cast_1": {"enabled": True},
7200 "players/up_old": {"enabled": True},
7201 "players/spb_old": {"enabled": True},
7202 "players/spb_new": {"enabled": True},
7203 "players/ap_old": {"enabled": True},
7204 "players/dlna_cached": {"enabled": False},
7205 }
7206 mock_mass.config.get = MagicMock(side_effect=config_store.get)
7207 mock_mass.config.set = MagicMock(side_effect=config_store.__setitem__)
7208 mock_mass.config.remove = MagicMock(side_effect=lambda key: config_store.pop(key, None))
7209 mock_mass.players = controller
7210 mock_mass.player_queues = MagicMock()
7211 mock_mass.call_later = MagicMock()
7212 mock_mass.loop = MagicMock()
7213 mock_mass.create_task = MagicMock()
7214
7215 identifiers = {IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"}
7216 universal = UniversalPlayer(
7217 provider=up_provider,
7218 player_id="up_old",
7219 name="Soundbar (Universal)",
7220 device_info=DeviceInfo(model="Test", manufacturer="Test"),
7221 protocol_player_ids=["spb_old", "ap_old", "dlna_cached"],
7222 )
7223 universal._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
7224 universal._cache.clear()
7225 universal.update_state(signal_event=False)
7226 universal.set_initialized()
7227
7228 native = MockPlayer(
7229 MockProvider("cast", mass=mock_mass), "cast_1", "Soundbar", identifiers=identifiers
7230 )
7231 native.set_initialized()
7232 sendspin_provider = MockProvider("sendspin", mass=mock_mass)
7233 spb_old = MockPlayer(
7234 sendspin_provider,
7235 "spb_old",
7236 "Soundbar (Sendspin)",
7237 player_type=PlayerType.PROTOCOL,
7238 identifiers=identifiers,
7239 )
7240 spb_old.set_initialized()
7241 spb_new = MockPlayer(
7242 sendspin_provider,
7243 "spb_new",
7244 "Soundbar (Sendspin v2)",
7245 player_type=PlayerType.PROTOCOL,
7246 identifiers=identifiers,
7247 )
7248 spb_new.set_initialized()
7249 ap_old = MockPlayer(
7250 MockProvider("airplay", mass=mock_mass),
7251 "ap_old",
7252 "Soundbar (AirPlay)",
7253 player_type=PlayerType.PROTOCOL,
7254 identifiers=identifiers,
7255 )
7256 ap_old.set_initialized()
7257
7258 controller._players = {
7259 "up_old": universal,
7260 "cast_1": native,
7261 "spb_old": spb_old,
7262 "spb_new": spb_new,
7263 "ap_old": ap_old,
7264 }
7265 controller._add_protocol_link(universal, spb_old, "sendspin")
7266 controller._add_protocol_link(universal, ap_old, "airplay")
7267 controller._add_protocol_link(native, spb_new, "sendspin")
7268
7269 controller._check_replace_universal_player(native)
7270
7271 # the registered airplay link moved, the refused sendspin link did not
7272 assert ap_old.protocol_parent_id == "cast_1"
7273 assert spb_old.protocol_parent_id == "up_old"
7274 # the cached-only protocol stays with the universal player that remains in charge
7275 assert "dlna_cached" in universal._protocol_player_ids
7276 assert "dlna_cached" not in (
7277 config_store.get("players/cast_1/values/linked_protocol_ids") or []
7278 )
7279 assert config_store.get("players/dlna_cached/values/protocol_parent_id") != "cast_1"
7280
7281 @staticmethod
7282 def _setup_carry_over_scenario(
7283 mock_mass: MagicMock, config_store: dict[str, Any]
7284 ) -> tuple[PlayerController, MockPlayer, list[Awaitable[object]]]:
7285 """
7286 Wire a replacement scenario for the config carry-over tests.
7287
7288 Universal player 'up_old' (holding protocol player 'ap_live') is
7289 replaceable by native player 'cast_1'.
7290 """
7291 controller = PlayerController(mock_mass)
7292 up_provider = create_mock_universal_provider(mock_mass)
7293
7294 def config_get(key: str, default: object = None) -> object:
7295 return config_store.get(key, default)
7296
7297 def config_set(key: str, value: object) -> None:
7298 config_store[key] = value
7299
7300 def config_remove(key: str) -> None:
7301 config_store.pop(key, None)
7302
7303 scheduled_tasks: list[Awaitable[object]] = []
7304
7305 def capture_task(task: Awaitable[object], *_args: Any, **_kwargs: Any) -> None:
7306 scheduled_tasks.append(task)
7307
7308 mock_mass.config.get = MagicMock(side_effect=config_get)
7309 mock_mass.config.set = MagicMock(side_effect=config_set)
7310 mock_mass.config.remove = MagicMock(side_effect=config_remove)
7311 mock_mass.players = controller
7312 mock_mass.player_queues = MagicMock()
7313 mock_mass.player_queues.get.return_value = None
7314 mock_mass.call_later = MagicMock()
7315 mock_mass.loop = MagicMock()
7316 mock_mass.create_task = MagicMock(side_effect=capture_task)
7317
7318 universal = UniversalPlayer(
7319 provider=up_provider,
7320 player_id="up_old",
7321 name="Soundbar (Universal)",
7322 device_info=DeviceInfo(model="Test", manufacturer="Test"),
7323 protocol_player_ids=["ap_live"],
7324 )
7325 universal._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, "AA:BB:CC:DD:EE:FF")
7326 universal._cache.clear()
7327 universal.update_state(signal_event=False)
7328 universal.set_initialized()
7329
7330 cast_provider = MockProvider("cast", mass=mock_mass)
7331 native = MockPlayer(
7332 cast_provider,
7333 "cast_1",
7334 "Soundbar",
7335 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
7336 )
7337 native.set_initialized()
7338
7339 airplay_provider = MockProvider("airplay", mass=mock_mass)
7340 ap_live = MockPlayer(
7341 airplay_provider,
7342 "ap_live",
7343 "Soundbar (AirPlay)",
7344 player_type=PlayerType.PROTOCOL,
7345 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
7346 )
7347 ap_live.set_initialized()
7348
7349 controller._players = {"up_old": universal, "cast_1": native, "ap_live": ap_live}
7350 controller._add_protocol_link(universal, ap_live, "airplay")
7351 return controller, native, scheduled_tasks
7352
7353 async def test_replace_carries_over_universal_config(self, mock_mass: MagicMock) -> None:
7354 """Replacement migrates name, values, DSP and queue settings to the native player."""
7355 config_store: dict[str, Any] = {
7356 # fresh native configs store name == default_name; that must not
7357 # count as a user override blocking the name carry-over
7358 "players/cast_1": {
7359 "enabled": True,
7360 "name": "Soundbar",
7361 "default_name": "Soundbar",
7362 "values": {"volume_control": "native"},
7363 },
7364 "players/up_old": {
7365 "enabled": True,
7366 "name": "Living Room",
7367 "default_name": "Soundbar (Universal)",
7368 "values": {
7369 "hide_in_ui": True,
7370 "volume_control": "up_volume_control",
7371 "linked_protocol_ids": ["ap_live", "ghost_proto"],
7372 "device_identifiers": {"mac_address": "AA:BB:CC:DD:EE:FF"},
7373 "device_info": {"model": "Test", "manufacturer": "Test"},
7374 "ap_live||protocol||output_codec": "flac",
7375 },
7376 },
7377 "players/ap_live": {"enabled": True},
7378 "player_dsp/up_old": {"enabled": True, "filters": []},
7379 "player_queues/up_old": {"queue_id": "up_old", "values": {"crossfade_duration": 5}},
7380 }
7381 controller, native, scheduled_tasks = self._setup_carry_over_scenario(
7382 mock_mass, config_store
7383 )
7384
7385 controller._check_replace_universal_player(native)
7386
7387 # the custom display name and user-set values moved onto the native player
7388 assert config_store["players/cast_1/name"] == "Living Room"
7389 assert config_store["players/cast_1/values/hide_in_ui"] is True
7390 # values the native player has explicitly set are not overwritten
7391 assert "players/cast_1/values/volume_control" not in config_store
7392 # wrapper bookkeeping and protocol-mirror values are not carried over
7393 assert "players/cast_1/values/device_identifiers" not in config_store
7394 assert "players/cast_1/values/device_info" not in config_store
7395 assert "players/cast_1/values/ap_live||protocol||output_codec" not in config_store
7396 # linked ids come from the protocol move machinery, not the universal's raw list
7397 assert config_store["players/cast_1/values/linked_protocol_ids"] == ["ap_live"]
7398 # DSP settings moved wholesale
7399 assert config_store["player_dsp/cast_1"] == {"enabled": True, "filters": []}
7400 # queue settings moved and re-keyed onto the native player's queue
7401 assert config_store["player_queues/cast_1"] == {
7402 "queue_id": "cast_1",
7403 "values": {"crossfade_duration": 5},
7404 }
7405 assert "player_queues/up_old" not in config_store
7406 # the native player's in-place config gets reloaded to apply the new values
7407 assert any("_reapply_player_config" in repr(t) for t in scheduled_tasks)
7408
7409 # and the universal player is still permanently removed
7410 unregister_tasks = [t for t in scheduled_tasks if "unregister" in repr(t)]
7411 assert len(unregister_tasks) == 1
7412 await unregister_tasks[0]
7413 assert "up_old" not in controller._players
7414 # migrated values survive the permanent cleanup of the universal player
7415 assert config_store["players/cast_1/name"] == "Living Room"
7416 assert "players/up_old" not in config_store
7417 assert "player_dsp/up_old" not in config_store
7418
7419 def test_replace_carries_over_nothing_without_user_config(self, mock_mass: MagicMock) -> None:
7420 """A non-customized universal player migrates nothing (no default-name carry)."""
7421 config_store: dict[str, Any] = {
7422 "players/cast_1": {"enabled": True},
7423 "players/up_old": {
7424 "enabled": True,
7425 "name": "Soundbar (Universal)",
7426 "default_name": "Soundbar (Universal)",
7427 "values": {"linked_protocol_ids": ["ap_live"]},
7428 },
7429 "players/ap_live": {"enabled": True},
7430 }
7431 controller, native, scheduled_tasks = self._setup_carry_over_scenario(
7432 mock_mass, config_store
7433 )
7434
7435 controller._check_replace_universal_player(native)
7436
7437 assert "players/cast_1/name" not in config_store
7438 assert "player_dsp/cast_1" not in config_store
7439 assert "player_queues/cast_1" not in config_store
7440 # nothing migrated, so no config reload is scheduled
7441 assert not any("_reapply_player_config" in repr(t) for t in scheduled_tasks)
7442 assert any("unregister" in repr(t) for t in scheduled_tasks)
7443
7444 def test_replace_keeps_native_name_dsp_and_queue_values(self, mock_mass: MagicMock) -> None:
7445 """Values explicitly set on the native player win over the universal player's."""
7446 config_store: dict[str, Any] = {
7447 "players/cast_1": {"enabled": True, "name": "Kitchen", "default_name": "Soundbar"},
7448 "players/up_old": {
7449 "enabled": True,
7450 "name": "Living Room",
7451 "default_name": "Soundbar (Universal)",
7452 "values": {"hide_in_ui": True},
7453 },
7454 "players/ap_live": {"enabled": True},
7455 "player_dsp/cast_1": {"enabled": False, "filters": ["native"]},
7456 "player_dsp/up_old": {"enabled": True, "filters": ["universal"]},
7457 "player_queues/cast_1": {"queue_id": "cast_1", "values": {"crossfade_duration": 2}},
7458 "player_queues/up_old": {
7459 "queue_id": "up_old",
7460 "values": {"crossfade_duration": 8, "autoplay_mode": "smart"},
7461 },
7462 }
7463 controller, native, _ = self._setup_carry_over_scenario(mock_mass, config_store)
7464
7465 controller._check_replace_universal_player(native)
7466
7467 # the native player's own custom name and DSP config win
7468 assert "players/cast_1/name" not in config_store
7469 assert config_store["players/cast_1"]["name"] == "Kitchen"
7470 assert config_store["player_dsp/cast_1"] == {"enabled": False, "filters": ["native"]}
7471 # queue values merge without overwriting the native queue's own values
7472 assert config_store["player_queues/cast_1"] == {
7473 "queue_id": "cast_1",
7474 "values": {"crossfade_duration": 2, "autoplay_mode": "smart"},
7475 }
7476 assert "player_queues/up_old" not in config_store
7477 # non-conflicting values still migrate
7478 assert config_store["players/cast_1/values/hide_in_ui"] is True
7479
7480 async def test_reapply_player_config_refreshes_native_player(
7481 self, mock_mass: MagicMock
7482 ) -> None:
7483 """Reloading the config applies a migrated custom name to the live player."""
7484 controller = PlayerController(mock_mass)
7485 mock_mass.players = controller
7486 mock_mass.player_queues = MagicMock()
7487 mock_mass.call_later = MagicMock()
7488 provider = MockProvider("cast", mass=mock_mass)
7489 native = MockPlayer(provider, "cast_1", "Soundbar")
7490 native.set_initialized()
7491 controller._players = {"cast_1": native}
7492
7493 new_config = PlayerConfig.parse(
7494 [],
7495 {
7496 "player_id": "cast_1",
7497 "provider": "cast",
7498 "name": "Living Room",
7499 "default_name": "Soundbar",
7500 },
7501 )
7502 mock_mass.config.get_player_config = AsyncMock(return_value=new_config)
7503
7504 await controller._reapply_player_config("cast_1")
7505
7506 assert native.config is new_config
7507 assert native.display_name == "Living Room"
7508 signaled_events = [call.args[0] for call in mock_mass.signal_event.call_args_list]
7509 assert EventType.PLAYER_CONFIG_UPDATED in signaled_events
7510
7511 async def test_replace_repoints_group_memberships(self, mock_mass: MagicMock) -> None:
7512 """Replacement re-points group memberships from the wrapper to the native player."""
7513 config_store: dict[str, Any] = {
7514 "players/cast_1": {"enabled": True},
7515 "players/up_old": {
7516 "enabled": True,
7517 "name": "Soundbar (Universal)",
7518 "default_name": "Soundbar (Universal)",
7519 "values": {"linked_protocol_ids": ["ap_live"]},
7520 },
7521 "players/ap_live": {"enabled": True},
7522 # nested players dict scanned by _update_group_memberships
7523 "players": {
7524 "group_1": {
7525 "enabled": True,
7526 "values": {
7527 "group_members": ["up_old", "other"],
7528 "allowed_members": ["up_old"],
7529 },
7530 },
7531 "group_2": {
7532 "enabled": True,
7533 # native id already listed -> no duplicate after re-point
7534 "values": {"group_members": ["up_old", "cast_1", "extra"]},
7535 },
7536 },
7537 }
7538 controller, native, scheduled_tasks = self._setup_carry_over_scenario(
7539 mock_mass, config_store
7540 )
7541 group_1 = MockPlayer(MockProvider("player_group", mass=mock_mass), "group_1", "Group")
7542 group_1.set_initialized()
7543 controller._players["group_1"] = group_1
7544
7545 with patch.object(group_1, "refresh_state") as mock_refresh:
7546 controller._check_replace_universal_player(native)
7547 for task in [t for t in scheduled_tasks if "_reload_group_members" in repr(t)]:
7548 await task
7549
7550 # the wrapper id is replaced by the native id on both membership keys
7551 assert config_store["players/group_1/values/group_members"] == ["cast_1", "other"]
7552 assert config_store["players/group_1/values/allowed_members"] == ["cast_1"]
7553 # no duplicate when the native id is already a member
7554 assert config_store["players/group_2/values/group_members"] == ["cast_1", "extra"]
7555 # a registered player whose membership changed re-reads it and is refreshed
7556 mock_refresh.assert_called()
7557
7558 async def test_replace_stops_playing_universal_before_unregister(
7559 self, mock_mass: MagicMock
7560 ) -> None:
7561 """A playing universal player is stopped before it is permanently removed."""
7562 config_store: dict[str, Any] = {
7563 "players/cast_1": {"enabled": True},
7564 "players/up_old": {
7565 "enabled": True,
7566 "name": "Soundbar (Universal)",
7567 "default_name": "Soundbar (Universal)",
7568 "values": {"linked_protocol_ids": ["ap_live"]},
7569 },
7570 "players/ap_live": {"enabled": True},
7571 }
7572 controller, native, scheduled_tasks = self._setup_carry_over_scenario(
7573 mock_mass, config_store
7574 )
7575 controller._players["up_old"]._attr_playback_state = PlaybackState.PLAYING
7576
7577 call_order: list[str] = []
7578 mock_mass.player_queues.stop = AsyncMock(
7579 side_effect=lambda *_a, **_k: call_order.append("stop")
7580 )
7581
7582 controller._check_replace_universal_player(native)
7583 task = next(t for t in scheduled_tasks if "unregister" in repr(t))
7584
7585 def _record_unregister(*_a: Any, **_k: Any) -> None:
7586 call_order.append("unregister")
7587
7588 with patch.object(controller, "unregister", new=AsyncMock(side_effect=_record_unregister)):
7589 await task
7590
7591 assert call_order == ["stop", "unregister"]
7592 mock_mass.player_queues.stop.assert_awaited_once_with("up_old")
7593
7594 async def test_replace_hands_the_user_filters_to_the_native_player(
7595 self, mock_mass: MagicMock
7596 ) -> None:
7597 """The replaced wrapper hands its access filter entries to the native player."""
7598 config_store: dict[str, Any] = {
7599 "players/cast_1": {"enabled": True},
7600 "players/up_old": {
7601 "enabled": True,
7602 "name": "Soundbar (Universal)",
7603 "default_name": "Soundbar (Universal)",
7604 "values": {"linked_protocol_ids": ["ap_live"]},
7605 },
7606 "players/ap_live": {"enabled": True},
7607 }
7608 controller, native, scheduled_tasks = self._setup_carry_over_scenario(
7609 mock_mass, config_store
7610 )
7611
7612 controller._check_replace_universal_player(native)
7613
7614 task = next(t for t in scheduled_tasks if "unregister" in repr(t))
7615 with patch.object(controller, "unregister", new=AsyncMock()) as mock_unregister:
7616 await task
7617
7618 mock_unregister.assert_awaited_once_with(
7619 "up_old", permanent=True, replacement_player_id="cast_1"
7620 )
7621
7622 async def test_replace_idle_universal_not_stopped(self, mock_mass: MagicMock) -> None:
7623 """An idle universal player is removed without a stop command."""
7624 config_store: dict[str, Any] = {
7625 "players/cast_1": {"enabled": True},
7626 "players/up_old": {
7627 "enabled": True,
7628 "name": "Soundbar (Universal)",
7629 "default_name": "Soundbar (Universal)",
7630 "values": {"linked_protocol_ids": ["ap_live"]},
7631 },
7632 "players/ap_live": {"enabled": True},
7633 }
7634 controller, native, scheduled_tasks = self._setup_carry_over_scenario(
7635 mock_mass, config_store
7636 )
7637 mock_mass.player_queues.stop = AsyncMock()
7638
7639 controller._check_replace_universal_player(native)
7640 task = next(t for t in scheduled_tasks if "unregister" in repr(t))
7641 await task
7642
7643 mock_mass.player_queues.stop.assert_not_awaited()
7644 assert "up_old" not in controller._players
7645
7646 async def test_provider_discovery_rechecks_registered_native_players(
7647 self, mock_mass: MagicMock
7648 ) -> None:
7649 """A native player that registered before its wrapper was restored is promoted."""
7650 controller = PlayerController(mock_mass)
7651 config_store: dict[str, Any] = {
7652 CONF_PLAYERS: {
7653 "sonos_1": {"enabled": True, "values": {}},
7654 "up_old": {"enabled": True, "provider": "universal_player", "values": {}},
7655 "ap_live": {
7656 "enabled": True,
7657 "provider": "airplay--test",
7658 "player_type": "protocol",
7659 "values": {CONF_PROTOCOL_PARENT_ID: "up_old"},
7660 },
7661 }
7662 }
7663 _wire_nested_config(mock_mass, config_store)
7664 mock_mass.players = controller
7665 mock_mass.player_queues = MagicMock()
7666 mock_mass.create_task = MagicMock()
7667 mock_mass.config.get_player_configs = AsyncMock(return_value=[])
7668
7669 provider = create_mock_universal_provider(mock_mass)
7670 identifiers = {IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"}
7671 universal = _create_universal_player(
7672 mock_mass, "up_old", "Old Universal", ["ap_live"], identifiers=identifiers
7673 )
7674 native = MockPlayer(
7675 MockProvider("sonos", mass=mock_mass), "sonos_1", "Sonos", identifiers=identifiers
7676 )
7677 native.set_initialized()
7678 ap_live = MockPlayer(
7679 MockProvider("airplay", mass=mock_mass),
7680 "ap_live",
7681 "AirPlay",
7682 player_type=PlayerType.PROTOCOL,
7683 identifiers=identifiers,
7684 )
7685 ap_live.set_initialized()
7686 controller._players = {
7687 "up_old": universal,
7688 "sonos_1": native,
7689 "ap_live": ap_live,
7690 }
7691 controller._add_protocol_link(universal, ap_live, "airplay")
7692
7693 await provider.discover_players()
7694
7695 assert ap_live.protocol_parent_id == "sonos_1"
7696 assert native.protocol_parent_id is None
7697
7698 async def test_provider_discovery_does_not_replace_wrapper_with_group(
7699 self, mock_mass: MagicMock
7700 ) -> None:
7701 """A matching group player must never take over a wrapper's protocols."""
7702 controller = PlayerController(mock_mass)
7703 config_store: dict[str, Any] = {
7704 CONF_PLAYERS: {
7705 "up_old": {"enabled": True, "provider": "universal_player", "values": {}},
7706 "ap_owned": {
7707 "enabled": True,
7708 "provider": "airplay--test",
7709 "player_type": "protocol",
7710 "values": {CONF_PROTOCOL_PARENT_ID: "up_old"},
7711 },
7712 }
7713 }
7714 _wire_nested_config(mock_mass, config_store)
7715 mock_mass.players = controller
7716 mock_mass.player_queues = MagicMock()
7717 mock_mass.create_task = MagicMock()
7718 mock_mass.config.get_player_configs = AsyncMock(return_value=[])
7719
7720 provider = create_mock_universal_provider(mock_mass)
7721 identifiers = {IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"}
7722 universal = _create_universal_player(
7723 mock_mass, "up_old", "Old Universal", ["ap_owned"], identifiers=identifiers
7724 )
7725 group = MockPlayer(
7726 MockProvider("sync_group", mass=mock_mass),
7727 "group_1",
7728 "Group",
7729 player_type=PlayerType.GROUP,
7730 identifiers=identifiers,
7731 )
7732 group.set_initialized()
7733 ap_owned = MockPlayer(
7734 MockProvider("airplay", mass=mock_mass),
7735 "ap_owned",
7736 "AirPlay",
7737 player_type=PlayerType.PROTOCOL,
7738 identifiers=identifiers,
7739 )
7740 ap_owned.set_initialized()
7741 controller._players = {"up_old": universal, "group_1": group, "ap_owned": ap_owned}
7742 controller._add_protocol_link(universal, ap_owned, "airplay")
7743
7744 await provider.discover_players()
7745
7746 assert ap_owned.protocol_parent_id == "up_old"
7747 assert not group.linked_output_protocols
7748
7749 async def test_eviction_from_an_emptied_wrapper_does_not_schedule_its_removal(
7750 self, mock_mass: MagicMock
7751 ) -> None:
7752 """
7753 Eviction leaves a wrapper it empties registered, and deliberately so.
7754
7755 `_add_protocol_link` evicts a protocol from every other parent, but tearing
7756 down a parent it empties is not its job: that belongs to the flow that owns
7757 the takeover (`_check_replace_universal_player`, `_merge_universal_players`
7758 or `_unlink_from_protocol_parent`). Scheduling a removal here would even be
7759 harmful, because `mass.create_task` runs with `eager_start=True` and
7760 `PlayerController.unregister` drops the player from `_players` before its
7761 first await: the removal would run synchronously and turn the owning flow's
7762 later `permanent=True` removal into a silent no-op, skipping the config
7763 deletion and the PLAYER_REMOVED event.
7764 """
7765 controller = PlayerController(mock_mass)
7766 config_store: dict[str, Any] = {
7767 CONF_PLAYERS: {
7768 "sonos_1": {"enabled": True, "values": {}},
7769 "up_old": {"enabled": True, "provider": "universal_player", "values": {}},
7770 "ap_live": {
7771 "enabled": True,
7772 "provider": "airplay--test",
7773 "player_type": "protocol",
7774 "values": {CONF_PROTOCOL_PARENT_ID: "up_old"},
7775 },
7776 }
7777 }
7778 _wire_nested_config(mock_mass, config_store)
7779
7780 scheduled_tasks: list[Awaitable[object]] = []
7781
7782 def capture_task(task: Awaitable[object], *_args: Any, **_kwargs: Any) -> None:
7783 scheduled_tasks.append(task)
7784
7785 mock_mass.players = controller
7786 mock_mass.player_queues = MagicMock()
7787 mock_mass.call_later = MagicMock()
7788 mock_mass.loop = MagicMock()
7789 mock_mass.create_task = MagicMock(side_effect=capture_task)
7790
7791 identifiers = {IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"}
7792 universal = _create_universal_player(
7793 mock_mass, "up_old", "Old Universal", ["ap_live"], identifiers=identifiers
7794 )
7795 native = MockPlayer(
7796 MockProvider("sonos", mass=mock_mass), "sonos_1", "Sonos", identifiers=identifiers
7797 )
7798 native.set_initialized()
7799 ap_live = MockPlayer(
7800 MockProvider("airplay", mass=mock_mass),
7801 "ap_live",
7802 "AirPlay",
7803 player_type=PlayerType.PROTOCOL,
7804 identifiers=identifiers,
7805 )
7806 ap_live.set_initialized()
7807 controller._players = {"up_old": universal, "sonos_1": native, "ap_live": ap_live}
7808
7809 controller._add_protocol_link(universal, ap_live, "airplay")
7810 assert [link.output_protocol_id for link in universal.linked_output_protocols] == [
7811 "ap_live"
7812 ]
7813 scheduled_tasks.clear()
7814
7815 with patch.object(controller, "unregister", new=AsyncMock()) as mock_unregister:
7816 controller._add_protocol_link(native, ap_live, "airplay")
7817 # replay whatever the eviction scheduled, so a missing unregister is what makes
7818 # the assertion below hold and not a task that never got the chance to run
7819 for task in scheduled_tasks:
7820 await task
7821
7822 assert ap_live.protocol_parent_id == "sonos_1"
7823 assert universal.linked_output_protocols == []
7824 assert universal._protocol_player_ids == []
7825 assert "up_old" in controller._players
7826 # removing the emptied wrapper is left to the flow that owns the takeover
7827 assert mock_unregister.call_args_list == []
7828
7829 async def test_wrapper_listing_the_native_id_as_its_protocol_completes_the_takeover(
7830 self, mock_mass: MagicMock
7831 ) -> None:
7832 """
7833 A wrapper that lists the native player's own id is still fully replaced.
7834
7835 A device that keeps its player id across a PROTOCOL -> PLAYER type change stays
7836 one of the wrapper's linked protocols. It cannot be taken over from itself, so it
7837 is left out of the transfer: the wrapper's genuine protocol moves to the native
7838 player, the user's configuration is carried over and the emptied wrapper is
7839 permanently removed.
7840 """
7841 controller = PlayerController(mock_mass)
7842 config_store: dict[str, Any] = {
7843 CONF_PLAYERS: {
7844 "esp_client": {
7845 "enabled": True,
7846 "provider": "sendspin--test",
7847 # left over from before the device changed type
7848 "values": {CONF_PROTOCOL_PARENT_ID: "up_old"},
7849 },
7850 "up_old": {
7851 "enabled": True,
7852 "provider": "universal_player",
7853 "name": "Living Room",
7854 "default_name": "ESP (Universal)",
7855 "values": {"hide_in_ui": True},
7856 },
7857 "ap_live": {
7858 "enabled": True,
7859 "provider": "airplay--test",
7860 "player_type": "protocol",
7861 "values": {CONF_PROTOCOL_PARENT_ID: "up_old"},
7862 },
7863 # a disabled protocol that never registered, so it only exists in config
7864 "dlna_off": {
7865 "enabled": False,
7866 "provider": "dlna--test",
7867 "player_type": "protocol",
7868 "values": {CONF_PROTOCOL_PARENT_ID: "up_old"},
7869 },
7870 }
7871 }
7872 _wire_nested_config(mock_mass, config_store)
7873
7874 scheduled_tasks: list[Awaitable[object]] = []
7875
7876 def capture_task(task: Awaitable[object], *_args: Any, **_kwargs: Any) -> None:
7877 scheduled_tasks.append(task)
7878
7879 mock_mass.players = controller
7880 mock_mass.player_queues = MagicMock()
7881 # keep the state refreshes below from scheduling an unrelated palette fetch
7882 mock_mass.player_queues.get = MagicMock(return_value=None)
7883 mock_mass.call_later = MagicMock()
7884 mock_mass.loop = MagicMock()
7885 mock_mass.create_task = MagicMock(side_effect=capture_task)
7886 mock_mass.config.get_player_config = AsyncMock(
7887 return_value=PlayerConfig.parse(
7888 [],
7889 {
7890 "player_id": "esp_client",
7891 "provider": "sendspin--test",
7892 "name": "Living Room",
7893 "default_name": "ESP",
7894 },
7895 )
7896 )
7897
7898 identifiers = {IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"}
7899 universal = _create_universal_player(
7900 mock_mass,
7901 "up_old",
7902 "ESP (Universal)",
7903 ["ap_live", "esp_client", "dlna_off"],
7904 identifiers=identifiers,
7905 )
7906 native = MockPlayer(
7907 MockProvider("sendspin", mass=mock_mass), "esp_client", "ESP", identifiers=identifiers
7908 )
7909 native.set_initialized()
7910 ap_live = MockPlayer(
7911 MockProvider("airplay", mass=mock_mass),
7912 "ap_live",
7913 "AirPlay",
7914 player_type=PlayerType.PROTOCOL,
7915 identifiers=identifiers,
7916 )
7917 ap_live.set_initialized()
7918 controller._players = {"up_old": universal, "esp_client": native, "ap_live": ap_live}
7919
7920 controller._add_protocol_link(universal, ap_live, "airplay")
7921 # the wrapper linked the device as a protocol before it changed type
7922 universal.set_linked_output_protocols(
7923 [
7924 *universal.linked_output_protocols,
7925 LinkedOutputProtocol(
7926 output_protocol_id="esp_client", protocol_domain="sendspin", priority=20
7927 ),
7928 ]
7929 )
7930 scheduled_tasks.clear()
7931
7932 with patch.object(controller, "unregister", new=AsyncMock()) as mock_unregister:
7933 controller._check_replace_universal_player(native)
7934 # replay what the takeover scheduled, otherwise the unregister assertion below
7935 # would hold for a task that never got the chance to run
7936 for task in scheduled_tasks:
7937 await task
7938
7939 # the genuine protocol moved over and the wrapper is left without any output
7940 assert ap_live.protocol_parent_id == "esp_client"
7941 assert universal.linked_output_protocols == []
7942 assert universal._protocol_player_ids == []
7943 # the emptied wrapper is permanently removed in favour of the native player
7944 mock_unregister.assert_awaited_once_with(
7945 "up_old", permanent=True, replacement_player_id="esp_client"
7946 )
7947 # and the user's configuration is carried over before that removal deletes it
7948 assert config_store[CONF_PLAYERS]["esp_client"]["name"] == "Living Room"
7949 assert config_store[CONF_PLAYERS]["esp_client"]["values"]["hide_in_ui"] is True
7950 # ownership is handed over in config as well, for the protocol that moved and for
7951 # the one that only exists in config: nothing may keep pointing at the removed wrapper
7952 ap_values = config_store[CONF_PLAYERS]["ap_live"]["values"]
7953 assert ap_values[CONF_PROTOCOL_PARENT_ID] == "esp_client"
7954 dlna_values = config_store[CONF_PLAYERS]["dlna_off"]["values"]
7955 assert dlna_values[CONF_PROTOCOL_PARENT_ID] == "esp_client"
7956 # the native player is never left pointing at the wrapper it replaces
7957 assert native.protocol_parent_id is None
7958 assert config_store[CONF_PLAYERS]["esp_client"]["values"][CONF_PROTOCOL_PARENT_ID] is None
7959
7960 async def test_wrapper_holding_only_the_native_id_completes_the_takeover(
7961 self, mock_mass: MagicMock
7962 ) -> None:
7963 """
7964 A wrapper whose only protocol is the native player itself is cleaned up.
7965
7966 Leaving the native player out of the transfer empties the wrapper without
7967 anything to hand over, which still carries the user's configuration across
7968 and removes the wrapper next to the player that replaces it.
7969 """
7970 controller = PlayerController(mock_mass)
7971 config_store: dict[str, Any] = {
7972 CONF_PLAYERS: {
7973 "esp_client": {"enabled": True, "provider": "sendspin--test", "values": {}},
7974 "up_old": {
7975 "enabled": True,
7976 "provider": "universal_player",
7977 "name": "Living Room",
7978 "default_name": "ESP (Universal)",
7979 "values": {"hide_in_ui": True},
7980 },
7981 }
7982 }
7983 _wire_nested_config(mock_mass, config_store)
7984
7985 scheduled_tasks: list[Awaitable[object]] = []
7986
7987 def capture_task(task: Awaitable[object], *_args: Any, **_kwargs: Any) -> None:
7988 scheduled_tasks.append(task)
7989
7990 mock_mass.players = controller
7991 mock_mass.player_queues = MagicMock()
7992 mock_mass.player_queues.get = MagicMock(return_value=None)
7993 mock_mass.call_later = MagicMock()
7994 mock_mass.loop = MagicMock()
7995 mock_mass.create_task = MagicMock(side_effect=capture_task)
7996 mock_mass.config.get_player_config = AsyncMock(
7997 return_value=PlayerConfig.parse(
7998 [],
7999 {
8000 "player_id": "esp_client",
8001 "provider": "sendspin--test",
8002 "name": "Living Room",
8003 "default_name": "ESP",
8004 },
8005 )
8006 )
8007
8008 universal = _create_universal_player(mock_mass, "up_old", "ESP (Universal)", ["esp_client"])
8009 universal.set_linked_output_protocols(
8010 [
8011 LinkedOutputProtocol(
8012 output_protocol_id="esp_client", protocol_domain="sendspin", priority=20
8013 )
8014 ]
8015 )
8016 native = MockPlayer(MockProvider("sendspin", mass=mock_mass), "esp_client", "ESP")
8017 native.set_initialized()
8018 controller._players = {"up_old": universal, "esp_client": native}
8019 scheduled_tasks.clear()
8020
8021 with patch.object(controller, "unregister", new=AsyncMock()) as mock_unregister:
8022 controller._check_replace_universal_player(native)
8023 for task in scheduled_tasks:
8024 await task
8025
8026 assert universal.linked_output_protocols == []
8027 assert universal._protocol_player_ids == []
8028 mock_unregister.assert_awaited_once_with(
8029 "up_old", permanent=True, replacement_player_id="esp_client"
8030 )
8031 assert config_store[CONF_PLAYERS]["esp_client"]["name"] == "Living Room"
8032 assert config_store[CONF_PLAYERS]["esp_client"]["values"]["hide_in_ui"] is True
8033 assert native.protocol_parent_id is None
8034
8035 async def test_wrapper_with_a_bridge_riding_on_the_native_completes_the_takeover(
8036 self, mock_mass: MagicMock
8037 ) -> None:
8038 """
8039 A protocol riding on the native player's own id moves along with the takeover.
8040
8041 The wrapper lists the device that kept its id across a type change together with
8042 the bridge riding on it, so both sit in one group with the device as its base.
8043 Leaving the device out of the transfer must not hold the bridge back: the bridge
8044 moves over as a protocol derived from the native player itself.
8045 """
8046 controller = PlayerController(mock_mass)
8047 config_store: dict[str, Any] = {
8048 CONF_PLAYERS: {
8049 "cast_base": {"enabled": True, "provider": "chromecast--test", "values": {}},
8050 "up_old": {
8051 "enabled": True,
8052 "provider": "universal_player",
8053 "name": "Kitchen",
8054 "default_name": "Speaker (Universal)",
8055 "values": {"hide_in_ui": True},
8056 },
8057 "spb_bridge": {
8058 "enabled": True,
8059 "provider": "sendspin--test",
8060 "player_type": "protocol",
8061 "values": {
8062 CONF_PROTOCOL_PARENT_ID: "up_old",
8063 CONF_UNDERLYING_PLAYER_ID: "cast_base",
8064 },
8065 },
8066 }
8067 }
8068 _wire_nested_config(mock_mass, config_store)
8069
8070 scheduled_tasks: list[Awaitable[object]] = []
8071
8072 def capture_task(task: Awaitable[object], *_args: Any, **_kwargs: Any) -> None:
8073 scheduled_tasks.append(task)
8074
8075 mock_mass.players = controller
8076 mock_mass.player_queues = MagicMock()
8077 # keep the state refreshes below from scheduling an unrelated palette fetch
8078 mock_mass.player_queues.get = MagicMock(return_value=None)
8079 mock_mass.call_later = MagicMock()
8080 mock_mass.loop = MagicMock()
8081 mock_mass.create_task = MagicMock(side_effect=capture_task)
8082 mock_mass.config.get_player_config = AsyncMock(
8083 return_value=PlayerConfig.parse(
8084 [],
8085 {
8086 "player_id": "cast_base",
8087 "provider": "chromecast--test",
8088 "name": "Kitchen",
8089 "default_name": "Speaker",
8090 },
8091 )
8092 )
8093
8094 identifiers = {IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"}
8095 universal = _create_universal_player(
8096 mock_mass,
8097 "up_old",
8098 "Speaker (Universal)",
8099 ["cast_base", "spb_bridge"],
8100 identifiers=identifiers,
8101 )
8102 native = MockPlayer(
8103 MockProvider("chromecast", mass=mock_mass),
8104 "cast_base",
8105 "Speaker",
8106 identifiers=identifiers,
8107 )
8108 native.set_initialized()
8109 bridge = MockPlayer(
8110 MockProvider("sendspin", mass=mock_mass),
8111 "spb_bridge",
8112 "Speaker (Bridge)",
8113 player_type=PlayerType.PROTOCOL,
8114 )
8115 bridge._attr_underlying_player_id = "cast_base"
8116 bridge.set_initialized()
8117 controller._players = {"up_old": universal, "cast_base": native, "spb_bridge": bridge}
8118
8119 controller._add_protocol_link(universal, bridge, "sendspin")
8120 # the wrapper linked the device as a protocol before it changed type, which makes
8121 # it the base of the group the bridge rides on
8122 universal.set_linked_output_protocols(
8123 [
8124 *universal.linked_output_protocols,
8125 LinkedOutputProtocol(
8126 output_protocol_id="cast_base", protocol_domain="chromecast", priority=30
8127 ),
8128 ]
8129 )
8130 scheduled_tasks.clear()
8131
8132 with patch.object(controller, "unregister", new=AsyncMock()) as mock_unregister:
8133 controller._check_replace_universal_player(native)
8134 # replay what the takeover scheduled, otherwise the unregister assertion below
8135 # would hold for a task that never got the chance to run
8136 for task in scheduled_tasks:
8137 await task
8138
8139 assert bridge.protocol_parent_id == "cast_base"
8140 # the bridge now rides on the parent player itself, recorded as "native"
8141 bridge_link = next(
8142 link
8143 for link in native.linked_output_protocols
8144 if link.output_protocol_id == "spb_bridge"
8145 )
8146 assert bridge_link.derived_from == "native"
8147 # the native player is never left pointing at the wrapper it replaces
8148 assert native.protocol_parent_id is None
8149 # the wrapper is left without any output and permanently removed
8150 assert universal.linked_output_protocols == []
8151 assert universal._protocol_player_ids == []
8152 mock_unregister.assert_awaited_once_with(
8153 "up_old", permanent=True, replacement_player_id="cast_base"
8154 )
8155
8156
8157class TestEndToEndDuplicateProtocol:
8158 """
8159 End-to-end integration tests for duplicate protocol â separate universal player flow.
8160
8161 These tests exercise the full async flow through _delayed_protocol_evaluation,
8162 ensure_universal_players_for_protocols, and _create_separate_universal_player,
8163 verifying that a second instance of the same protocol domain on the same host
8164 results in a separate universal player.
8165 """
8166
8167 @staticmethod
8168 def _setup_e2e_controller(
8169 mock_mass: MagicMock,
8170 ) -> tuple[PlayerController, UniversalPlayerProvider]:
8171 """
8172 Set up a PlayerController and UniversalPlayerProvider wired for E2E testing.
8173
8174 The mock_mass is configured so that:
8175 - get_providers(ProviderType.PLAYER) returns the universal provider
8176 - register_or_update adds the player to the controller's _players dict
8177 - config.create_default_player_config does not fail
8178 - config.set does not fail
8179
8180 :return: Tuple of (controller, universal_provider).
8181 """
8182 controller = PlayerController(mock_mass)
8183 up_provider = create_mock_universal_provider(mock_mass)
8184
8185 # Wire get_providers to return our universal provider
8186 mock_mass.get_providers = MagicMock(return_value=[up_provider])
8187
8188 # Wire register_or_update to add the player to controller._players
8189 async def fake_register_or_update(player: Player) -> None:
8190 controller._players[player.player_id] = player
8191 player.set_initialized()
8192
8193 mock_mass.players = MagicMock()
8194 mock_mass.players.register_or_update = AsyncMock(side_effect=fake_register_or_update)
8195 mock_mass.players.get_player = lambda pid: controller._players.get(pid)
8196
8197 # Wire config methods
8198 mock_mass.config.create_default_player_config = MagicMock()
8199 mock_mass.config.set = MagicMock()
8200 mock_mass.config.get_base_player_config.return_value = create_mock_config("Test")
8201
8202 return controller, up_provider
8203
8204 @pytest.mark.asyncio
8205 async def test_path_a_delayed_eval_creates_separate_universal_for_duplicate(
8206 self, mock_mass: MagicMock
8207 ) -> None:
8208 """
8209 Path A: _delayed_protocol_evaluation creates separate universal player for duplicate.
8210
8211 Scenario: Two AirPlay instances register on the same host.
8212 1. First AirPlay links to existing universal player
8213 via _add_protocol_to_existing_universal
8214 2. Second AirPlay arrives at _delayed_protocol_evaluation
8215 3. It finds the existing universal player but is refused (domain duplicate)
8216 4. Falls through to _find_matching_protocol_players (which skips same-domain)
8217 5. Creates a NEW separate universal player via _create_or_update_universal_player
8218 """
8219 controller, _ = self._setup_e2e_controller(mock_mass)
8220
8221 # Create existing universal player with AirPlay already linked
8222 universal = _create_universal_player(
8223 mock_mass,
8224 "up_aabbccddeeff",
8225 "Living Room Speaker",
8226 protocol_player_ids=["ap_1"],
8227 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8228 )
8229
8230 # Create first AirPlay (already linked to universal)
8231 ap_provider = MockProvider("airplay", mass=mock_mass)
8232 ap1 = MockPlayer(
8233 ap_provider,
8234 "ap_1",
8235 "AirPlay Instance 1",
8236 player_type=PlayerType.PROTOCOL,
8237 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8238 )
8239 ap1.set_initialized()
8240 controller._add_protocol_link(universal, ap1, "airplay")
8241 assert ap1.protocol_parent_id == "up_aabbccddeeff"
8242
8243 # Create second AirPlay (same MAC, not yet linked)
8244 ap2 = MockPlayer(
8245 ap_provider,
8246 "ap_2",
8247 "AirPlay Instance 2",
8248 player_type=PlayerType.PROTOCOL,
8249 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8250 )
8251 ap2.set_initialized()
8252
8253 controller._players = {
8254 "up_aabbccddeeff": universal,
8255 "ap_1": ap1,
8256 "ap_2": ap2,
8257 }
8258
8259 # Run delayed evaluation for ap2 - full async flow
8260 await controller._delayed_protocol_evaluation("ap_2")
8261
8262 # ap2 should NOT be linked to the existing universal player
8263 assert ap2.protocol_parent_id != "up_aabbccddeeff"
8264
8265 # ap2 should have its own (freshly minted) universal player
8266 assert ap2.protocol_parent_id is not None
8267 separate_up_id = ap2.protocol_parent_id
8268 assert separate_up_id in controller._players
8269 separate_up = controller._players[separate_up_id]
8270 assert isinstance(separate_up, UniversalPlayer)
8271
8272 # The original universal player should still have only ap_1
8273 original_ap_links = [
8274 link for link in universal.linked_output_protocols if link.protocol_domain == "airplay"
8275 ]
8276 assert len(original_ap_links) == 1
8277 assert original_ap_links[0].output_protocol_id == "ap_1"
8278
8279 @pytest.mark.asyncio
8280 async def test_path_a_delayed_eval_joins_existing_universal_different_domain(
8281 self, mock_mass: MagicMock
8282 ) -> None:
8283 """
8284 Path A: _delayed_protocol_evaluation correctly joins when domain is different.
8285
8286 Scenario: AirPlay universal player exists, DLNA arrives via delayed eval.
8287 DLNA should successfully join the existing universal player (different domain).
8288 """
8289 controller, _ = self._setup_e2e_controller(mock_mass)
8290
8291 # Create existing universal player with AirPlay linked
8292 universal = _create_universal_player(
8293 mock_mass,
8294 "up_aabbccddeeff",
8295 "Living Room Speaker",
8296 protocol_player_ids=["ap_1"],
8297 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8298 )
8299
8300 ap_provider = MockProvider("airplay", mass=mock_mass)
8301 ap1 = MockPlayer(
8302 ap_provider,
8303 "ap_1",
8304 "AirPlay",
8305 player_type=PlayerType.PROTOCOL,
8306 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8307 )
8308 ap1.set_initialized()
8309 controller._add_protocol_link(universal, ap1, "airplay")
8310
8311 # Create DLNA player (same device, different protocol)
8312 dlna_provider = MockProvider("dlna", mass=mock_mass)
8313 dlna1 = MockPlayer(
8314 dlna_provider,
8315 "dlna_1",
8316 "DLNA",
8317 player_type=PlayerType.PROTOCOL,
8318 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8319 )
8320 dlna1.set_initialized()
8321
8322 controller._players = {
8323 "up_aabbccddeeff": universal,
8324 "ap_1": ap1,
8325 "dlna_1": dlna1,
8326 }
8327
8328 # Run delayed evaluation for DLNA
8329 await controller._delayed_protocol_evaluation("dlna_1")
8330
8331 # DLNA should join the existing universal player
8332 assert dlna1.protocol_parent_id == "up_aabbccddeeff"
8333
8334 # Universal player should now have both AirPlay and DLNA
8335 domains = {link.protocol_domain for link in universal.linked_output_protocols}
8336 assert "airplay" in domains
8337 assert "dlna" in domains
8338
8339 @pytest.mark.asyncio
8340 async def test_path_b_ensure_universal_separates_duplicate_domain(
8341 self, mock_mass: MagicMock
8342 ) -> None:
8343 """
8344 Path B: ensure_universal_players_for_protocols separates can_join vs rejected.
8345
8346 Scenario: Two AirPlay players arrive simultaneously for delayed eval.
8347 Both are unlinked, both pass to _create_or_update_universal_player.
8348 The first creates a universal player. The second finds the existing one
8349 and is rejected (duplicate domain), getting its own separate universal player.
8350 """
8351 controller, _ = self._setup_e2e_controller(mock_mass)
8352
8353 ap_provider = MockProvider("airplay", mass=mock_mass)
8354 ap1 = MockPlayer(
8355 ap_provider,
8356 "ap_1",
8357 "AirPlay Instance 1",
8358 player_type=PlayerType.PROTOCOL,
8359 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8360 )
8361 ap1.set_initialized()
8362
8363 ap2 = MockPlayer(
8364 ap_provider,
8365 "ap_2",
8366 "AirPlay Instance 2",
8367 player_type=PlayerType.PROTOCOL,
8368 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8369 )
8370 ap2.set_initialized()
8371
8372 controller._players = {
8373 "ap_1": ap1,
8374 "ap_2": ap2,
8375 }
8376
8377 # First: ap1 goes through delayed evaluation, creates a universal player
8378 await controller._delayed_protocol_evaluation("ap_1")
8379
8380 # ap1 should have a universal player parent
8381 assert ap1.protocol_parent_id is not None
8382 first_up_id = ap1.protocol_parent_id
8383 assert first_up_id in controller._players
8384
8385 # Second: ap2 goes through delayed evaluation
8386 # _find_matching_universal_player will find the universal player by MAC
8387 # _add_protocol_to_existing_universal will refuse (duplicate domain)
8388 # _find_matching_protocol_players will skip ap1 (same domain)
8389 # _create_or_update_universal_player â ensure_universal_players_for_protocols
8390 # finds existing universal player, separates ap2 as rejected
8391 await controller._delayed_protocol_evaluation("ap_2")
8392
8393 # ap2 should have its own separate universal player
8394 assert ap2.protocol_parent_id is not None
8395 second_up_id = ap2.protocol_parent_id
8396 assert second_up_id != first_up_id
8397 assert second_up_id in controller._players
8398
8399 # Both universal players should exist
8400 first_up = controller._players[first_up_id]
8401 second_up = controller._players[second_up_id]
8402 assert isinstance(first_up, UniversalPlayer)
8403 assert isinstance(second_up, UniversalPlayer)
8404
8405 @pytest.mark.asyncio
8406 async def test_path_b_first_creates_then_second_gets_separate(
8407 self, mock_mass: MagicMock
8408 ) -> None:
8409 """
8410 Path B: First protocol player creates universal, second gets separate.
8411
8412 Scenario: AirPlay and DLNA create a universal player together.
8413 Then a second AirPlay arrives and gets its own separate universal player.
8414 """
8415 controller, _ = self._setup_e2e_controller(mock_mass)
8416
8417 ap_provider = MockProvider("airplay", mass=mock_mass)
8418 dlna_provider = MockProvider("dlna", mass=mock_mass)
8419
8420 ap1 = MockPlayer(
8421 ap_provider,
8422 "ap_1",
8423 "AirPlay",
8424 player_type=PlayerType.PROTOCOL,
8425 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8426 )
8427 ap1.set_initialized()
8428
8429 dlna1 = MockPlayer(
8430 dlna_provider,
8431 "dlna_1",
8432 "DLNA",
8433 player_type=PlayerType.PROTOCOL,
8434 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8435 )
8436 dlna1.set_initialized()
8437
8438 ap2 = MockPlayer(
8439 ap_provider,
8440 "ap_2",
8441 "AirPlay 2",
8442 player_type=PlayerType.PROTOCOL,
8443 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8444 )
8445 ap2.set_initialized()
8446
8447 controller._players = {
8448 "ap_1": ap1,
8449 "dlna_1": dlna1,
8450 "ap_2": ap2,
8451 }
8452
8453 # First: ap1 arrives at delayed eval, finds dlna1 as matching (different domain)
8454 # Together they create a universal player
8455 await controller._delayed_protocol_evaluation("ap_1")
8456
8457 assert ap1.protocol_parent_id is not None
8458 # dlna1 should also be linked (found by _find_matching_protocol_players)
8459 assert dlna1.protocol_parent_id == ap1.protocol_parent_id
8460 shared_up_id = ap1.protocol_parent_id
8461
8462 # Second: ap2 arrives at delayed eval
8463 await controller._delayed_protocol_evaluation("ap_2")
8464
8465 # ap2 should get its own universal player
8466 assert ap2.protocol_parent_id is not None
8467 assert ap2.protocol_parent_id != shared_up_id
8468 assert ap2.protocol_parent_id in controller._players
8469
8470 # Shared universal player should have AirPlay + DLNA
8471 shared_up = controller._players[shared_up_id]
8472 shared_domains = {link.protocol_domain for link in shared_up.linked_output_protocols}
8473 assert "airplay" in shared_domains
8474 assert "dlna" in shared_domains
8475
8476 @pytest.mark.asyncio
8477 async def test_path_c_sendspin_duplicate_gets_separate_universal(
8478 self, mock_mass: MagicMock
8479 ) -> None:
8480 """
8481 Path C: Two Sendspin bridge instances on same host get separate universal players.
8482
8483 Sendspin bridges match via CAST_UUID / AIRPLAY_ID, not MAC. Two bridges
8484 on the same host share the same MAC (from ARP) but have different CAST_UUIDs.
8485 Each should get its own universal player.
8486 """
8487 controller, _ = self._setup_e2e_controller(mock_mass)
8488
8489 sendspin_provider = MockProvider("sendspin", mass=mock_mass)
8490
8491 # First Sendspin bridge
8492 spb1 = MockPlayer(
8493 sendspin_provider,
8494 "spb_1",
8495 "Sendspin Bridge 1",
8496 player_type=PlayerType.PROTOCOL,
8497 identifiers={
8498 IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF",
8499 IdentifierType.CAST_UUID: "cast-uuid-111",
8500 },
8501 )
8502 spb1.set_initialized()
8503
8504 # Second Sendspin bridge (same MAC, different CAST_UUID)
8505 spb2 = MockPlayer(
8506 sendspin_provider,
8507 "spb_2",
8508 "Sendspin Bridge 2",
8509 player_type=PlayerType.PROTOCOL,
8510 identifiers={
8511 IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF",
8512 IdentifierType.CAST_UUID: "cast-uuid-222",
8513 },
8514 )
8515 spb2.set_initialized()
8516
8517 controller._players = {
8518 "spb_1": spb1,
8519 "spb_2": spb2,
8520 }
8521
8522 # First: spb1 goes through delayed evaluation
8523 await controller._delayed_protocol_evaluation("spb_1")
8524
8525 assert spb1.protocol_parent_id is not None
8526 first_up_id = spb1.protocol_parent_id
8527
8528 # Second: spb2 goes through delayed evaluation
8529 # _find_matching_protocol_players skips spb1 (same domain: "sendspin")
8530 # _find_matching_universal_player may find the first universal player by MAC
8531 # _add_protocol_to_existing_universal refuses (duplicate domain: "sendspin")
8532 # Falls through to create separate universal player
8533 await controller._delayed_protocol_evaluation("spb_2")
8534
8535 assert spb2.protocol_parent_id is not None
8536 second_up_id = spb2.protocol_parent_id
8537
8538 # Each should have its own universal player
8539 assert first_up_id != second_up_id
8540 assert first_up_id in controller._players
8541 assert second_up_id in controller._players
8542
8543 first_up = controller._players[first_up_id]
8544 second_up = controller._players[second_up_id]
8545 assert isinstance(first_up, UniversalPlayer)
8546 assert isinstance(second_up, UniversalPlayer)
8547
8548 @pytest.mark.asyncio
8549 async def test_three_airplay_instances_get_separate_universals(
8550 self, mock_mass: MagicMock
8551 ) -> None:
8552 """
8553 Test that three AirPlay instances each get their own universal player.
8554
8555 Exercises the flow when there are 3+ instances of the same protocol.
8556 """
8557 controller, _ = self._setup_e2e_controller(mock_mass)
8558
8559 ap_provider = MockProvider("airplay", mass=mock_mass)
8560 players = []
8561 for i in range(1, 4):
8562 p = MockPlayer(
8563 ap_provider,
8564 f"ap_{i}",
8565 f"AirPlay Instance {i}",
8566 player_type=PlayerType.PROTOCOL,
8567 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8568 )
8569 p.set_initialized()
8570 players.append(p)
8571
8572 controller._players = {p.player_id: p for p in players}
8573
8574 # Run delayed evaluation for each in sequence
8575 for p in players:
8576 await controller._delayed_protocol_evaluation(p.player_id)
8577
8578 # Each should have its own universal player
8579 parent_ids = {p.protocol_parent_id for p in players}
8580 assert None not in parent_ids
8581 # All three should have distinct parents
8582 assert len(parent_ids) == 3
8583
8584 # All three universal players should exist
8585 for pid in parent_ids:
8586 assert pid in controller._players
8587 assert isinstance(controller._players[pid], UniversalPlayer)
8588
8589 @pytest.mark.asyncio
8590 async def test_same_domain_same_ip_get_separate_universals(self, mock_mass: MagicMock) -> None:
8591 """
8592 Test that multiple instances of the same protocol on the same host stay separate.
8593
8594 Scenario: 3 shairport-sync AirPlay instances on the same Raspberry Pi.
8595 All share the same IP and have locally-administered MACs.
8596 The IP fallback must NOT merge them â domain dedup takes precedence.
8597 """
8598 controller, _ = self._setup_e2e_controller(mock_mass)
8599
8600 ap_provider = MockProvider("airplay", mass=mock_mass)
8601 players = []
8602 for i in range(1, 4):
8603 p = MockPlayer(
8604 ap_provider,
8605 f"ap_{i}",
8606 f"Shairport Zone {i}",
8607 player_type=PlayerType.PROTOCOL,
8608 identifiers={
8609 # Each has a distinct LA MAC (as shairport-sync generates)
8610 IdentifierType.MAC_ADDRESS: f"02:AA:BB:CC:DD:{i:02X}",
8611 IdentifierType.IP_ADDRESS: "192.168.1.10",
8612 },
8613 )
8614 p.set_initialized()
8615 players.append(p)
8616
8617 controller._players = {p.player_id: p for p in players}
8618
8619 for p in players:
8620 await controller._delayed_protocol_evaluation(p.player_id)
8621
8622 # Each should have its own universal player (NOT merged)
8623 parent_ids = {p.protocol_parent_id for p in players}
8624 assert None not in parent_ids
8625 assert len(parent_ids) == 3
8626
8627 @pytest.mark.asyncio
8628 async def test_same_domain_same_mac_get_separate_universals(self, mock_mass: MagicMock) -> None:
8629 """
8630 Test that two snapcast instances with the same ARP-resolved MAC stay separate.
8631
8632 Scenario: Two snapcast clients on the same Mac mini. Both have distinct
8633 locally-administered MACs but ARP resolves both to the same real hardware MAC.
8634 They should each get their own universal player, not be merged.
8635 """
8636 controller, _ = self._setup_e2e_controller(mock_mass)
8637
8638 snap_provider = MockProvider("snapcast", mass=mock_mass)
8639 snap1 = MockPlayer(
8640 snap_provider,
8641 "ma_cea0b4ed2221",
8642 "Mac-mini-15269.local",
8643 player_type=PlayerType.PROTOCOL,
8644 identifiers={
8645 # ARP-enriched: both resolve to same real MAC
8646 IdentifierType.MAC_ADDRESS: "D0:11:E5:00:67:2F",
8647 IdentifierType.IP_ADDRESS: "192.168.1.42",
8648 },
8649 )
8650 snap2 = MockPlayer(
8651 snap_provider,
8652 "ma_cea0b4ed2220",
8653 "Mac-mini-63197.local",
8654 player_type=PlayerType.PROTOCOL,
8655 identifiers={
8656 IdentifierType.MAC_ADDRESS: "D0:11:E5:00:67:2F",
8657 IdentifierType.IP_ADDRESS: "192.168.1.42",
8658 },
8659 )
8660 snap1._attr_available = False
8661 snap1._cache.clear()
8662 snap1.update_state(signal_event=False)
8663 snap2._attr_available = False
8664 snap2._cache.clear()
8665 snap2.update_state(signal_event=False)
8666 snap1.set_initialized()
8667 snap2.set_initialized()
8668
8669 controller._players = {"ma_cea0b4ed2221": snap1, "ma_cea0b4ed2220": snap2}
8670
8671 await controller._delayed_protocol_evaluation("ma_cea0b4ed2221")
8672 await controller._delayed_protocol_evaluation("ma_cea0b4ed2220")
8673
8674 # Each should have its own universal player
8675 assert snap1.protocol_parent_id is not None
8676 assert snap2.protocol_parent_id is not None
8677 assert snap1.protocol_parent_id != snap2.protocol_parent_id
8678
8679 @pytest.mark.asyncio
8680 async def test_mixed_protocols_plus_duplicate_creates_correct_topology(
8681 self, mock_mass: MagicMock
8682 ) -> None:
8683 """
8684 Test that mixed protocols + duplicate create correct player topology.
8685
8686 Scenario:
8687 - Device has AirPlay, DLNA, and Chromecast protocols
8688 - Plus a second AirPlay instance (duplicate)
8689 Result:
8690 - One universal player with AirPlay + DLNA + Chromecast
8691 - One separate universal player for the second AirPlay
8692 """
8693 controller, _ = self._setup_e2e_controller(mock_mass)
8694
8695 ap_provider = MockProvider("airplay", mass=mock_mass)
8696 dlna_provider = MockProvider("dlna", mass=mock_mass)
8697 cc_provider = MockProvider("chromecast", mass=mock_mass)
8698
8699 ap1 = MockPlayer(
8700 ap_provider,
8701 "ap_1",
8702 "AirPlay",
8703 player_type=PlayerType.PROTOCOL,
8704 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8705 )
8706 ap1.set_initialized()
8707
8708 dlna1 = MockPlayer(
8709 dlna_provider,
8710 "dlna_1",
8711 "DLNA",
8712 player_type=PlayerType.PROTOCOL,
8713 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8714 )
8715 dlna1.set_initialized()
8716
8717 cc1 = MockPlayer(
8718 cc_provider,
8719 "cc_1",
8720 "Chromecast",
8721 player_type=PlayerType.PROTOCOL,
8722 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8723 )
8724 cc1.set_initialized()
8725
8726 ap2 = MockPlayer(
8727 ap_provider,
8728 "ap_2",
8729 "AirPlay Duplicate",
8730 player_type=PlayerType.PROTOCOL,
8731 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
8732 )
8733 ap2.set_initialized()
8734
8735 controller._players = {
8736 "ap_1": ap1,
8737 "dlna_1": dlna1,
8738 "cc_1": cc1,
8739 "ap_2": ap2,
8740 }
8741
8742 # ap1 goes through delayed eval - finds dlna1 and cc1 as matching
8743 # (different domains), creates universal player with all three
8744 await controller._delayed_protocol_evaluation("ap_1")
8745
8746 assert ap1.protocol_parent_id is not None
8747 assert dlna1.protocol_parent_id == ap1.protocol_parent_id
8748 assert cc1.protocol_parent_id == ap1.protocol_parent_id
8749 shared_up_id = ap1.protocol_parent_id
8750
8751 # ap2 goes through delayed eval - finds universal player but is rejected
8752 await controller._delayed_protocol_evaluation("ap_2")
8753
8754 assert ap2.protocol_parent_id is not None
8755 assert ap2.protocol_parent_id != shared_up_id
8756
8757 # Shared universal player should have 3 protocols
8758 shared_up = controller._players[shared_up_id]
8759 shared_domains = {link.protocol_domain for link in shared_up.linked_output_protocols}
8760 assert shared_domains == {"airplay", "dlna", "chromecast"}
8761
8762
8763class TestEndToEndUniversalPlayerId:
8764 """
8765 End-to-end tests for the minted player id of a universal player.
8766
8767 Regression tests for music-assistant/support#5888: the id used to be derived from
8768 whichever device identifiers happened to be available when the wrapper was created,
8769 so a re-created wrapper could silently change id and orphan the entities API
8770 consumers (such as the Home Assistant integration) bind to it. These tests drive
8771 the real evaluation path against a config store that persists what the flow writes.
8772 """
8773
8774 @staticmethod
8775 def _setup_controller(
8776 mock_mass: MagicMock,
8777 ) -> tuple[PlayerController, dict[str, Any]]:
8778 """
8779 Wire a controller, the universal player provider and a persisting config store.
8780
8781 :param mock_mass: The mocked MusicAssistant instance to wire.
8782 :return: Tuple of (controller, backing config store).
8783 """
8784 controller = PlayerController(mock_mass)
8785 up_provider = create_mock_universal_provider(mock_mass)
8786 mock_mass.get_providers = MagicMock(return_value=[up_provider])
8787
8788 store: dict[str, Any] = {CONF_PLAYERS: {}}
8789 _wire_nested_config(mock_mass, store)
8790 mock_mass.config.create_default_player_config = MagicMock(
8791 side_effect=lambda *args, **kwargs: _fake_create_default_player_config(
8792 store, *args, **kwargs
8793 )
8794 )
8795 mock_mass.config.get_base_player_config.return_value = create_mock_config("Test")
8796
8797 async def fake_register_or_update(player: Player) -> None:
8798 controller._players[player.player_id] = player
8799 player.set_initialized()
8800
8801 mock_mass.players = MagicMock()
8802 mock_mass.players.register_or_update = AsyncMock(side_effect=fake_register_or_update)
8803 mock_mass.players.get_player = lambda pid, *_args, **_kwargs: controller._players.get(pid)
8804 return controller, store
8805
8806 @staticmethod
8807 def _make_airplay_player(
8808 mock_mass: MagicMock, player_id: str, name: str, identifiers: dict[IdentifierType, str]
8809 ) -> MockPlayer:
8810 """Return an unlinked AirPlay protocol player."""
8811 player = MockPlayer(
8812 MockProvider("airplay", mass=mock_mass),
8813 player_id,
8814 name,
8815 player_type=PlayerType.PROTOCOL,
8816 identifiers=identifiers,
8817 )
8818 player.set_initialized()
8819 return player
8820
8821 async def test_id_survives_recreation_with_other_identifiers(
8822 self, mock_mass: MagicMock
8823 ) -> None:
8824 """
8825 A re-created wrapper keeps its id when a different set of identifiers is known.
8826
8827 The first evaluation only knows the device's MAC, the second only its UUID.
8828 The derived key changed along with that, taking the player id with it.
8829 """
8830 controller, store = self._setup_controller(mock_mass)
8831 first = self._make_airplay_player(
8832 mock_mass, "ap_1", "Living Room", {IdentifierType.MAC_ADDRESS: "54:78:C9:E6:0D:A0"}
8833 )
8834 controller._players = {"ap_1": first}
8835
8836 await controller._delayed_protocol_evaluation("ap_1")
8837
8838 universal_id = first.protocol_parent_id
8839 assert universal_id is not None
8840 assert re.fullmatch(r"up[0-9a-f]{8}", universal_id)
8841
8842 # tear the wrapper down (its config is kept, as a non-permanent unregister does)
8843 # and bring the device back with only a UUID to identify it by
8844 del controller._players[universal_id]
8845 second = self._make_airplay_player(
8846 mock_mass,
8847 "ap_1",
8848 "Living Room",
8849 {IdentifierType.UUID: "12345678-1234-1234-1234-123456789abc"},
8850 )
8851 controller._players = {"ap_1": second}
8852
8853 await controller._delayed_protocol_evaluation("ap_1")
8854
8855 assert second.protocol_parent_id == universal_id
8856 assert universal_id in controller._players
8857 assert store[CONF_PLAYERS]["ap_1"]["values"][CONF_PROTOCOL_PARENT_ID] == universal_id
8858
8859 async def test_wrappers_created_in_one_second_still_order(self, mock_mass: MagicMock) -> None:
8860 """
8861 Two wrappers created back to back get distinct creation timestamps.
8862
8863 A merge between them must be able to keep the older one, which it cannot do
8864 when both carry the same timestamp and the tiebreak falls back to the id.
8865 """
8866 controller, store = self._setup_controller(mock_mass)
8867 players = [
8868 self._make_airplay_player(
8869 mock_mass, f"ap_{index}", f"Speaker {index}", {IdentifierType.MAC_ADDRESS: mac}
8870 )
8871 for index, mac in enumerate(("54:78:C9:E6:0D:A0", "AA:BB:CC:DD:EE:FF"), start=1)
8872 ]
8873 controller._players = {player.player_id: player for player in players}
8874
8875 for player in players:
8876 await controller._delayed_protocol_evaluation(player.player_id)
8877
8878 created = [
8879 store[CONF_PLAYERS][player.protocol_parent_id]["values"][CONF_CREATED_AT]
8880 for player in players
8881 ]
8882 assert all(isinstance(value, int) for value in created)
8883 assert created[0] < created[1]
8884
8885 async def test_new_devices_get_distinct_minted_ids(self, mock_mass: MagicMock) -> None:
8886 """Devices that were never wrapped before each get their own minted id."""
8887 controller, _ = self._setup_controller(mock_mass)
8888 players = [
8889 self._make_airplay_player(
8890 mock_mass, f"ap_{index}", f"Speaker {index}", {IdentifierType.MAC_ADDRESS: mac}
8891 )
8892 for index, mac in enumerate(("54:78:C9:E6:0D:A0", "AA:BB:CC:DD:EE:FF"), start=1)
8893 ]
8894 controller._players = {player.player_id: player for player in players}
8895
8896 for player in players:
8897 await controller._delayed_protocol_evaluation(player.player_id)
8898
8899 universal_ids = [player.protocol_parent_id for player in players]
8900 assert all(pid and re.fullmatch(r"up[0-9a-f]{8}", pid) for pid in universal_ids)
8901 assert len(set(universal_ids)) == len(players)
8902
8903 async def test_duplicate_domain_gets_a_second_wrapper_with_a_parent_link(
8904 self, mock_mass: MagicMock
8905 ) -> None:
8906 """
8907 Two players of one protocol domain end up on two wrappers, both linked.
8908
8909 The handoff must persist a parent link for the second player as well,
8910 otherwise it silently stays unwrapped.
8911 """
8912 controller, store = self._setup_controller(mock_mass)
8913 identifiers = {IdentifierType.MAC_ADDRESS: "54:78:C9:E6:0D:A0"}
8914 ap1 = self._make_airplay_player(mock_mass, "ap_1", "Zone 1", identifiers)
8915 ap2 = self._make_airplay_player(mock_mass, "ap_2", "Zone 2", identifiers)
8916 controller._players = {"ap_1": ap1, "ap_2": ap2}
8917
8918 await controller._create_or_update_universal_player([ap1, ap2])
8919
8920 assert ap1.protocol_parent_id is not None
8921 assert ap2.protocol_parent_id is not None
8922 assert ap1.protocol_parent_id != ap2.protocol_parent_id
8923 for player in (ap1, ap2):
8924 stored = store[CONF_PLAYERS][player.player_id]["values"][CONF_PROTOCOL_PARENT_ID]
8925 assert stored == player.protocol_parent_id
8926
8927
8928class TestSiblingProtocolMatching:
8929 """
8930 Tests for sibling protocol matching via _match_via_linked_protocols.
8931
8932 When a native player (e.g., HEOS) doesn't have its own MAC/serial identifiers
8933 but has protocol players (e.g., AirPlay) already linked, a new protocol player
8934 (e.g., Sendspin bridge) should be matched to the native player through the
8935 shared identifiers of sibling protocols.
8936 """
8937
8938 def test_sendspin_matches_heos_via_airplay_sibling(self, mock_mass: MagicMock) -> None:
8939 """
8940 Test Sendspin links to HEOS through AirPlay's shared AIRPLAY_ID.
8941
8942 HEOS has no MAC/UUID identifiers. AirPlay is already linked to HEOS.
8943 Sendspin has AIRPLAY_ID matching AirPlay. Sibling matching should link
8944 Sendspin to HEOS.
8945 """
8946 controller = PlayerController(mock_mass)
8947
8948 # HEOS native player - no MAC, no serial, no UUID (just IP from discovery)
8949 heos_provider = MockProvider("heos", mass=mock_mass)
8950 heos_player = MockPlayer(
8951 heos_provider,
8952 "2140037800",
8953 "Denon AVR-X2700H",
8954 player_type=PlayerType.PLAYER,
8955 )
8956 heos_player._attr_supported_features = {PlayerFeature.VOLUME_SET, PlayerFeature.PLAY_MEDIA}
8957 heos_player._cache.clear()
8958 heos_player.set_initialized()
8959
8960 # AirPlay protocol player already linked to HEOS
8961 ap_provider = MockProvider("airplay", mass=mock_mass)
8962 ap_player = MockPlayer(
8963 ap_provider,
8964 "ap000678747b16",
8965 "Denon AVR-X2700H (AirPlay)",
8966 player_type=PlayerType.PROTOCOL,
8967 identifiers={
8968 IdentifierType.MAC_ADDRESS: "00:06:78:74:7B:16",
8969 IdentifierType.AIRPLAY_ID: "ap000678747b16",
8970 },
8971 )
8972 ap_player.set_initialized()
8973
8974 # Link AirPlay to HEOS
8975 controller._players = {
8976 "2140037800": heos_player,
8977 "ap000678747b16": ap_player,
8978 }
8979 controller._add_protocol_link(heos_player, ap_player, "airplay")
8980 assert ap_player.protocol_parent_id == "2140037800"
8981
8982 # Sendspin bridge with AIRPLAY_ID matching AirPlay
8983 spb_provider = MockProvider("sendspin", mass=mock_mass)
8984 spb_player = MockPlayer(
8985 spb_provider,
8986 "spb_000678747b16",
8987 "Denon AVR-X2700H (Sendspin)",
8988 player_type=PlayerType.PROTOCOL,
8989 identifiers={
8990 IdentifierType.MAC_ADDRESS: "00:06:78:74:7B:16",
8991 IdentifierType.AIRPLAY_ID: "ap000678747b16",
8992 },
8993 )
8994 spb_player.set_initialized()
8995 controller._players["spb_000678747b16"] = spb_player
8996
8997 # Direct identifier match would fail (HEOS has no identifiers)
8998 assert controller._identifiers_match(heos_player, spb_player, "sendspin") is False
8999
9000 # Sibling matching should succeed through AirPlay's identifiers
9001 assert controller._match_via_linked_protocols(heos_player, spb_player, "sendspin") is True
9002 assert spb_player.protocol_parent_id == "2140037800"
9003
9004 def test_sibling_match_no_linked_protocols(self, mock_mass: MagicMock) -> None:
9005 """Test sibling matching returns False when native player has no linked protocols."""
9006 controller = PlayerController(mock_mass)
9007
9008 heos_provider = MockProvider("heos", mass=mock_mass)
9009 heos_player = MockPlayer(
9010 heos_provider, "heos_1", "HEOS Player", player_type=PlayerType.PLAYER
9011 )
9012 heos_player.set_initialized()
9013
9014 spb_provider = MockProvider("sendspin", mass=mock_mass)
9015 spb_player = MockPlayer(
9016 spb_provider,
9017 "spb_1",
9018 "Sendspin",
9019 player_type=PlayerType.PROTOCOL,
9020 identifiers={IdentifierType.AIRPLAY_ID: "ap_1"},
9021 )
9022 spb_player.set_initialized()
9023
9024 controller._players = {"heos_1": heos_player, "spb_1": spb_player}
9025
9026 assert controller._match_via_linked_protocols(heos_player, spb_player, "sendspin") is False
9027
9028 def test_sibling_match_no_identifier_overlap(self, mock_mass: MagicMock) -> None:
9029 """Test sibling matching returns False when identifiers don't overlap."""
9030 controller = PlayerController(mock_mass)
9031
9032 heos_provider = MockProvider("heos", mass=mock_mass)
9033 heos_player = MockPlayer(
9034 heos_provider, "heos_1", "HEOS Player", player_type=PlayerType.PLAYER
9035 )
9036 heos_player.set_initialized()
9037
9038 # AirPlay with one MAC
9039 ap_provider = MockProvider("airplay", mass=mock_mass)
9040 ap_player = MockPlayer(
9041 ap_provider,
9042 "ap_1",
9043 "AirPlay",
9044 player_type=PlayerType.PROTOCOL,
9045 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
9046 )
9047 ap_player.set_initialized()
9048
9049 controller._players = {"heos_1": heos_player, "ap_1": ap_player}
9050 controller._add_protocol_link(heos_player, ap_player, "airplay")
9051
9052 # Sendspin with different MAC, no shared identifiers
9053 spb_provider = MockProvider("sendspin", mass=mock_mass)
9054 spb_player = MockPlayer(
9055 spb_provider,
9056 "spb_1",
9057 "Sendspin",
9058 player_type=PlayerType.PROTOCOL,
9059 identifiers={IdentifierType.MAC_ADDRESS: "11:22:33:44:55:66"},
9060 )
9061 spb_player.set_initialized()
9062 controller._players["spb_1"] = spb_player
9063
9064 assert controller._match_via_linked_protocols(heos_player, spb_player, "sendspin") is False
9065 assert spb_player.protocol_parent_id is None
9066
9067 def test_sibling_match_refuses_duplicate_domain(self, mock_mass: MagicMock) -> None:
9068 """Test sibling matching refuses link when domain is already active on native player."""
9069 controller = PlayerController(mock_mass)
9070
9071 heos_provider = MockProvider("heos", mass=mock_mass)
9072 heos_player = MockPlayer(
9073 heos_provider, "heos_1", "HEOS Player", player_type=PlayerType.PLAYER
9074 )
9075 heos_player.set_initialized()
9076
9077 # AirPlay already linked
9078 ap_provider = MockProvider("airplay", mass=mock_mass)
9079 ap_player = MockPlayer(
9080 ap_provider,
9081 "ap_1",
9082 "AirPlay",
9083 player_type=PlayerType.PROTOCOL,
9084 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
9085 )
9086 ap_player.set_initialized()
9087
9088 controller._players = {"heos_1": heos_player, "ap_1": ap_player}
9089 controller._add_protocol_link(heos_player, ap_player, "airplay")
9090
9091 # Second AirPlay instance with same MAC - should be refused (duplicate domain)
9092 ap2 = MockPlayer(
9093 ap_provider,
9094 "ap_2",
9095 "AirPlay 2",
9096 player_type=PlayerType.PROTOCOL,
9097 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
9098 )
9099 ap2.set_initialized()
9100 controller._players["ap_2"] = ap2
9101
9102 assert controller._match_via_linked_protocols(heos_player, ap2, "airplay") is False
9103 assert ap2.protocol_parent_id is None
9104
9105 def test_try_link_to_existing_uses_sibling_matching(self, mock_mass: MagicMock) -> None:
9106 """Test _try_link_to_existing_player falls back to sibling matching."""
9107 controller = PlayerController(mock_mass)
9108
9109 # No cached protocol IDs for HEOS
9110 mock_mass.config.get = MagicMock(return_value=[])
9111
9112 heos_provider = MockProvider("heos", mass=mock_mass)
9113 heos_player = MockPlayer(
9114 heos_provider,
9115 "2140037800",
9116 "Denon AVR-X2700H",
9117 player_type=PlayerType.PLAYER,
9118 )
9119 heos_player.set_initialized()
9120
9121 ap_provider = MockProvider("airplay", mass=mock_mass)
9122 ap_player = MockPlayer(
9123 ap_provider,
9124 "ap000678747b16",
9125 "Denon AirPlay",
9126 player_type=PlayerType.PROTOCOL,
9127 identifiers={IdentifierType.AIRPLAY_ID: "ap000678747b16"},
9128 )
9129 ap_player.set_initialized()
9130
9131 controller._players = {
9132 "2140037800": heos_player,
9133 "ap000678747b16": ap_player,
9134 }
9135 controller._add_protocol_link(heos_player, ap_player, "airplay")
9136
9137 # Sendspin with matching AIRPLAY_ID
9138 spb_provider = MockProvider("sendspin", mass=mock_mass)
9139 spb_player = MockPlayer(
9140 spb_provider,
9141 "spb_000678747b16",
9142 "Denon Sendspin",
9143 player_type=PlayerType.PROTOCOL,
9144 identifiers={IdentifierType.AIRPLAY_ID: "ap000678747b16"},
9145 )
9146 spb_player.set_initialized()
9147 controller._players["spb_000678747b16"] = spb_player
9148
9149 # _try_link_to_existing_player should succeed via sibling matching
9150 result = controller._try_link_to_existing_player(spb_player, "sendspin")
9151 assert result is True
9152 assert spb_player.protocol_parent_id == "2140037800"
9153
9154
9155class TestDelayedEvalRetry:
9156 """
9157 Tests for the retry of _try_link_to_existing_player in _delayed_protocol_evaluation.
9158
9159 When a protocol player's delayed evaluation fires, native players may have
9160 registered during the delay period. The retry ensures they are checked before
9161 falling through to universal player creation.
9162 """
9163
9164 @pytest.mark.asyncio
9165 async def test_delayed_eval_links_to_native_registered_during_delay(
9166 self, mock_mass: MagicMock
9167 ) -> None:
9168 """
9169 Test delayed eval links to a native player that registered during the delay.
9170
9171 Scenario: Sendspin registers before HEOS. The delayed evaluation fires
9172 after HEOS has registered and has AirPlay linked. The retry should find
9173 HEOS via sibling matching and link Sendspin.
9174 """
9175 controller, _ = TestEndToEndDuplicateProtocol._setup_e2e_controller(mock_mass)
9176
9177 # No cached protocol IDs
9178 mock_mass.config.get = MagicMock(return_value=[])
9179
9180 # HEOS native player (no device identifiers)
9181 heos_provider = MockProvider("heos", mass=mock_mass)
9182 heos_player = MockPlayer(
9183 heos_provider,
9184 "2140037800",
9185 "Denon AVR-X2700H",
9186 player_type=PlayerType.PLAYER,
9187 )
9188 heos_player._attr_supported_features = {PlayerFeature.VOLUME_SET, PlayerFeature.PLAY_MEDIA}
9189 heos_player._cache.clear()
9190 heos_player.set_initialized()
9191
9192 # AirPlay already linked to HEOS
9193 ap_provider = MockProvider("airplay", mass=mock_mass)
9194 ap_player = MockPlayer(
9195 ap_provider,
9196 "ap000678747b16",
9197 "Denon AirPlay",
9198 player_type=PlayerType.PROTOCOL,
9199 identifiers={
9200 IdentifierType.MAC_ADDRESS: "00:06:78:74:7B:16",
9201 IdentifierType.AIRPLAY_ID: "ap000678747b16",
9202 },
9203 )
9204 ap_player.set_initialized()
9205 ap_player.set_protocol_parent_id("2140037800")
9206
9207 # Sendspin (not yet linked)
9208 spb_provider = MockProvider("sendspin", mass=mock_mass)
9209 spb_player = MockPlayer(
9210 spb_provider,
9211 "spb_000678747b16",
9212 "Denon Sendspin",
9213 player_type=PlayerType.PROTOCOL,
9214 identifiers={
9215 IdentifierType.MAC_ADDRESS: "00:06:78:74:7B:16",
9216 IdentifierType.AIRPLAY_ID: "ap000678747b16",
9217 },
9218 )
9219 spb_player.set_initialized()
9220
9221 # Set up players dict (simulating: HEOS registered during the delay)
9222 controller._players = {
9223 "2140037800": heos_player,
9224 "ap000678747b16": ap_player,
9225 "spb_000678747b16": spb_player,
9226 }
9227
9228 # Link AirPlay to HEOS
9229 controller._add_protocol_link(heos_player, ap_player, "airplay")
9230
9231 # Run delayed evaluation for Sendspin
9232 await controller._delayed_protocol_evaluation("spb_000678747b16")
9233
9234 # Sendspin should be linked to HEOS, not a new universal player
9235 assert spb_player.protocol_parent_id == "2140037800"
9236
9237 @pytest.mark.asyncio
9238 async def test_delayed_eval_skips_already_linked(self, mock_mass: MagicMock) -> None:
9239 """Test delayed eval returns early if protocol player was linked during the delay."""
9240 controller, _ = TestEndToEndDuplicateProtocol._setup_e2e_controller(mock_mass)
9241
9242 spb_provider = MockProvider("sendspin", mass=mock_mass)
9243 spb_player = MockPlayer(
9244 spb_provider,
9245 "spb_1",
9246 "Sendspin",
9247 player_type=PlayerType.PROTOCOL,
9248 identifiers={IdentifierType.AIRPLAY_ID: "ap_1"},
9249 )
9250 spb_player.set_initialized()
9251 # Simulate it was linked during the delay
9252 spb_player.set_protocol_parent_id("some_parent")
9253
9254 controller._players = {"spb_1": spb_player}
9255
9256 # Should return early without creating universal player
9257 await controller._delayed_protocol_evaluation("spb_1")
9258 assert spb_player.protocol_parent_id == "some_parent"
9259
9260
9261class TestNativePlayerSiblingLinking:
9262 """
9263 Tests for the second pass in _try_link_protocols_to_native using sibling matching.
9264
9265 After a native player registers and recovers cached protocol links, the second
9266 pass should match remaining unlinked protocol players via sibling identifiers.
9267 """
9268
9269 def test_native_registration_links_sendspin_via_sibling(self, mock_mass: MagicMock) -> None:
9270 """
9271 Test HEOS registration links Sendspin via AirPlay sibling identifiers.
9272
9273 Scenario: Sendspin registered before HEOS. When HEOS registers, the first
9274 pass can't match Sendspin (no direct identifiers). After recovering cached
9275 AirPlay link, the second pass matches Sendspin via AirPlay's AIRPLAY_ID.
9276 """
9277 controller = PlayerController(mock_mass)
9278
9279 # Set up config to return cached AirPlay link for HEOS
9280 def config_get_side_effect(key: str, default: object = None) -> object:
9281 if key == "players/2140037800/values/linked_protocol_ids":
9282 return ["ap000678747b16"]
9283 if key == "players/ap000678747b16":
9284 return {
9285 "provider": "airplay--test",
9286 "player_type": "protocol",
9287 "values": {"protocol_parent_id": "2140037800"},
9288 }
9289 if key == "players":
9290 return {
9291 "ap000678747b16": {
9292 "provider": "airplay--test",
9293 "player_type": "protocol",
9294 "values": {"protocol_parent_id": "2140037800"},
9295 },
9296 "spb_000678747b16": {
9297 "provider": "sendspin--test",
9298 "player_type": "protocol",
9299 "values": {},
9300 },
9301 }
9302 return default
9303
9304 mock_mass.config.get = MagicMock(side_effect=config_get_side_effect)
9305 mock_mass.get_provider = MagicMock(return_value=None)
9306
9307 # AirPlay protocol player (already registered, waiting for parent)
9308 ap_provider = MockProvider("airplay", mass=mock_mass)
9309 ap_player = MockPlayer(
9310 ap_provider,
9311 "ap000678747b16",
9312 "Denon AirPlay",
9313 player_type=PlayerType.PROTOCOL,
9314 identifiers={
9315 IdentifierType.MAC_ADDRESS: "00:06:78:74:7B:16",
9316 IdentifierType.AIRPLAY_ID: "ap000678747b16",
9317 },
9318 )
9319 ap_player.set_initialized()
9320 # AirPlay has cached parent set but parent hasn't registered yet
9321 ap_player.set_protocol_parent_id("2140037800")
9322
9323 # Sendspin (registered, not linked)
9324 spb_provider = MockProvider("sendspin", mass=mock_mass)
9325 spb_player = MockPlayer(
9326 spb_provider,
9327 "spb_000678747b16",
9328 "Denon Sendspin",
9329 player_type=PlayerType.PROTOCOL,
9330 identifiers={
9331 IdentifierType.MAC_ADDRESS: "00:06:78:74:7B:16",
9332 IdentifierType.AIRPLAY_ID: "ap000678747b16",
9333 },
9334 )
9335 spb_player.set_initialized()
9336
9337 # HEOS native player registers now
9338 heos_provider = MockProvider("heos", mass=mock_mass)
9339 heos_player = MockPlayer(
9340 heos_provider,
9341 "2140037800",
9342 "Denon AVR-X2700H",
9343 player_type=PlayerType.PLAYER,
9344 )
9345 heos_player._attr_supported_features = {PlayerFeature.VOLUME_SET, PlayerFeature.PLAY_MEDIA}
9346 heos_player._cache.clear()
9347 heos_player.set_initialized()
9348
9349 controller._players = {
9350 "ap000678747b16": ap_player,
9351 "spb_000678747b16": spb_player,
9352 "2140037800": heos_player,
9353 }
9354
9355 # Simulate what happens when HEOS registers
9356 controller._try_link_protocols_to_native(heos_player)
9357
9358 # AirPlay should be recovered from cache (linked_output_protocols)
9359 airplay_linked = any(
9360 link.output_protocol_id == "ap000678747b16"
9361 for link in heos_player.linked_output_protocols
9362 )
9363 assert airplay_linked, "AirPlay should be recovered from cached protocol links"
9364
9365 # Sendspin should be linked via sibling matching (second pass)
9366 assert spb_player.protocol_parent_id == "2140037800"
9367 sendspin_linked = any(
9368 link.output_protocol_id == "spb_000678747b16"
9369 for link in heos_player.linked_output_protocols
9370 )
9371 assert sendspin_linked, "Sendspin should be linked via sibling protocol matching"
9372
9373
9374class TestCachedProtocolLinkRecovery:
9375 """Tests for recovering protocol links from config."""
9376
9377 def test_recovered_links_are_applied_through_the_setter(self, mock_mass: MagicMock) -> None:
9378 """Recovery applies a single link per protocol domain through the setter."""
9379 controller = PlayerController(mock_mass)
9380
9381 protocol_configs = {
9382 "ap_first": {
9383 "provider": "airplay--first",
9384 "player_type": "protocol",
9385 "values": {"protocol_parent_id": "heos_player"},
9386 },
9387 "ap_second": {
9388 "provider": "airplay--second",
9389 "player_type": "protocol",
9390 "values": {"protocol_parent_id": "heos_player"},
9391 },
9392 }
9393
9394 def config_get_side_effect(key: str, default: object = None) -> object:
9395 if key == "players/heos_player/values/linked_protocol_ids":
9396 return ["ap_first", "ap_second"]
9397 if key == "players":
9398 return protocol_configs
9399 if key.startswith("players/"):
9400 return protocol_configs.get(key.split("/", maxsplit=1)[1])
9401 return default
9402
9403 mock_mass.config.get = MagicMock(side_effect=config_get_side_effect)
9404
9405 heos_player = MockPlayer(
9406 MockProvider("heos", mass=mock_mass),
9407 "heos_player",
9408 "Denon AVR-X2700H",
9409 )
9410
9411 controller._recover_cached_protocol_links(heos_player)
9412
9413 recovered = [link.output_protocol_id for link in heos_player.linked_output_protocols]
9414 assert recovered == ["ap_first"]
9415 mock_mass.players.trigger_player_update.assert_called_once_with("heos_player")
9416
9417 # a repeat pass has nothing left to recover, so no update is triggered
9418 controller._recover_cached_protocol_links(heos_player)
9419 mock_mass.players.trigger_player_update.assert_called_once_with("heos_player")
9420
9421 def test_protocol_owned_by_another_parent_is_not_recovered(self, mock_mass: MagicMock) -> None:
9422 """A cached protocol that another parent owns stays out of this parent's outputs."""
9423 controller = PlayerController(mock_mass)
9424
9425 store: dict[str, Any] = {
9426 CONF_PLAYERS: {
9427 "ap_shared": {
9428 "provider": "airplay--x",
9429 "player_type": "protocol",
9430 "values": {CONF_PROTOCOL_PARENT_ID: "cast_owner"},
9431 },
9432 "heos_player": {
9433 "provider": "heos--y",
9434 "player_type": "player",
9435 "values": {"linked_protocol_ids": ["ap_shared"]},
9436 },
9437 "cast_owner": {
9438 "provider": "chromecast--z",
9439 "player_type": "player",
9440 "values": {"linked_protocol_ids": ["ap_shared"]},
9441 },
9442 }
9443 }
9444 _wire_nested_config(mock_mass, store)
9445
9446 airplay = MockPlayer(
9447 MockProvider("airplay", mass=mock_mass),
9448 "ap_shared",
9449 "AVR (AirPlay)",
9450 player_type=PlayerType.PROTOCOL,
9451 )
9452 airplay.set_protocol_parent_id("cast_owner")
9453 owner = MockPlayer(MockProvider("chromecast", mass=mock_mass), "cast_owner", "AVR (Cast)")
9454 owner.set_linked_output_protocols(
9455 [LinkedOutputProtocol(output_protocol_id="ap_shared", protocol_domain="airplay")]
9456 )
9457 heos_player = MockPlayer(MockProvider("heos", mass=mock_mass), "heos_player", "AVR")
9458 controller._players = {
9459 "ap_shared": airplay,
9460 "cast_owner": owner,
9461 "heos_player": heos_player,
9462 }
9463
9464 controller._recover_cached_protocol_links(heos_player)
9465
9466 assert heos_player.linked_output_protocols == []
9467 # the domain slot stays free for this parent's own AirPlay endpoint
9468 assert not controller._parent_has_active_protocol_from_domain(heos_player, "airplay")
9469 assert airplay.protocol_parent_id == "cast_owner"
9470
9471 def test_unowned_and_own_cached_protocols_are_still_recovered(
9472 self, mock_mass: MagicMock
9473 ) -> None:
9474 """A disabled protocol without a live parent is still recovered for its parent."""
9475 controller = PlayerController(mock_mass)
9476
9477 store: dict[str, Any] = {
9478 CONF_PLAYERS: {
9479 "ap_disabled": {
9480 "provider": "airplay--x",
9481 "player_type": "protocol",
9482 "values": {CONF_PROTOCOL_PARENT_ID: "heos_player"},
9483 },
9484 "dlna_own": {
9485 "provider": "dlna--x",
9486 "player_type": "protocol",
9487 "values": {CONF_PROTOCOL_PARENT_ID: "heos_player"},
9488 },
9489 "heos_player": {
9490 "provider": "heos--y",
9491 "player_type": "player",
9492 "values": {"linked_protocol_ids": ["ap_disabled", "dlna_own"]},
9493 },
9494 }
9495 }
9496 _wire_nested_config(mock_mass, store)
9497
9498 # registered but not owned by anyone (e.g. freshly detached)
9499 dlna = MockPlayer(
9500 MockProvider("dlna", mass=mock_mass),
9501 "dlna_own",
9502 "AVR (DLNA)",
9503 player_type=PlayerType.PROTOCOL,
9504 )
9505 heos_player = MockPlayer(MockProvider("heos", mass=mock_mass), "heos_player", "AVR")
9506 controller._players = {"dlna_own": dlna, "heos_player": heos_player}
9507
9508 controller._recover_cached_protocol_links(heos_player)
9509
9510 recovered = {link.output_protocol_id for link in heos_player.linked_output_protocols}
9511 # ap_disabled is not registered at all, dlna_own is registered without a parent
9512 assert recovered == {"ap_disabled", "dlna_own"}
9513
9514 def test_protocol_waiting_for_its_owner_is_not_recovered(self, mock_mass: MagicMock) -> None:
9515 """A protocol whose owner has not registered yet is left to that owner."""
9516 controller = PlayerController(mock_mass)
9517
9518 store: dict[str, Any] = {
9519 CONF_PLAYERS: {
9520 "ap_shared": {
9521 "provider": "airplay--x",
9522 "player_type": "protocol",
9523 "values": {CONF_PROTOCOL_PARENT_ID: "cast_owner"},
9524 },
9525 "heos_player": {
9526 "provider": "heos--y",
9527 "player_type": "player",
9528 "values": {"linked_protocol_ids": ["ap_shared"]},
9529 },
9530 "cast_owner": {
9531 "provider": "chromecast--z",
9532 "player_type": "player",
9533 "values": {"linked_protocol_ids": ["ap_shared"]},
9534 },
9535 }
9536 }
9537 _wire_nested_config(mock_mass, store)
9538
9539 # the protocol is registered but still unparented: its owner is not registered yet
9540 airplay = MockPlayer(
9541 MockProvider("airplay", mass=mock_mass),
9542 "ap_shared",
9543 "AVR (AirPlay)",
9544 player_type=PlayerType.PROTOCOL,
9545 )
9546 heos_player = MockPlayer(MockProvider("heos", mass=mock_mass), "heos_player", "AVR")
9547 controller._players = {"ap_shared": airplay, "heos_player": heos_player}
9548
9549 controller._recover_cached_protocol_links(heos_player)
9550
9551 assert airplay.protocol_parent_id is None
9552 assert heos_player.linked_output_protocols == []
9553 assert not controller._parent_has_active_protocol_from_domain(heos_player, "airplay")
9554
9555 def test_bridge_owned_by_wrapper_leaves_native_domain_slot_free(
9556 self, mock_mass: MagicMock
9557 ) -> None:
9558 """
9559 A bridge that stayed with its wrapper is not recovered onto a native player.
9560
9561 A native player may carry a stale cached id for a bridge whose underlying
9562 connection it could not claim. The bridge follows that connection, so the
9563 native player must leave the domain slot free for its own bridge.
9564 """
9565 controller = PlayerController(mock_mass)
9566
9567 store: dict[str, Any] = {
9568 CONF_PLAYERS: {
9569 "cast_base": {
9570 "provider": "chromecast--x",
9571 "player_type": "protocol",
9572 "values": {CONF_PROTOCOL_PARENT_ID: STORED_UNIVERSAL_ID},
9573 },
9574 "spb_bridge": {
9575 "provider": "sendspin--y",
9576 "player_type": "protocol",
9577 "values": {
9578 CONF_PROTOCOL_PARENT_ID: "heos_player",
9579 CONF_UNDERLYING_PLAYER_ID: "cast_base",
9580 },
9581 },
9582 STORED_UNIVERSAL_ID: {
9583 "provider": "universal_player",
9584 "player_type": "player",
9585 "values": {"linked_protocol_ids": ["cast_base"]},
9586 },
9587 "heos_player": {
9588 "provider": "heos--z",
9589 "player_type": "player",
9590 "values": {"linked_protocol_ids": ["spb_bridge"]},
9591 },
9592 }
9593 }
9594 _wire_nested_config(mock_mass, store)
9595
9596 wrapper = _create_universal_player(
9597 mock_mass, STORED_UNIVERSAL_ID, "AVR (wrapper)", ["cast_base"]
9598 )
9599 base = MockPlayer(
9600 MockProvider("chromecast", mass=mock_mass),
9601 "cast_base",
9602 "AVR (Cast 2)",
9603 player_type=PlayerType.PROTOCOL,
9604 )
9605 base.set_protocol_parent_id(STORED_UNIVERSAL_ID)
9606 wrapper.set_linked_output_protocols(
9607 [LinkedOutputProtocol(output_protocol_id="cast_base", protocol_domain="chromecast")]
9608 )
9609 bridge = MockPlayer(
9610 MockProvider("sendspin", mass=mock_mass),
9611 "spb_bridge",
9612 "AVR (Bridge)",
9613 player_type=PlayerType.PROTOCOL,
9614 )
9615 bridge._attr_underlying_player_id = "cast_base"
9616 bridge.set_initialized()
9617 heos_player = MockPlayer(MockProvider("heos", mass=mock_mass), "heos_player", "AVR")
9618 controller._players = {
9619 STORED_UNIVERSAL_ID: wrapper,
9620 "cast_base": base,
9621 "spb_bridge": bridge,
9622 "heos_player": heos_player,
9623 }
9624
9625 # the bridge resolves via its underlying connection, so it joins the wrapper
9626 controller._try_link_protocol_to_native(bridge)
9627 assert bridge.protocol_parent_id == STORED_UNIVERSAL_ID
9628
9629 controller._recover_cached_protocol_links(heos_player)
9630
9631 assert heos_player.linked_output_protocols == []
9632 assert not controller._parent_has_active_protocol_from_domain(heos_player, "sendspin")
9633
9634 def test_claiming_a_protocol_clears_it_from_its_previous_parent(
9635 self, mock_mass: MagicMock
9636 ) -> None:
9637 """
9638 A parent loses its output entry for a protocol that another parent claims.
9639
9640 A bridge that registers before the connection it runs on has no owner to
9641 compare against yet, so a stale cached id still recovers it onto a native
9642 player. Once the connection registers and takes the bridge along, the native
9643 player must give up its entry instead of listing the bridge as well.
9644 """
9645 controller = PlayerController(mock_mass)
9646
9647 store: dict[str, Any] = {
9648 CONF_PLAYERS: {
9649 "cast_base": {
9650 "provider": "chromecast--x",
9651 "player_type": "protocol",
9652 "values": {CONF_PROTOCOL_PARENT_ID: STORED_UNIVERSAL_ID},
9653 },
9654 "spb_bridge": {
9655 "provider": "sendspin--y",
9656 "player_type": "protocol",
9657 "values": {
9658 CONF_PROTOCOL_PARENT_ID: "heos_player",
9659 CONF_UNDERLYING_PLAYER_ID: "cast_base",
9660 },
9661 },
9662 STORED_UNIVERSAL_ID: {
9663 "provider": "universal_player",
9664 "player_type": "player",
9665 "values": {"linked_protocol_ids": ["cast_base"]},
9666 },
9667 "heos_player": {
9668 "provider": "heos--z",
9669 "player_type": "player",
9670 "values": {"linked_protocol_ids": ["spb_bridge"]},
9671 },
9672 }
9673 }
9674 _wire_nested_config(mock_mass, store)
9675
9676 wrapper = _create_universal_player(
9677 mock_mass, STORED_UNIVERSAL_ID, "AVR (wrapper)", ["cast_base"]
9678 )
9679 bridge = MockPlayer(
9680 MockProvider("sendspin", mass=mock_mass),
9681 "spb_bridge",
9682 "AVR (Bridge)",
9683 player_type=PlayerType.PROTOCOL,
9684 )
9685 bridge._attr_underlying_player_id = "cast_base"
9686 bridge.set_initialized()
9687 heos_player = MockPlayer(MockProvider("heos", mass=mock_mass), "heos_player", "AVR")
9688 controller._players = {
9689 STORED_UNIVERSAL_ID: wrapper,
9690 "spb_bridge": bridge,
9691 "heos_player": heos_player,
9692 }
9693
9694 # the bridge has no owner yet, so the cached id recovers it onto the native player
9695 controller._recover_cached_protocol_links(heos_player)
9696 assert [link.output_protocol_id for link in heos_player.linked_output_protocols] == [
9697 "spb_bridge"
9698 ]
9699
9700 # the connection registers and joins the wrapper, taking the bridge with it
9701 base = MockPlayer(
9702 MockProvider("chromecast", mass=mock_mass),
9703 "cast_base",
9704 "AVR (Cast 2)",
9705 player_type=PlayerType.PROTOCOL,
9706 )
9707 controller._players["cast_base"] = base
9708 controller._try_link_protocol_to_native(base)
9709
9710 assert bridge.protocol_parent_id == STORED_UNIVERSAL_ID
9711 assert heos_player.linked_output_protocols == []
9712 assert not controller._parent_has_active_protocol_from_domain(heos_player, "sendspin")
9713 # the stale cached id is gone too, so the bridge is not offered here as disabled
9714 assert store[CONF_PLAYERS]["heos_player"]["values"]["linked_protocol_ids"] == []
9715
9716 def test_claiming_a_protocol_clears_universal_membership(self, mock_mass: MagicMock) -> None:
9717 """A wrapper that loses a protocol also gives up its stored membership."""
9718 controller = PlayerController(mock_mass)
9719
9720 store: dict[str, Any] = {
9721 CONF_PLAYERS: {
9722 "ap_shared": {
9723 "provider": "airplay--x",
9724 "player_type": "protocol",
9725 "values": {CONF_PROTOCOL_PARENT_ID: STORED_UNIVERSAL_ID},
9726 },
9727 STORED_UNIVERSAL_ID: {
9728 "provider": "universal_player",
9729 "player_type": "player",
9730 "values": {"linked_protocol_ids": ["ap_shared"]},
9731 },
9732 "heos_player": {
9733 "provider": "heos--z",
9734 "player_type": "player",
9735 "values": {},
9736 },
9737 }
9738 }
9739 _wire_nested_config(mock_mass, store)
9740
9741 wrapper = _create_universal_player(
9742 mock_mass, STORED_UNIVERSAL_ID, "AVR (wrapper)", ["ap_shared"]
9743 )
9744 wrapper.set_linked_output_protocols(
9745 [LinkedOutputProtocol(output_protocol_id="ap_shared", protocol_domain="airplay")]
9746 )
9747 airplay = MockPlayer(
9748 MockProvider("airplay", mass=mock_mass),
9749 "ap_shared",
9750 "AVR (AirPlay)",
9751 player_type=PlayerType.PROTOCOL,
9752 )
9753 airplay.set_protocol_parent_id(STORED_UNIVERSAL_ID)
9754 heos_player = MockPlayer(MockProvider("heos", mass=mock_mass), "heos_player", "AVR")
9755 controller._players = {
9756 STORED_UNIVERSAL_ID: wrapper,
9757 "ap_shared": airplay,
9758 "heos_player": heos_player,
9759 }
9760
9761 controller._add_protocol_link(heos_player, airplay, "airplay")
9762
9763 assert airplay.protocol_parent_id == "heos_player"
9764 assert wrapper.linked_output_protocols == []
9765 # the wrapper's stored membership is authoritative and gets written back on save,
9766 # so it has to give up the protocol there as well
9767 assert wrapper._protocol_player_ids == []
9768 assert store[CONF_PLAYERS][STORED_UNIVERSAL_ID]["values"]["linked_protocol_ids"] == []
9769
9770
9771class TestMultiMACMatching:
9772 """Tests for multi-MAC matching (reported MAC vs ARP MAC)."""
9773
9774 def test_match_on_reported_mac_when_arp_mac_differs(self, mock_mass: MagicMock) -> None:
9775 """Two players match when one's reported MAC equals the other's ARP-resolved MAC."""
9776 controller = PlayerController(mock_mass)
9777
9778 provider = MockProvider("test")
9779 # Player A has ARP-resolved MAC in identifiers, reported MAC saved in extra_data
9780 player_a = MockPlayer(
9781 provider,
9782 "player_a",
9783 "Player A",
9784 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
9785 )
9786 player_a.extra_data["reported_mac"] = "AA:BB:CC:DD:EE:02"
9787
9788 # Player B has a MAC that matches player_a's reported MAC
9789 player_b = MockPlayer(
9790 provider,
9791 "player_b",
9792 "Player B",
9793 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
9794 )
9795
9796 assert controller._identifiers_match(player_a, player_b) is True
9797
9798 def test_match_on_reported_mac_reverse(self, mock_mass: MagicMock) -> None:
9799 """Match when player_b's reported MAC matches player_a's ARP MAC."""
9800 controller = PlayerController(mock_mass)
9801
9802 provider = MockProvider("test")
9803 player_a = MockPlayer(
9804 provider,
9805 "player_a",
9806 "Player A",
9807 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
9808 )
9809
9810 player_b = MockPlayer(
9811 provider,
9812 "player_b",
9813 "Player B",
9814 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
9815 )
9816 player_b.extra_data["reported_mac"] = "AA:BB:CC:DD:EE:02"
9817
9818 assert controller._identifiers_match(player_a, player_b) is True
9819
9820 def test_no_match_when_both_macs_differ(self, mock_mass: MagicMock) -> None:
9821 """No match when all MACs differ between players."""
9822 controller = PlayerController(mock_mass)
9823
9824 provider = MockProvider("test")
9825 player_a = MockPlayer(
9826 provider,
9827 "player_a",
9828 "Player A",
9829 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
9830 )
9831 player_a.extra_data["reported_mac"] = "AA:BB:CC:DD:EE:02"
9832
9833 player_b = MockPlayer(
9834 provider,
9835 "player_b",
9836 "Player B",
9837 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:03"},
9838 )
9839 player_b.extra_data["reported_mac"] = "AA:BB:CC:DD:EE:04"
9840
9841 assert controller._identifiers_match(player_a, player_b) is False
9842
9843 def test_match_reported_mac_with_la_bit_normalization(self, mock_mass: MagicMock) -> None:
9844 """Reported MAC matching also applies LA bit normalization."""
9845 controller = PlayerController(mock_mass)
9846
9847 provider = MockProvider("test")
9848 # Player A has ARP MAC, reported MAC has LA bit set
9849 player_a = MockPlayer(
9850 provider,
9851 "player_a",
9852 "Player A",
9853 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
9854 )
9855 player_a.extra_data["reported_mac"] = "56:78:C9:E6:0D:A0" # LA variant
9856
9857 # Player B has the hardware MAC
9858 player_b = MockPlayer(
9859 provider,
9860 "player_b",
9861 "Player B",
9862 identifiers={IdentifierType.MAC_ADDRESS: "54:78:C9:E6:0D:A0"}, # real MAC
9863 )
9864
9865 assert controller._identifiers_match(player_a, player_b) is True
9866
9867
9868class TestProtocolParentIdPersistence:
9869 """Tests for protocol_parent_id persistence for all parent types."""
9870
9871 def test_parent_id_saved_for_universal_parent(self, mock_mass: MagicMock) -> None:
9872 """protocol_parent_id should be saved when linking to a universal player."""
9873 controller = PlayerController(mock_mass)
9874
9875 def _config_get(key: str, default: object = None) -> object:
9876 # Protocol player config must exist for _save_protocol_parent_id to write
9877 if key == "players/airplay_test":
9878 return {"enabled": True}
9879 return default if default is not None else []
9880
9881 mock_mass.config.get = MagicMock(side_effect=_config_get)
9882
9883 universal_provider = create_mock_universal_provider(mock_mass)
9884 parent = UniversalPlayer(
9885 provider=universal_provider,
9886 player_id="up_test",
9887 name="Test Universal",
9888 device_info=DeviceInfo(),
9889 protocol_player_ids=[],
9890 )
9891 parent.update_state(signal_event=False)
9892
9893 protocol_provider = MockProvider("airplay")
9894 protocol_player = MockPlayer(
9895 protocol_provider,
9896 "airplay_test",
9897 "AirPlay Test",
9898 player_type=PlayerType.PROTOCOL,
9899 )
9900
9901 controller._players = {
9902 "up_test": parent,
9903 "airplay_test": protocol_player,
9904 }
9905
9906 controller._add_protocol_link(parent, protocol_player, "airplay")
9907
9908 # Verify _save_protocol_parent_id was called (config.set with parent ID)
9909 config_set_calls = [
9910 call
9911 for call in mock_mass.config.set.call_args_list
9912 if "protocol_parent_id" in str(call)
9913 ]
9914 assert len(config_set_calls) >= 1, (
9915 "protocol_parent_id should be saved for universal player parents"
9916 )
9917
9918 def test_parent_id_cleared_for_universal_parent(self, mock_mass: MagicMock) -> None:
9919 """protocol_parent_id should be cleared when unlinking from a universal player."""
9920 controller = PlayerController(mock_mass)
9921 mock_mass.config.get = MagicMock(return_value={"enabled": True})
9922
9923 universal_provider = create_mock_universal_provider(mock_mass)
9924 parent = UniversalPlayer(
9925 provider=universal_provider,
9926 player_id="up_test",
9927 name="Test Universal",
9928 device_info=DeviceInfo(),
9929 protocol_player_ids=["airplay_test"],
9930 )
9931 parent.update_state(signal_event=False)
9932
9933 protocol_provider = MockProvider("airplay")
9934 protocol_player = MockPlayer(
9935 protocol_provider,
9936 "airplay_test",
9937 "AirPlay Test",
9938 player_type=PlayerType.PROTOCOL,
9939 )
9940 protocol_player.set_protocol_parent_id("up_test")
9941
9942 # Set up linked protocols
9943 parent.set_linked_output_protocols(
9944 [
9945 LinkedOutputProtocol(
9946 output_protocol_id="airplay_test",
9947 protocol_domain="airplay",
9948 priority=10,
9949 )
9950 ]
9951 )
9952
9953 controller._players = {
9954 "up_test": parent,
9955 "airplay_test": protocol_player,
9956 }
9957
9958 controller._remove_protocol_link(parent, "airplay_test")
9959
9960 # Verify protocol_parent_id was cleared in config
9961 config_set_calls = [
9962 call
9963 for call in mock_mass.config.set.call_args_list
9964 if "protocol_parent_id" in str(call) and call.args[1] is None
9965 ]
9966 assert len(config_set_calls) >= 1, (
9967 "protocol_parent_id should be cleared for universal player parents"
9968 )
9969
9970
9971class TestCleanupProtocolLinks:
9972 """Tests for protocol link cleanup on player removal."""
9973
9974 def test_cleanup_clears_config_parent_id(self, mock_mass: MagicMock) -> None:
9975 """When a universal player is removed, protocol parent_ids are cleared in config."""
9976 controller = PlayerController(mock_mass)
9977 mock_mass.config.get = MagicMock(return_value={"enabled": True})
9978
9979 universal_provider = create_mock_universal_provider(mock_mass)
9980 parent = UniversalPlayer(
9981 provider=universal_provider,
9982 player_id="up_test",
9983 name="Test Universal",
9984 device_info=DeviceInfo(),
9985 protocol_player_ids=["airplay_test"],
9986 )
9987 parent.update_state(signal_event=False)
9988
9989 protocol_provider = MockProvider("airplay")
9990 protocol_player = MockPlayer(
9991 protocol_provider,
9992 "airplay_test",
9993 "AirPlay Test",
9994 player_type=PlayerType.PROTOCOL,
9995 )
9996 protocol_player.set_protocol_parent_id("up_test")
9997
9998 parent.set_linked_output_protocols(
9999 [
10000 LinkedOutputProtocol(
10001 output_protocol_id="airplay_test",
10002 protocol_domain="airplay",
10003 priority=10,
10004 )
10005 ]
10006 )
10007
10008 controller._players = {
10009 "up_test": parent,
10010 "airplay_test": protocol_player,
10011 }
10012
10013 controller._cleanup_protocol_links(parent)
10014
10015 # Verify protocol_parent_id was cleared in config
10016 config_set_calls = [
10017 call
10018 for call in mock_mass.config.set.call_args_list
10019 if "airplay_test" in str(call) and "protocol_parent_id" in str(call)
10020 ]
10021 assert len(config_set_calls) >= 1, (
10022 "protocol_parent_id should be cleared in config on parent removal"
10023 )
10024 # Verify in-memory parent cleared
10025 assert protocol_player.protocol_parent_id is None
10026
10027 def test_cleanup_native_parent_schedules_protocol_re_evaluation(
10028 self, mock_mass: MagicMock
10029 ) -> None:
10030 """Permanent native parent removal should reset links and reschedule protocols."""
10031 controller = PlayerController(mock_mass)
10032
10033 config_store: dict[str, object] = {
10034 "players/sonos_1": {"enabled": True},
10035 "players/sonos_1/values/linked_protocol_ids": ["airplay_live", "dlna_cached"],
10036 "players/airplay_live": {"enabled": True},
10037 "players/dlna_cached": {"enabled": True},
10038 }
10039
10040 def config_get(key: str, default: object = None) -> object:
10041 return config_store.get(key, default)
10042
10043 def config_set(key: str, value: object) -> None:
10044 config_store[key] = value
10045
10046 mock_mass.config.get = MagicMock(side_effect=config_get)
10047 mock_mass.config.set = MagicMock(side_effect=config_set)
10048
10049 native_provider = MockProvider("sonos", mass=mock_mass)
10050 parent = MockPlayer(
10051 native_provider,
10052 "sonos_1",
10053 "Sonos",
10054 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
10055 )
10056
10057 protocol_provider = MockProvider("airplay", mass=mock_mass)
10058 protocol_player = MockPlayer(
10059 protocol_provider,
10060 "airplay_live",
10061 "AirPlay Test",
10062 player_type=PlayerType.PROTOCOL,
10063 )
10064 protocol_player.set_protocol_parent_id("sonos_1")
10065
10066 parent.set_linked_output_protocols(
10067 [
10068 LinkedOutputProtocol(
10069 output_protocol_id="airplay_live",
10070 protocol_domain="airplay",
10071 priority=10,
10072 )
10073 ]
10074 )
10075
10076 controller._players = {
10077 "sonos_1": parent,
10078 "airplay_live": protocol_player,
10079 }
10080
10081 with patch.object(controller, "_schedule_protocol_evaluation") as mock_schedule:
10082 controller._cleanup_protocol_links(parent)
10083
10084 assert protocol_player.protocol_parent_id is None
10085 assert config_store["players/airplay_live/values/protocol_parent_id"] is None
10086 assert config_store["players/dlna_cached/values/protocol_parent_id"] is None
10087 mock_schedule.assert_called_once_with(protocol_player)
10088
10089 def test_cleanup_universal_parent_clears_cached_only_protocol_ids(
10090 self, mock_mass: MagicMock
10091 ) -> None:
10092 """Universal cleanup should also clear cached protocol ids that are not active."""
10093 controller = PlayerController(mock_mass)
10094
10095 config_store: dict[str, object] = {
10096 "players/up_test": {"enabled": True},
10097 "players/airplay_live": {"enabled": True},
10098 "players/dlna_cached": {"enabled": True},
10099 }
10100
10101 def config_get(key: str, default: object = None) -> object:
10102 return config_store.get(key, default)
10103
10104 def config_set(key: str, value: object) -> None:
10105 config_store[key] = value
10106
10107 mock_mass.config.get = MagicMock(side_effect=config_get)
10108 mock_mass.config.set = MagicMock(side_effect=config_set)
10109
10110 universal_provider = create_mock_universal_provider(mock_mass)
10111 parent = UniversalPlayer(
10112 provider=universal_provider,
10113 player_id="up_test",
10114 name="Test Universal",
10115 device_info=DeviceInfo(),
10116 protocol_player_ids=["airplay_live", "dlna_cached"],
10117 )
10118 parent.update_state(signal_event=False)
10119
10120 protocol_provider = MockProvider("airplay", mass=mock_mass)
10121 protocol_player = MockPlayer(
10122 protocol_provider,
10123 "airplay_live",
10124 "AirPlay Test",
10125 player_type=PlayerType.PROTOCOL,
10126 )
10127 protocol_player.set_protocol_parent_id("up_test")
10128
10129 parent.set_linked_output_protocols(
10130 [
10131 LinkedOutputProtocol(
10132 output_protocol_id="airplay_live",
10133 protocol_domain="airplay",
10134 priority=10,
10135 )
10136 ]
10137 )
10138
10139 controller._players = {
10140 "up_test": parent,
10141 "airplay_live": protocol_player,
10142 }
10143
10144 with patch.object(controller, "_schedule_protocol_evaluation") as mock_schedule:
10145 controller._cleanup_protocol_links(parent)
10146
10147 assert protocol_player.protocol_parent_id is None
10148 assert config_store["players/airplay_live/values/protocol_parent_id"] is None
10149 assert config_store["players/dlna_cached/values/protocol_parent_id"] is None
10150 mock_schedule.assert_called_once_with(protocol_player)
10151
10152
10153class TestDetachProtocolChildren:
10154 """Tests for detaching protocol players of a removed player that is not registered."""
10155
10156 @staticmethod
10157 def _setup(
10158 mock_mass: MagicMock, live_parent_id: str | None
10159 ) -> tuple[PlayerController, MockPlayer, dict[str, object]]:
10160 """Set up a registered protocol player whose (unregistered) parent is sonos_1."""
10161 controller = PlayerController(mock_mass)
10162
10163 config_store: dict[str, object] = {
10164 "players": {"sonos_1": {}, "airplay_live": {}},
10165 "players/sonos_1": {"enabled": True},
10166 "players/airplay_live": {"enabled": True},
10167 "players/airplay_live/values/protocol_parent_id": "sonos_1",
10168 }
10169
10170 mock_mass.config.get = MagicMock(
10171 side_effect=lambda key, default=None: config_store.get(key, default)
10172 )
10173 mock_mass.config.set = MagicMock(
10174 side_effect=lambda key, value: config_store.__setitem__(key, value)
10175 )
10176
10177 protocol_player = MockPlayer(
10178 MockProvider("airplay", mass=mock_mass),
10179 "airplay_live",
10180 "AirPlay Test",
10181 player_type=PlayerType.PROTOCOL,
10182 )
10183 protocol_player.set_protocol_parent_id(live_parent_id)
10184 controller._players = {"airplay_live": protocol_player}
10185 return controller, protocol_player, config_store
10186
10187 def test_detach_on_removal_of_an_unregistered_parent(self, mock_mass: MagicMock) -> None:
10188 """Removing a player that is no longer registered detaches its protocol player."""
10189 controller, protocol_player, config_store = self._setup(mock_mass, "sonos_1")
10190
10191 with patch.object(controller, "_schedule_protocol_evaluation") as mock_schedule:
10192 controller.delete_player_config("sonos_1")
10193
10194 assert protocol_player.protocol_parent_id is None
10195 assert config_store["players/airplay_live/values/protocol_parent_id"] is None
10196 mock_schedule.assert_called_once_with(protocol_player)
10197
10198 def test_detach_of_a_protocol_player_waiting_for_its_parent(self, mock_mass: MagicMock) -> None:
10199 """A protocol player that only has the parent link in its config is detached too."""
10200 controller, protocol_player, config_store = self._setup(mock_mass, None)
10201
10202 with patch.object(controller, "_schedule_protocol_evaluation") as mock_schedule:
10203 controller.delete_player_config("sonos_1")
10204
10205 assert config_store["players/airplay_live/values/protocol_parent_id"] is None
10206 mock_schedule.assert_called_once_with(protocol_player)
10207
10208 def test_detach_skips_a_protocol_player_of_another_parent(self, mock_mass: MagicMock) -> None:
10209 """A protocol player that already moved to another parent keeps its link."""
10210 controller, protocol_player, config_store = self._setup(mock_mass, "cast_1")
10211
10212 with patch.object(controller, "_schedule_protocol_evaluation") as mock_schedule:
10213 controller.delete_player_config("sonos_1")
10214
10215 assert protocol_player.protocol_parent_id == "cast_1"
10216 assert config_store["players/airplay_live/values/protocol_parent_id"] == "sonos_1"
10217 mock_schedule.assert_not_called()
10218
10219
10220class TestStaleConfigMigration:
10221 """Tests for protocol parent link repair on startup."""
10222
10223 def test_clears_stale_parent_ids(self, mock_mass: MagicMock) -> None:
10224 """Stale parent_ids pointing to deleted players are cleared on startup."""
10225 controller = PlayerController(mock_mass)
10226
10227 # Set up config with a protocol player pointing to a deleted universal player
10228 mock_mass.config.get = MagicMock(
10229 return_value={
10230 "airplay_test": {
10231 "player_type": "protocol",
10232 "values": {
10233 "protocol_parent_id": "up_deleted_player",
10234 },
10235 },
10236 "heos_player": {
10237 "player_type": "player",
10238 "values": {},
10239 },
10240 }
10241 )
10242
10243 controller._repair_protocol_parent_links()
10244
10245 # Verify the stale parent_id was cleared
10246 mock_mass.config.set.assert_any_call(
10247 "players/airplay_test/values/protocol_parent_id",
10248 None,
10249 )
10250 mock_mass.config.set_player_type.assert_not_called()
10251
10252 def test_keeps_valid_parent_ids(self, mock_mass: MagicMock) -> None:
10253 """Valid parent_ids pointing to existing players are preserved."""
10254 controller = PlayerController(mock_mass)
10255
10256 mock_mass.config.get = MagicMock(
10257 return_value={
10258 "airplay_test": {
10259 "player_type": "protocol",
10260 "values": {
10261 "protocol_parent_id": "up_valid_player",
10262 },
10263 },
10264 "up_valid_player": {
10265 "player_type": "group",
10266 "provider": "universal_player",
10267 "values": {},
10268 },
10269 }
10270 )
10271
10272 controller._repair_protocol_parent_links()
10273
10274 # Verify no set calls were made to clear the parent_id
10275 for call in mock_mass.config.set.call_args_list:
10276 assert "protocol_parent_id" not in str(call), "Valid parent_id should not be cleared"
10277 mock_mass.config.set_player_type.assert_not_called()
10278
10279 def test_heals_stale_player_type_of_linked_child(self, mock_mass: MagicMock) -> None:
10280 """A parented child whose player_type was corrupted is healed back to protocol."""
10281 controller = PlayerController(mock_mass)
10282
10283 mock_mass.config.get = MagicMock(
10284 return_value={
10285 "squeezelite_child": {
10286 "player_type": "player",
10287 "values": {
10288 "protocol_parent_id": "up_valid_player",
10289 },
10290 },
10291 "up_valid_player": {
10292 "player_type": "group",
10293 "provider": "universal_player",
10294 "values": {},
10295 },
10296 }
10297 )
10298
10299 controller._repair_protocol_parent_links()
10300
10301 mock_mass.config.set_player_type.assert_called_once_with(
10302 "squeezelite_child", PlayerType.PROTOCOL
10303 )
10304
10305 def test_native_registration_clears_stale_parent_link(self, mock_mass: MagicMock) -> None:
10306 """A player registering with a non-protocol type drops its leftover parent link."""
10307 controller = PlayerController(mock_mass)
10308 provider = MockProvider("sendspin", mass=mock_mass)
10309 player = MockPlayer(provider, "web_player", "Web Player", player_type=PlayerType.PLAYER)
10310
10311 config_values = {
10312 f"{CONF_PLAYERS}/web_player": {"player_type": "player"},
10313 f"{CONF_PLAYERS}/web_player/values/protocol_parent_id": "up_old_parent",
10314 }
10315 mock_mass.config.get = MagicMock(
10316 side_effect=lambda key, default=None: config_values.get(key, default)
10317 )
10318
10319 with patch.object(controller, "_try_link_protocols_to_native"):
10320 controller._evaluate_protocol_links(player)
10321
10322 mock_mass.config.set.assert_any_call(
10323 f"{CONF_PLAYERS}/web_player/values/protocol_parent_id",
10324 None,
10325 )
10326
10327
10328class TestUniversalPlayerRestoreOrphanCleanup:
10329 """Tests for UniversalPlayerProvider._restore_player membership repair behavior."""
10330
10331 @staticmethod
10332 def _setup_config_get(
10333 mock_mass: MagicMock,
10334 universal_id: str,
10335 linked_protocol_ids: list[str],
10336 protocol_configs: dict[str, dict[str, object]],
10337 ) -> None:
10338 """Wire mass.config.get to return universal/protocol configs by key."""
10339 universal_conf = {
10340 "values": {
10341 "linked_protocol_ids": list(linked_protocol_ids),
10342 "device_identifiers": {},
10343 "device_info": {},
10344 },
10345 "name": "Test Universal",
10346 }
10347 all_configs: dict[str, object] = {universal_id: universal_conf, **protocol_configs}
10348
10349 def _get(key: str, default: object = None) -> object:
10350 if key == CONF_PLAYERS:
10351 return all_configs
10352 if key.startswith(f"{CONF_PLAYERS}/"):
10353 pid = key.split("/", 1)[1]
10354 return all_configs.get(pid, default)
10355 return default
10356
10357 mock_mass.config.get.side_effect = _get
10358
10359 @pytest.mark.asyncio
10360 async def test_orphan_protocol_dropped_but_configs_kept(self, mock_mass: MagicMock) -> None:
10361 """Orphan protocol is dropped from membership without deleting any config."""
10362 provider = create_mock_universal_provider(mock_mass)
10363 universal_id = "up_test"
10364 orphan_id = "spb_orphan"
10365
10366 self._setup_config_get(
10367 mock_mass,
10368 universal_id,
10369 [orphan_id],
10370 {
10371 orphan_id: {
10372 "player_type": "protocol",
10373 "values": {"protocol_parent_id": None},
10374 },
10375 },
10376 )
10377 mock_mass.players = MagicMock()
10378 mock_mass.players.get_player = MagicMock(return_value=None)
10379 mock_mass.players.delete_player_config = MagicMock()
10380 mock_mass.players.unregister = AsyncMock()
10381 mock_mass.players.register_or_update = AsyncMock()
10382 mock_mass.config.remove_player_config = AsyncMock()
10383
10384 await provider._restore_player(universal_id)
10385
10386 # Neither the orphan's config nor the universal's config is deleted
10387 mock_mass.players.delete_player_config.assert_not_called()
10388 mock_mass.players.unregister.assert_not_called()
10389 mock_mass.config.remove_player_config.assert_not_called()
10390 # With no valid protocols left, the universal is simply not restored
10391 mock_mass.players.register_or_update.assert_not_called()
10392
10393 @pytest.mark.asyncio
10394 async def test_valid_protocol_kept_and_no_cleanup(self, mock_mass: MagicMock) -> None:
10395 """Protocol with a valid protocol_parent_id is kept and no cleanup runs."""
10396 provider = create_mock_universal_provider(mock_mass)
10397 universal_id = "up_test"
10398 protocol_id = "spb_valid"
10399
10400 self._setup_config_get(
10401 mock_mass,
10402 universal_id,
10403 [protocol_id],
10404 {
10405 protocol_id: {
10406 "player_type": "protocol",
10407 "values": {"protocol_parent_id": universal_id},
10408 },
10409 },
10410 )
10411 mock_mass.players = MagicMock()
10412 mock_mass.players.get_player = MagicMock(return_value=None)
10413 mock_mass.players.delete_player_config = MagicMock()
10414 mock_mass.players.unregister = AsyncMock()
10415 mock_mass.players.register_or_update = AsyncMock()
10416 mock_mass.config.remove_player_config = AsyncMock()
10417 mock_mass.config.get_base_player_config.return_value = create_mock_config("Test Universal")
10418
10419 await provider._restore_player(universal_id)
10420
10421 mock_mass.players.delete_player_config.assert_not_called()
10422 mock_mass.players.unregister.assert_not_called()
10423 mock_mass.config.remove_player_config.assert_not_called()
10424 # Universal is constructed and registered with the valid protocol kept
10425 mock_mass.players.register_or_update.assert_awaited_once()
10426 registered = mock_mass.players.register_or_update.call_args.args[0]
10427 assert protocol_id in registered._protocol_player_ids
10428
10429 @pytest.mark.asyncio
10430 async def test_restore_keeps_linked_protocol_after_startup_type_rewrite(
10431 self, mock_mass: MagicMock
10432 ) -> None:
10433 """A linked protocol whose type was rewritten must not delete its universal config."""
10434 provider = create_mock_universal_provider(mock_mass)
10435 universal_id = "upe45f0170ef67"
10436 protocol_id = "e4:5f:01:70:ef:67"
10437 universal_config: dict[str, Any] = {
10438 "player_id": universal_id,
10439 "provider": "universal_player",
10440 "player_type": "player",
10441 "enabled": True,
10442 "name": "WC-Player",
10443 "default_name": "solarium-bath-sl",
10444 "values": {
10445 "hide_in_ui": True,
10446 "announce_volume_min": 55,
10447 "announce_volume_max": 98,
10448 "play_media_overrides_group": False,
10449 "linked_protocol_ids": [protocol_id],
10450 "device_identifiers": {},
10451 "device_info": {},
10452 },
10453 }
10454 configs: dict[str, dict[str, Any]] = {
10455 universal_id: universal_config,
10456 protocol_id: {
10457 "player_id": protocol_id,
10458 "provider": "squeezelite",
10459 "player_type": "player",
10460 "enabled": True,
10461 "values": {"protocol_parent_id": universal_id},
10462 },
10463 }
10464
10465 def _config_get(key: str, default: object = None) -> object:
10466 if key == CONF_PLAYERS:
10467 return configs
10468 if key.startswith(f"{CONF_PLAYERS}/"):
10469 pid = key.split("/", 1)[1]
10470 return configs.get(pid, default)
10471 return default
10472
10473 mock_mass.config.get.side_effect = _config_get
10474 mock_mass.config.remove_player_config = AsyncMock()
10475 mock_mass.config.get_base_player_config.return_value = create_mock_config("WC-Player")
10476 mock_mass.players = MagicMock()
10477 mock_mass.players.get_player = MagicMock(return_value=None)
10478 mock_mass.players.delete_player_config = MagicMock()
10479 mock_mass.players.unregister = AsyncMock()
10480 mock_mass.players.register_or_update = AsyncMock()
10481
10482 await provider._restore_player(universal_id)
10483
10484 mock_mass.config.remove_player_config.assert_not_called()
10485 mock_mass.players.delete_player_config.assert_not_called()
10486 mock_mass.players.unregister.assert_not_called()
10487 mock_mass.players.register_or_update.assert_awaited_once()
10488 registered = mock_mass.players.register_or_update.call_args.args[0]
10489 assert protocol_id in registered._protocol_player_ids
10490 assert configs[universal_id]["values"]["hide_in_ui"] is True
10491 assert configs[universal_id]["values"]["announce_volume_min"] == 55
10492
10493 @pytest.mark.asyncio
10494 async def test_membership_augmented_from_child_parent_link(self, mock_mass: MagicMock) -> None:
10495 """A child whose parent link points at the universal is re-added to membership."""
10496 provider = create_mock_universal_provider(mock_mass)
10497 universal_id = "up_test"
10498 stored_id = "spb_stored"
10499 missing_id = "spb_missing"
10500
10501 self._setup_config_get(
10502 mock_mass,
10503 universal_id,
10504 [stored_id],
10505 {
10506 stored_id: {
10507 "player_type": "protocol",
10508 "values": {"protocol_parent_id": universal_id},
10509 },
10510 missing_id: {
10511 "player_type": "protocol",
10512 "values": {"protocol_parent_id": universal_id},
10513 },
10514 },
10515 )
10516 mock_mass.players = MagicMock()
10517 mock_mass.players.get_player = MagicMock(return_value=None)
10518 mock_mass.players.register_or_update = AsyncMock()
10519 mock_mass.config.remove_player_config = AsyncMock()
10520 mock_mass.config.get_base_player_config.return_value = create_mock_config("Test Universal")
10521
10522 await provider._restore_player(universal_id)
10523
10524 # The missing child is restored to membership and persisted
10525 mock_mass.config.set.assert_any_call(
10526 f"{CONF_PLAYERS}/{universal_id}/values/linked_protocol_ids",
10527 [stored_id, missing_id],
10528 )
10529 registered = mock_mass.players.register_or_update.call_args.args[0]
10530 assert registered._protocol_player_ids == [stored_id, missing_id]
10531
10532 @pytest.mark.asyncio
10533 async def test_universal_config_kept_when_protocol_moved_to_other_parent(
10534 self, mock_mass: MagicMock
10535 ) -> None:
10536 """A protocol that moved to another parent is dropped, universal config is kept."""
10537 provider = create_mock_universal_provider(mock_mass)
10538 universal_id = "up_test"
10539 protocol_id = "spb_moved"
10540
10541 self._setup_config_get(
10542 mock_mass,
10543 universal_id,
10544 [protocol_id],
10545 {
10546 protocol_id: {
10547 "player_type": "protocol",
10548 "values": {"protocol_parent_id": "up_other"},
10549 },
10550 },
10551 )
10552 mock_mass.players = MagicMock()
10553 mock_mass.players.get_player = MagicMock(return_value=None)
10554 mock_mass.players.register_or_update = AsyncMock()
10555 mock_mass.config.remove_player_config = AsyncMock()
10556
10557 await provider._restore_player(universal_id)
10558
10559 mock_mass.config.remove_player_config.assert_not_called()
10560 mock_mass.players.register_or_update.assert_not_called()
10561
10562 @pytest.mark.asyncio
10563 async def test_disabled_parent_reparents_and_disables_orphaned_protocols(
10564 self, mock_mass: MagicMock
10565 ) -> None:
10566 """
10567 Self-heal: stale UP whose protocols belong to a disabled native parent.
10568
10569 Restoring such a UP should skip the wrapper, restore each protocol's
10570 parent_id back to the rightful (disabled) native parent, cascade-disable
10571 each protocol so the next registration cycle doesn't rebuild the wrapper,
10572 and hand the wrapper's config over to the native parent before deleting it.
10573 """
10574 provider = create_mock_universal_provider(mock_mass)
10575 universal_id = "up_test"
10576 native_parent_id = "sonos_disabled"
10577 ap_id = "airplay_1"
10578 dlna_id = "dlna_1"
10579
10580 all_configs = {
10581 universal_id: {
10582 "values": {
10583 "linked_protocol_ids": [ap_id, dlna_id],
10584 "device_identifiers": {},
10585 "device_info": {},
10586 },
10587 "name": "Test UP",
10588 },
10589 native_parent_id: {
10590 "enabled": False,
10591 "provider": "sonos",
10592 "values": {"linked_protocol_ids": [ap_id, dlna_id]},
10593 },
10594 ap_id: {
10595 "player_type": "protocol",
10596 "enabled": True,
10597 "values": {"protocol_parent_id": universal_id},
10598 },
10599 dlna_id: {
10600 "player_type": "protocol",
10601 "enabled": True,
10602 "values": {"protocol_parent_id": universal_id},
10603 },
10604 }
10605
10606 def _config_get(key: str, default: object = None) -> object:
10607 if key == CONF_PLAYERS:
10608 return all_configs
10609 if key.startswith(f"{CONF_PLAYERS}/"):
10610 pid = key.split("/", 1)[1]
10611 return all_configs.get(pid, default)
10612 return default
10613
10614 mock_mass.config.get.side_effect = _config_get
10615 mock_mass.config.set = MagicMock()
10616 mock_mass.config.save_player_config = AsyncMock()
10617 mock_mass.config.remove_player_config = AsyncMock()
10618 mock_mass.players = MagicMock()
10619 mock_mass.players.get_player = MagicMock(return_value=None)
10620
10621 await provider._restore_player(universal_id)
10622
10623 # The wrapper is not restored; its settings are handed over to the
10624 # native parent and its now-obsolete config is deleted
10625 mock_mass.players._migrate_universal_player_config.assert_called_once_with(
10626 universal_id, native_parent_id
10627 )
10628 mock_mass.players.delete_player_config.assert_called_once_with(
10629 universal_id, replacement_player_id=native_parent_id
10630 )
10631
10632 # Each protocol's parent_id is restored to the disabled native parent
10633 parent_restorations = {
10634 call.args[0]: call.args[1]
10635 for call in mock_mass.config.set.call_args_list
10636 if "protocol_parent_id" in call.args[0]
10637 }
10638 assert parent_restorations == {
10639 f"{CONF_PLAYERS}/{ap_id}/values/protocol_parent_id": native_parent_id,
10640 f"{CONF_PLAYERS}/{dlna_id}/values/protocol_parent_id": native_parent_id,
10641 }
10642
10643 # Each protocol is cascade-disabled
10644 disabled_ids = {
10645 call.args[0] for call in mock_mass.config.save_player_config.await_args_list
10646 }
10647 assert disabled_ids == {ap_id, dlna_id}
10648
10649 @pytest.mark.asyncio
10650 async def test_universal_replaced_by_linkplay_shell(self, mock_mass: MagicMock) -> None:
10651 """A generic LinkPlay shell that owns DLNA+AirPlay children replaces the Universal."""
10652 provider = create_mock_universal_provider(mock_mass)
10653 universal_id = "up_edifier"
10654 shell_id = "wiim_uuid:FF97F002-783E-6505-6579-F15FFF97F002"
10655 ap_id = "airplay_edifier"
10656 dlna_id = "dlna_edifier"
10657
10658 all_configs = {
10659 universal_id: {
10660 "values": {
10661 "linked_protocol_ids": [ap_id, dlna_id],
10662 "device_identifiers": {},
10663 "device_info": {},
10664 },
10665 "name": "Edifier MS50A",
10666 },
10667 shell_id: {
10668 "enabled": True,
10669 "provider": "wiim",
10670 "player_type": "player",
10671 "values": {"linked_protocol_ids": [ap_id, dlna_id]},
10672 },
10673 ap_id: {
10674 "player_type": "protocol",
10675 "enabled": True,
10676 "values": {"protocol_parent_id": universal_id},
10677 },
10678 dlna_id: {
10679 "player_type": "protocol",
10680 "enabled": True,
10681 "values": {"protocol_parent_id": universal_id},
10682 },
10683 }
10684
10685 def _config_get(key: str, default: object = None) -> object:
10686 if key == CONF_PLAYERS:
10687 return all_configs
10688 if key.startswith(f"{CONF_PLAYERS}/"):
10689 pid = key.split("/", 1)[1]
10690 return all_configs.get(pid, default)
10691 return default
10692
10693 mock_mass.config.get.side_effect = _config_get
10694 mock_mass.config.set = MagicMock()
10695 mock_mass.config.save_player_config = AsyncMock()
10696 mock_mass.config.remove_player_config = AsyncMock()
10697 mock_mass.players = MagicMock()
10698 mock_mass.players.get_player = MagicMock(return_value=None)
10699 mock_mass.players.register_or_update = AsyncMock()
10700
10701 await provider._restore_player(universal_id)
10702
10703 # both protocol children are reparented from the Universal to the LinkPlay shell
10704 parent_restorations = {
10705 call.args[0]: call.args[1]
10706 for call in mock_mass.config.set.call_args_list
10707 if "protocol_parent_id" in call.args[0]
10708 }
10709 assert parent_restorations == {
10710 f"{CONF_PLAYERS}/{ap_id}/values/protocol_parent_id": shell_id,
10711 f"{CONF_PLAYERS}/{dlna_id}/values/protocol_parent_id": shell_id,
10712 }
10713 # the Universal's saved config/name/DSP/preference and group refs migrate to the
10714 # shell, and the now-obsolete Universal is removed
10715 mock_mass.players._migrate_universal_player_config.assert_called_once_with(
10716 universal_id, shell_id
10717 )
10718 mock_mass.players.delete_player_config.assert_called_once_with(
10719 universal_id, replacement_player_id=shell_id
10720 )
10721
10722 @pytest.mark.asyncio
10723 async def test_protocols_reparented_to_their_own_native_claimer(
10724 self, mock_mass: MagicMock
10725 ) -> None:
10726 """Each protocol is reparented to the native player that claims it, not the first found."""
10727 provider = create_mock_universal_provider(mock_mass)
10728 universal_id = "up_test"
10729 ap_id = "airplay_1"
10730 slimproto_id = "slimproto_1"
10731
10732 all_configs = {
10733 universal_id: {
10734 "values": {
10735 "linked_protocol_ids": [ap_id, slimproto_id],
10736 "device_identifiers": {},
10737 "device_info": {},
10738 },
10739 "name": "Test UP",
10740 },
10741 "native_a": {
10742 "provider": "dlna",
10743 "values": {"linked_protocol_ids": [ap_id]},
10744 },
10745 "native_b": {
10746 "provider": "squeezelite",
10747 "values": {"linked_protocol_ids": [slimproto_id]},
10748 },
10749 ap_id: {
10750 "player_type": "protocol",
10751 "values": {"protocol_parent_id": universal_id},
10752 },
10753 slimproto_id: {
10754 "player_type": "protocol",
10755 "values": {"protocol_parent_id": universal_id},
10756 },
10757 }
10758
10759 def _config_get(key: str, default: object = None) -> object:
10760 if key == CONF_PLAYERS:
10761 return all_configs
10762 if key.startswith(f"{CONF_PLAYERS}/"):
10763 pid = key.split("/", 1)[1]
10764 return all_configs.get(pid, default)
10765 return default
10766
10767 mock_mass.config.get.side_effect = _config_get
10768 mock_mass.config.set = MagicMock()
10769 mock_mass.config.save_player_config = AsyncMock()
10770 mock_mass.config.remove_player_config = AsyncMock()
10771 mock_mass.players = MagicMock()
10772 mock_mass.players.get_player = MagicMock(return_value=None)
10773 mock_mass.players.register_or_update = AsyncMock()
10774
10775 await provider._restore_player(universal_id)
10776
10777 mock_mass.players.register_or_update.assert_not_called()
10778 parent_restorations = {
10779 call.args[0]: call.args[1]
10780 for call in mock_mass.config.set.call_args_list
10781 if "protocol_parent_id" in call.args[0]
10782 }
10783 assert parent_restorations == {
10784 f"{CONF_PLAYERS}/{ap_id}/values/protocol_parent_id": "native_a",
10785 f"{CONF_PLAYERS}/{slimproto_id}/values/protocol_parent_id": "native_b",
10786 }
10787 for call in mock_mass.config.save_player_config.await_args_list:
10788 assert call.args[1] == {ATTR_ENABLED: False}
10789 # The wrapper's settings are handed to the first claimer, then its
10790 # config is deleted
10791 mock_mass.players._migrate_universal_player_config.assert_called_once_with(
10792 universal_id, "native_a"
10793 )
10794 mock_mass.players.delete_player_config.assert_called_once_with(
10795 universal_id, replacement_player_id="native_a"
10796 )
10797
10798 @pytest.mark.asyncio
10799 async def test_restore_native_claims_carries_config_and_deletes_wrapper(
10800 self, mock_mass: MagicMock
10801 ) -> None:
10802 """The wrapper's user settings move to the native claimer and its config is deleted."""
10803 universal_id = "up_old"
10804 native_id = "cast_1"
10805 ap_id = "ap_1"
10806 store: dict[str, Any] = {
10807 CONF_PLAYERS: {
10808 universal_id: {
10809 "provider": "universal_player",
10810 "enabled": True,
10811 "name": "Living Room",
10812 "default_name": "Soundbar (Universal)",
10813 "values": {
10814 "hide_in_ui": True,
10815 "volume_control": "up_volume_control",
10816 "linked_protocol_ids": [ap_id],
10817 "device_identifiers": {"mac_address": "AA:BB:CC:DD:EE:FF"},
10818 "device_info": {"model": "Test", "manufacturer": "Test"},
10819 },
10820 },
10821 native_id: {
10822 "provider": "cast",
10823 "enabled": True,
10824 "name": "Soundbar",
10825 "default_name": "Soundbar",
10826 "values": {
10827 "volume_control": "native",
10828 "linked_protocol_ids": [ap_id],
10829 },
10830 },
10831 ap_id: {
10832 "player_type": "protocol",
10833 "enabled": True,
10834 "values": {"protocol_parent_id": universal_id},
10835 },
10836 "group_1": {
10837 "provider": "sync_group",
10838 "enabled": True,
10839 "values": {
10840 "group_members": [universal_id, "other"],
10841 "allowed_members": [universal_id],
10842 },
10843 },
10844 },
10845 CONF_PLAYER_DSP: {universal_id: {"enabled": True, "filters": []}},
10846 CONF_PLAYER_QUEUES: {
10847 universal_id: {"queue_id": universal_id, "values": {"crossfade_duration": 5}}
10848 },
10849 }
10850 _wire_nested_config(mock_mass, store)
10851 mock_mass.config.save_player_config = AsyncMock()
10852 scheduled_tasks: list[Awaitable[object]] = []
10853 mock_mass.create_task = MagicMock(
10854 side_effect=lambda task, *_a, **_kw: scheduled_tasks.append(task)
10855 )
10856 controller = PlayerController(mock_mass)
10857 controller._players = {}
10858 mock_mass.players = controller
10859 mock_mass.player_queues = MagicMock()
10860 provider = create_mock_universal_provider(mock_mass)
10861
10862 await provider._restore_player(universal_id)
10863
10864 players_tree = store[CONF_PLAYERS]
10865 # the protocol player is reparented to the native claimer
10866 assert players_tree[ap_id]["values"]["protocol_parent_id"] == native_id
10867 # the custom display name and user-set values moved onto the native player
10868 assert players_tree[native_id]["name"] == "Living Room"
10869 assert players_tree[native_id]["values"]["hide_in_ui"] is True
10870 # values the native player has explicitly set are not overwritten
10871 assert players_tree[native_id]["values"]["volume_control"] == "native"
10872 # wrapper bookkeeping values are not carried over
10873 assert "device_identifiers" not in players_tree[native_id]["values"]
10874 assert "device_info" not in players_tree[native_id]["values"]
10875 # DSP and queue settings moved onto the native player
10876 assert store[CONF_PLAYER_DSP] == {native_id: {"enabled": True, "filters": []}}
10877 assert store[CONF_PLAYER_QUEUES] == {
10878 native_id: {"queue_id": native_id, "values": {"crossfade_duration": 5}}
10879 }
10880 # group memberships that referenced the wrapper now point at the native player
10881 assert players_tree["group_1"]["values"]["group_members"] == [native_id, "other"]
10882 assert players_tree["group_1"]["values"]["allowed_members"] == [native_id]
10883 # the wrapper's own config entries are all gone
10884 assert universal_id not in players_tree
10885 # cached queue state of the wrapper is purged as well
10886 mock_mass.player_queues.purge_saved_queue.assert_called_once_with(universal_id)
10887 # the wrapper itself is not registered as a player
10888 assert universal_id not in controller._players
10889 for task in scheduled_tasks:
10890 await task
10891
10892 @pytest.mark.asyncio
10893 async def test_restore_native_claims_keeps_native_name_dsp_and_queue_values(
10894 self, mock_mass: MagicMock
10895 ) -> None:
10896 """Values explicitly set on the native player win over the wrapper's on restore."""
10897 universal_id = "up_old"
10898 native_id = "cast_1"
10899 ap_id = "ap_1"
10900 store: dict[str, Any] = {
10901 CONF_PLAYERS: {
10902 universal_id: {
10903 "provider": "universal_player",
10904 "enabled": True,
10905 "name": "Living Room",
10906 "default_name": "Soundbar (Universal)",
10907 "values": {"hide_in_ui": True, "linked_protocol_ids": [ap_id]},
10908 },
10909 native_id: {
10910 "provider": "cast",
10911 "enabled": True,
10912 "name": "Kitchen",
10913 "default_name": "Soundbar",
10914 "values": {"linked_protocol_ids": [ap_id]},
10915 },
10916 ap_id: {
10917 "player_type": "protocol",
10918 "enabled": True,
10919 "values": {"protocol_parent_id": universal_id},
10920 },
10921 },
10922 CONF_PLAYER_DSP: {
10923 universal_id: {"enabled": True, "filters": ["universal"]},
10924 native_id: {"enabled": False, "filters": ["native"]},
10925 },
10926 CONF_PLAYER_QUEUES: {
10927 universal_id: {
10928 "queue_id": universal_id,
10929 "values": {"crossfade_duration": 8, "autoplay_mode": "smart"},
10930 },
10931 native_id: {"queue_id": native_id, "values": {"crossfade_duration": 2}},
10932 },
10933 }
10934 _wire_nested_config(mock_mass, store)
10935 mock_mass.config.save_player_config = AsyncMock()
10936 scheduled_tasks: list[Awaitable[object]] = []
10937 mock_mass.create_task = MagicMock(
10938 side_effect=lambda task, *_a, **_kw: scheduled_tasks.append(task)
10939 )
10940 controller = PlayerController(mock_mass)
10941 controller._players = {}
10942 mock_mass.players = controller
10943 mock_mass.player_queues = MagicMock()
10944 provider = create_mock_universal_provider(mock_mass)
10945
10946 await provider._restore_player(universal_id)
10947
10948 players_tree = store[CONF_PLAYERS]
10949 # the native player's own custom name and DSP config win
10950 assert players_tree[native_id]["name"] == "Kitchen"
10951 assert store[CONF_PLAYER_DSP] == {native_id: {"enabled": False, "filters": ["native"]}}
10952 # queue values merge without overwriting the native queue's own values
10953 assert store[CONF_PLAYER_QUEUES] == {
10954 native_id: {
10955 "queue_id": native_id,
10956 "values": {"crossfade_duration": 2, "autoplay_mode": "smart"},
10957 }
10958 }
10959 # non-conflicting values still migrate and the wrapper config is gone
10960 assert players_tree[native_id]["values"]["hide_in_ui"] is True
10961 assert universal_id not in players_tree
10962 for task in scheduled_tasks:
10963 await task
10964
10965 @pytest.mark.asyncio
10966 async def test_restore_native_claims_keeps_config_while_wrapper_registered(
10967 self, mock_mass: MagicMock
10968 ) -> None:
10969 """No config carry-over/deletion while the wrapper is still registered."""
10970 provider = create_mock_universal_provider(mock_mass)
10971 universal_id = "up_test"
10972 ap_id = "airplay_1"
10973
10974 all_configs = {
10975 universal_id: {
10976 "values": {
10977 "linked_protocol_ids": [ap_id],
10978 "device_identifiers": {},
10979 "device_info": {},
10980 },
10981 "name": "Test UP",
10982 },
10983 "native_a": {
10984 "provider": "dlna",
10985 "values": {"linked_protocol_ids": [ap_id]},
10986 },
10987 ap_id: {
10988 "player_type": "protocol",
10989 "values": {"protocol_parent_id": universal_id},
10990 },
10991 }
10992
10993 def _config_get(key: str, default: object = None) -> object:
10994 if key == CONF_PLAYERS:
10995 return all_configs
10996 if key.startswith(f"{CONF_PLAYERS}/"):
10997 pid = key.split("/", 1)[1]
10998 return all_configs.get(pid, default)
10999 return default
11000
11001 mock_mass.config.get.side_effect = _config_get
11002 mock_mass.config.set = MagicMock()
11003 mock_mass.config.save_player_config = AsyncMock()
11004 mock_mass.players = MagicMock()
11005 mock_mass.players.get_player = MagicMock(return_value=MagicMock())
11006
11007 await provider._restore_player(universal_id)
11008
11009 # the protocol link repair still runs
11010 parent_restorations = {
11011 call.args[0]: call.args[1]
11012 for call in mock_mass.config.set.call_args_list
11013 if "protocol_parent_id" in call.args[0]
11014 }
11015 assert parent_restorations == {
11016 f"{CONF_PLAYERS}/{ap_id}/values/protocol_parent_id": "native_a",
11017 }
11018 # but the registered wrapper keeps its config and group memberships
11019 mock_mass.players._migrate_universal_player_config.assert_not_called()
11020 mock_mass.players.delete_player_config.assert_not_called()
11021 mock_mass.player_queues.on_player_remove.assert_not_called()
11022
11023
11024class TestParentDisableCascade:
11025 """Tests for cascading enable/disable from a native parent to its protocols."""
11026
11027 @staticmethod
11028 def _make_config(player_id: str, *, enabled: bool, provider: str = "sonos") -> MagicMock:
11029 """Build a minimal PlayerConfig mock for on_player_config_change."""
11030 config = MagicMock()
11031 config.player_id = player_id
11032 config.provider = provider
11033 config.enabled = enabled
11034 config.values = {}
11035 return config
11036
11037 @pytest.mark.asyncio
11038 async def test_disabling_native_parent_cascades_disable_to_linked_protocols(
11039 self, mock_mass: MagicMock
11040 ) -> None:
11041 """Disabling a native parent saves enabled=False for each linked protocol."""
11042 controller = PlayerController(mock_mass)
11043
11044 native_provider = MockProvider("sonos", mass=mock_mass)
11045 native_player = MockPlayer(
11046 native_provider,
11047 "sonos_native",
11048 "Native Speaker",
11049 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
11050 )
11051 # Bypass the power-off branch in on_player_config_change
11052 native_player._attr_available = False
11053 native_player.set_linked_output_protocols(
11054 [
11055 LinkedOutputProtocol(
11056 output_protocol_id="ap_1",
11057 protocol_domain="airplay",
11058 priority=10,
11059 ),
11060 LinkedOutputProtocol(
11061 output_protocol_id="dlna_1",
11062 protocol_domain="dlna",
11063 priority=20,
11064 ),
11065 ]
11066 )
11067 controller._players = {native_player.player_id: native_player}
11068
11069 protocol_configs = {
11070 "ap_1": {"enabled": True, "player_type": "protocol"},
11071 "dlna_1": {"enabled": True, "player_type": "protocol"},
11072 }
11073
11074 def _config_get(key: str, default: object = None) -> object:
11075 if key.startswith(f"{CONF_PLAYERS}/"):
11076 pid = key.split("/", 1)[1]
11077 return protocol_configs.get(pid, default)
11078 return default
11079
11080 mock_mass.config.get = MagicMock(side_effect=_config_get)
11081 mock_mass.config.save_player_config = MagicMock()
11082 mock_mass.create_task = MagicMock()
11083 mock_mass.get_provider = MagicMock(return_value=MagicMock(spec=PlayerProvider))
11084
11085 config = self._make_config(native_player.player_id, enabled=False)
11086
11087 await controller.on_player_config_change(config, {ATTR_ENABLED})
11088
11089 called = mock_mass.config.save_player_config.call_args_list
11090 assert {call.args[0] for call in called} == {"ap_1", "dlna_1"}
11091 for call in called:
11092 assert call.args[1] == {ATTR_ENABLED: False}
11093
11094 @pytest.mark.asyncio
11095 async def test_enabling_native_parent_cascades_enable_to_linked_protocols(
11096 self, mock_mass: MagicMock
11097 ) -> None:
11098 """Re-enabling a native parent saves enabled=True for each (currently disabled) protocol."""
11099 controller = PlayerController(mock_mass)
11100
11101 native_provider = MockProvider("sonos", mass=mock_mass)
11102 native_player = MockPlayer(
11103 native_provider,
11104 "sonos_native",
11105 "Native Speaker",
11106 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
11107 )
11108 native_player._attr_available = False
11109 native_player.set_linked_output_protocols(
11110 [
11111 LinkedOutputProtocol(
11112 output_protocol_id="ap_1",
11113 protocol_domain="airplay",
11114 priority=10,
11115 ),
11116 ]
11117 )
11118 controller._players = {native_player.player_id: native_player}
11119
11120 protocol_configs = {
11121 "ap_1": {"enabled": False, "player_type": "protocol"},
11122 }
11123
11124 def _config_get(key: str, default: object = None) -> object:
11125 if key.startswith(f"{CONF_PLAYERS}/"):
11126 pid = key.split("/", 1)[1]
11127 return protocol_configs.get(pid, default)
11128 return default
11129
11130 mock_mass.config.get = MagicMock(side_effect=_config_get)
11131 mock_mass.config.save_player_config = MagicMock()
11132 mock_mass.create_task = MagicMock()
11133 mock_mass.get_provider = MagicMock(return_value=MagicMock(spec=PlayerProvider))
11134
11135 config = self._make_config(native_player.player_id, enabled=True)
11136
11137 await controller.on_player_config_change(config, {ATTR_ENABLED})
11138
11139 mock_mass.config.save_player_config.assert_called_once_with("ap_1", {ATTR_ENABLED: True})
11140
11141 @pytest.mark.asyncio
11142 async def test_disabling_native_parent_falls_back_to_cached_protocol_ids(
11143 self, mock_mass: MagicMock
11144 ) -> None:
11145 """When the parent isn't registered, cascade uses cached linked_protocol_ids."""
11146 controller = PlayerController(mock_mass)
11147
11148 # Parent is not in _players (e.g. provider didn't register a disabled parent)
11149 controller._players = {}
11150
11151 cached_protocol_ids = ["ap_cached", "dlna_cached"]
11152 protocol_configs = {
11153 "ap_cached": {"enabled": True, "player_type": "protocol"},
11154 "dlna_cached": {"enabled": True, "player_type": "protocol"},
11155 }
11156
11157 def _config_get(key: str, default: object = None) -> object:
11158 if key == f"{CONF_PLAYERS}/unregistered_native/values/linked_protocol_ids":
11159 return list(cached_protocol_ids)
11160 if key.startswith(f"{CONF_PLAYERS}/"):
11161 pid = key.split("/", 1)[1]
11162 return protocol_configs.get(pid, default)
11163 return default
11164
11165 mock_mass.config.get = MagicMock(side_effect=_config_get)
11166 mock_mass.config.save_player_config = MagicMock()
11167 mock_mass.create_task = MagicMock()
11168 mock_mass.get_provider = MagicMock(return_value=MagicMock(spec=PlayerProvider))
11169
11170 config = self._make_config("unregistered_native", enabled=False)
11171
11172 await controller.on_player_config_change(config, {ATTR_ENABLED})
11173
11174 called_ids = {call.args[0] for call in mock_mass.config.save_player_config.call_args_list}
11175 assert called_ids == set(cached_protocol_ids)
11176
11177 @pytest.mark.asyncio
11178 async def test_toggling_protocol_player_does_not_cascade(self, mock_mass: MagicMock) -> None:
11179 """A PROTOCOL-type player flipping enabled must not trigger any cascade."""
11180 controller = PlayerController(mock_mass)
11181
11182 ap_provider = MockProvider("airplay", mass=mock_mass)
11183 ap_player = MockPlayer(
11184 ap_provider,
11185 "ap_1",
11186 "AirPlay",
11187 player_type=PlayerType.PROTOCOL,
11188 )
11189 ap_player._attr_available = False
11190 controller._players = {ap_player.player_id: ap_player}
11191
11192 mock_mass.config.save_player_config = MagicMock()
11193 mock_mass.create_task = MagicMock()
11194 mock_mass.get_provider = MagicMock(return_value=MagicMock(spec=PlayerProvider))
11195
11196 config = self._make_config(ap_player.player_id, enabled=False, provider="airplay")
11197
11198 await controller.on_player_config_change(config, {ATTR_ENABLED})
11199
11200 mock_mass.config.save_player_config.assert_not_called()
11201
11202
11203class TestDelayedEvalDisabledParentGuard:
11204 """Tests for the guard in _delayed_protocol_evaluation against disabled parents."""
11205
11206 @pytest.mark.asyncio
11207 async def test_skips_universal_creation_when_cached_parent_is_disabled(
11208 self, mock_mass: MagicMock
11209 ) -> None:
11210 """No universal player is created when the protocol's cached parent is disabled."""
11211 controller = PlayerController(mock_mass)
11212
11213 dlna_provider = MockProvider("dlna", mass=mock_mass)
11214 protocol_player = MockPlayer(
11215 dlna_provider,
11216 "dlna_orphan",
11217 "Orphan DLNA",
11218 player_type=PlayerType.PROTOCOL,
11219 )
11220 protocol_player.set_initialized()
11221 controller._players = {protocol_player.player_id: protocol_player}
11222
11223 cached_parent_id = "sonos_disabled"
11224
11225 def _config_get(key: str, default: object = None) -> object:
11226 if key.endswith("/protocol_parent_id"):
11227 return cached_parent_id
11228 if key == f"{CONF_PLAYERS}/{cached_parent_id}":
11229 return {"enabled": False, "provider": "sonos"}
11230 return default
11231
11232 mock_mass.config.get = MagicMock(side_effect=_config_get)
11233
11234 with (
11235 patch.object(controller, "_try_link_to_existing_player", return_value=False),
11236 patch.object(controller, "_find_matching_universal_player", return_value=None),
11237 patch.object(controller, "_create_or_update_universal_player") as mock_create_up,
11238 ):
11239 await controller._delayed_protocol_evaluation(protocol_player.player_id)
11240
11241 mock_create_up.assert_not_called()
11242
11243 @pytest.mark.asyncio
11244 async def test_creates_universal_when_cached_parent_is_enabled_but_offline(
11245 self, mock_mass: MagicMock
11246 ) -> None:
11247 """Sanity check: an enabled-but-unregistered cached parent still falls through."""
11248 controller = PlayerController(mock_mass)
11249
11250 dlna_provider = MockProvider("dlna", mass=mock_mass)
11251 protocol_player = MockPlayer(
11252 dlna_provider,
11253 "dlna_orphan",
11254 "Orphan DLNA",
11255 player_type=PlayerType.PROTOCOL,
11256 )
11257 protocol_player.set_initialized()
11258 controller._players = {protocol_player.player_id: protocol_player}
11259
11260 cached_parent_id = "sonos_offline"
11261
11262 def _config_get(key: str, default: object = None) -> object:
11263 if key.endswith("/protocol_parent_id"):
11264 return cached_parent_id
11265 if key == f"{CONF_PLAYERS}/{cached_parent_id}":
11266 return {"enabled": True, "provider": "sonos"}
11267 return default
11268
11269 mock_mass.config.get = MagicMock(side_effect=_config_get)
11270
11271 with (
11272 patch.object(controller, "_try_link_to_existing_player", return_value=False),
11273 patch.object(controller, "_find_matching_universal_player", return_value=None),
11274 patch.object(controller, "_create_or_update_universal_player") as mock_create_up,
11275 patch.object(
11276 controller,
11277 "_find_matching_protocol_players",
11278 return_value=[protocol_player],
11279 ),
11280 ):
11281 await controller._delayed_protocol_evaluation(protocol_player.player_id)
11282
11283 mock_create_up.assert_called_once()
11284
11285
11286class TestUniversalPlayerCurrentMedia:
11287 """Tests for current_media resolution while an output protocol is active."""
11288
11289 def test_current_media_surfaces_active_output_protocol(self, mock_mass: MagicMock) -> None:
11290 """
11291 While outputting via a protocol player, surface that player's raw current_media.
11292
11293 A sync group mirrors its leader's raw current_media to resolve the active queue
11294 item. When the leader is a universal player outputting via AirPlay, returning None
11295 here strands the group with a frozen current item (regression guard for grouped
11296 AirPlay live-metadata never refreshing).
11297 """
11298 protocol_provider = MockProvider("airplay", mass=mock_mass)
11299 protocol_player = MockPlayer(
11300 protocol_provider, "ap_1", "AirPlay", player_type=PlayerType.PROTOCOL
11301 )
11302 media = PlayerMedia(
11303 uri="http://x/flow/sess/queue_1/item_1/ap_1.flac", queue_item_id="item_1"
11304 )
11305 protocol_player._attr_current_media = media
11306
11307 universal = _create_universal_player(mock_mass, "up_1", "Universal", ["ap_1"])
11308 players = {"up_1": universal, "ap_1": protocol_player}
11309 mock_mass.players.get_player = MagicMock(side_effect=lambda pid: players.get(pid))
11310
11311 # without an active output protocol there is nothing to surface
11312 assert universal.current_media is None
11313
11314 universal.set_active_output_protocol("ap_1")
11315 assert universal.current_media is media
11316
11317 def test_current_media_none_for_native_output(self, mock_mass: MagicMock) -> None:
11318 """A native output protocol has no separate protocol player to surface."""
11319 universal = _create_universal_player(mock_mass, "up_1", "Universal", [])
11320 universal.set_active_output_protocol("native")
11321 assert universal.current_media is None
11322
11323
11324class TestSelfReferentialProtocolLinks:
11325 """
11326 Tests for the self-link bug when a Sendspin device changes player type.
11327
11328 A Sendspin device keeps a stable client_id (the MA player_id) across reflashes.
11329 When it first registers as a protocol player it gets wrapped in a universal
11330 player that caches that id as one of its protocols. If the device later
11331 reconnects as a non-protocol player (e.g. its roles changed to display-only)
11332 with the same id, the replace logic could link it to itself, hiding it.
11333 """
11334
11335 def test_add_protocol_link_refuses_self(self, mock_mass: MagicMock) -> None:
11336 """A player must never become its own protocol parent."""
11337 controller = PlayerController(mock_mass)
11338 provider = MockProvider("sendspin", mass=mock_mass)
11339 player = MockPlayer(provider, "esp_client", "ESP", player_type=PlayerType.PROTOCOL)
11340 mock_mass.players = controller
11341 controller._players = {"esp_client": player}
11342
11343 controller._add_protocol_link(player, player, "sendspin")
11344
11345 assert player.protocol_parent_id is None
11346 assert all(
11347 link.output_protocol_id != "esp_client" for link in player.linked_output_protocols
11348 )
11349
11350 def test_type_change_replaces_universal_without_self_link(self, mock_mass: MagicMock) -> None:
11351 """Replacing a universal player with the same-id native player must not self-link."""
11352 universal = _create_universal_player(
11353 mock_mass, "upespclient", "ESP", protocol_player_ids=["esp_client"]
11354 )
11355 display_provider = MockProvider("sendspin", mass=mock_mass)
11356 display_player = MockPlayer(
11357 display_provider, "esp_client", "ESP", player_type=PlayerType.DISPLAY
11358 )
11359
11360 store: dict[str, Any] = {"players/esp_client": {"enabled": True}}
11361 mock_mass.config.get.side_effect = lambda key, default=None: store.get(key, default)
11362 mock_mass.config.set.side_effect = lambda key, value: store.__setitem__(key, value)
11363 mock_mass.create_task = MagicMock()
11364 mock_mass.players = controller = PlayerController(mock_mass)
11365 controller._players = {"upespclient": universal, "esp_client": display_player}
11366
11367 controller._check_replace_universal_player(display_player)
11368
11369 assert display_player.protocol_parent_id is None
11370 assert store.get("players/esp_client/values/protocol_parent_id") != "esp_client"
11371 assert "esp_client" not in store.get("players/esp_client/values/linked_protocol_ids", [])
11372 # the obsolete universal player must not keep listing the native player,
11373 # or its permanent cleanup would re-evaluate it as an orphaned protocol
11374 assert "esp_client" not in universal._protocol_player_ids
11375
11376 async def test_migrate_clears_persisted_self_referential_link(self) -> None:
11377 """Config migration scrubs a self-referential link left by an older version."""
11378 config = ConfigController.__new__(ConfigController)
11379 config._data = {
11380 CONF_PLAYERS: {
11381 "esp_client": {
11382 "provider": "sendspin",
11383 "player_id": "esp_client",
11384 "values": {
11385 "protocol_parent_id": "esp_client",
11386 "linked_protocol_ids": ["esp_client"],
11387 },
11388 }
11389 }
11390 }
11391 await migrate(config._data)
11392
11393 values = config._data[CONF_PLAYERS]["esp_client"]["values"]
11394 assert values["protocol_parent_id"] is None
11395 assert "esp_client" not in values["linked_protocol_ids"]
11396
11397
11398class TestDerivedProtocolLinking:
11399 """
11400 Tests for derived protocol players (players with underlying_player_id set).
11401
11402 Derived protocol players (e.g. Sendspin bridges riding on an AirPlay player)
11403 resolve their parent deterministically via the underlying player instead of
11404 device identifier matching, and never seed universal players themselves.
11405 """
11406
11407 @staticmethod
11408 def _make_derived_player(
11409 mock_mass: MagicMock, player_id: str, underlying_player_id: str
11410 ) -> MockPlayer:
11411 """Create a derived protocol player without any device identifiers."""
11412 provider = MockProvider("sendspin", mass=mock_mass)
11413 player = MockPlayer(
11414 provider,
11415 player_id,
11416 f"Bridge {player_id}",
11417 player_type=PlayerType.PROTOCOL,
11418 )
11419 player._attr_underlying_player_id = underlying_player_id
11420 player.set_initialized()
11421 return player
11422
11423 def test_derived_links_to_parent_of_linked_underlying(self, mock_mass: MagicMock) -> None:
11424 """Test a derived player joins the parent of its (linked) underlying player."""
11425 controller = PlayerController(mock_mass)
11426 mock_mass.config.get = MagicMock(return_value=[])
11427
11428 native = MockPlayer(
11429 MockProvider("heos", mass=mock_mass), "native_1", "AVR", player_type=PlayerType.PLAYER
11430 )
11431 native.set_initialized()
11432 ap_player = MockPlayer(
11433 MockProvider("airplay", mass=mock_mass),
11434 "ap_1",
11435 "AVR AirPlay",
11436 player_type=PlayerType.PROTOCOL,
11437 )
11438 ap_player.set_initialized()
11439 controller._players = {"native_1": native, "ap_1": ap_player}
11440 controller._add_protocol_link(native, ap_player, "airplay")
11441
11442 # The derived player has NO identifiers - the edge alone must resolve it
11443 derived = self._make_derived_player(mock_mass, "spb_1", "ap_1")
11444 controller._players["spb_1"] = derived
11445 controller._try_link_protocol_to_native(derived)
11446
11447 assert derived.protocol_parent_id == "native_1"
11448 # the derived link carries its base output, the non-derived link does not
11449 links = {link.output_protocol_id: link for link in native.linked_output_protocols}
11450 assert links["spb_1"].derived_from == "ap_1"
11451 assert links["ap_1"].derived_from is None
11452
11453 def test_waiting_derived_follows_when_underlying_links(self, mock_mass: MagicMock) -> None:
11454 """Test a derived player that registered early follows once its underlying links."""
11455 controller = PlayerController(mock_mass)
11456 mock_mass.config.get = MagicMock(return_value=[])
11457
11458 native = MockPlayer(
11459 MockProvider("heos", mass=mock_mass), "native_1", "AVR", player_type=PlayerType.PLAYER
11460 )
11461 native.set_initialized()
11462 ap_player = MockPlayer(
11463 MockProvider("airplay", mass=mock_mass),
11464 "ap_1",
11465 "AVR AirPlay",
11466 player_type=PlayerType.PROTOCOL,
11467 )
11468 ap_player.set_initialized()
11469 derived = self._make_derived_player(mock_mass, "spb_1", "ap_1")
11470 controller._players = {"native_1": native, "ap_1": ap_player, "spb_1": derived}
11471
11472 # Underlying is not linked yet: derived stays unlinked
11473 controller._try_link_protocol_to_native(derived)
11474 assert derived.protocol_parent_id is None
11475
11476 # Linking the underlying player propagates to the waiting derived player
11477 controller._add_protocol_link(native, ap_player, "airplay")
11478 assert derived.protocol_parent_id == "native_1"
11479
11480 def test_derived_links_directly_to_non_protocol_underlying(self, mock_mass: MagicMock) -> None:
11481 """Test a derived player parents to the underlying player itself when not a protocol."""
11482 controller = PlayerController(mock_mass)
11483 mock_mass.config.get = MagicMock(side_effect=lambda _key, default=None: default)
11484
11485 local_player = MockPlayer(
11486 MockProvider("local_audio", mass=mock_mass),
11487 "local_1",
11488 "Dummy Output",
11489 player_type=PlayerType.PLAYER,
11490 )
11491 local_player.set_initialized()
11492 derived = self._make_derived_player(mock_mass, "spb_1", "local_1")
11493 controller._players = {"spb_1": derived, "local_1": local_player}
11494
11495 # The final derived pass of _try_link_protocols_to_native picks it up
11496 controller._try_link_protocols_to_native(local_player)
11497
11498 assert derived.protocol_parent_id == "local_1"
11499 # riding on the parent player itself normalizes the base output to "native"
11500 links = {link.output_protocol_id: link for link in local_player.linked_output_protocols}
11501 assert links["spb_1"].derived_from == "native"
11502
11503 @pytest.mark.asyncio
11504 async def test_derived_delayed_eval_never_creates_universal_player(
11505 self, mock_mass: MagicMock
11506 ) -> None:
11507 """Test delayed evaluation of a derived player never wraps it in a universal player."""
11508 controller, _ = TestEndToEndDuplicateProtocol._setup_e2e_controller(mock_mass)
11509 mock_mass.config.get = MagicMock(return_value=[])
11510
11511 derived = self._make_derived_player(mock_mass, "spb_1", "ap_missing")
11512 controller._players = {"spb_1": derived}
11513
11514 await controller._delayed_protocol_evaluation("spb_1")
11515
11516 assert derived.protocol_parent_id is None
11517 assert not any(pid.startswith("up") for pid in controller._players)
11518
11519 def test_derived_link_refused_on_domain_duplicate(self, mock_mass: MagicMock) -> None:
11520 """Test a derived player stays unlinked when the parent already has its domain."""
11521 controller = PlayerController(mock_mass)
11522 mock_mass.config.get = MagicMock(return_value=[])
11523
11524 native = MockPlayer(
11525 MockProvider("heos", mass=mock_mass), "native_1", "AVR", player_type=PlayerType.PLAYER
11526 )
11527 native.set_initialized()
11528 ap_player = MockPlayer(
11529 MockProvider("airplay", mass=mock_mass),
11530 "ap_1",
11531 "AVR AirPlay",
11532 player_type=PlayerType.PROTOCOL,
11533 )
11534 ap_player.set_initialized()
11535 other_sendspin = MockPlayer(
11536 MockProvider("sendspin", mass=mock_mass),
11537 "sendspin_native_client",
11538 "AVR Sendspin",
11539 player_type=PlayerType.PROTOCOL,
11540 )
11541 other_sendspin.set_initialized()
11542 controller._players = {
11543 "native_1": native,
11544 "ap_1": ap_player,
11545 "sendspin_native_client": other_sendspin,
11546 }
11547 controller._add_protocol_link(native, ap_player, "airplay")
11548 controller._add_protocol_link(native, other_sendspin, "sendspin")
11549
11550 derived = self._make_derived_player(mock_mass, "spb_1", "ap_1")
11551 controller._players["spb_1"] = derived
11552 controller._try_link_protocol_to_native(derived)
11553
11554 assert derived.protocol_parent_id is None
11555
11556 def test_derived_joins_universal_parent(self, mock_mass: MagicMock) -> None:
11557 """Test a derived player joins the universal player of its underlying player."""
11558 controller = PlayerController(mock_mass)
11559 mock_mass.config.get = MagicMock(return_value=[])
11560
11561 def _close_coro(coro: Any, *_args: Any, **_kwargs: Any) -> None:
11562 if hasattr(coro, "close"):
11563 coro.close()
11564
11565 mock_mass.create_task = MagicMock(side_effect=_close_coro)
11566
11567 universal = _create_universal_player(
11568 mock_mass,
11569 "up_aabbccddeeff",
11570 "Living Room Speaker",
11571 protocol_player_ids=["ap_1"],
11572 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
11573 )
11574 ap_player = MockPlayer(
11575 MockProvider("airplay", mass=mock_mass),
11576 "ap_1",
11577 "AirPlay Speaker",
11578 player_type=PlayerType.PROTOCOL,
11579 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:FF"},
11580 )
11581 ap_player.set_initialized()
11582 controller._players = {"up_aabbccddeeff": universal, "ap_1": ap_player}
11583 controller._add_protocol_link(universal, ap_player, "airplay")
11584
11585 derived = self._make_derived_player(mock_mass, "spb_1", "ap_1")
11586 controller._players["spb_1"] = derived
11587 controller._try_link_protocol_to_native(derived)
11588
11589 assert derived.protocol_parent_id == "up_aabbccddeeff"
11590 assert "spb_1" in universal._protocol_player_ids
11591
11592 @pytest.mark.parametrize("derived_first", [False, True])
11593 def test_derived_stays_with_refused_base_on_replacement(
11594 self, mock_mass: MagicMock, derived_first: bool
11595 ) -> None:
11596 """
11597 Keep a derived protocol with its base when the base's link is refused.
11598
11599 The native player absorbs the first universal player's cast protocol, so the
11600 second universal player's cast protocol is refused and stays behind. The
11601 sendspin bridge riding on it must stay behind too instead of moving on its own,
11602 whichever order the two links are listed in.
11603 """
11604 controller = PlayerController(mock_mass)
11605 up_provider = create_mock_universal_provider(mock_mass)
11606
11607 config_store: dict[str, Any] = {
11608 f"players/{player_id}": {"enabled": True}
11609 for player_id in ("native", "up_a", "up_b", "cc_1", "cc_2", "spb_2")
11610 }
11611 mock_mass.config.get = MagicMock(side_effect=config_store.get)
11612 mock_mass.config.set = MagicMock(side_effect=config_store.__setitem__)
11613 mock_mass.config.remove = MagicMock(side_effect=lambda key: config_store.pop(key, None))
11614 mock_mass.players = controller
11615 mock_mass.player_queues = MagicMock()
11616 mock_mass.call_later = MagicMock()
11617 mock_mass.loop = MagicMock()
11618 mock_mass.create_task = MagicMock()
11619
11620 mac = "AA:BB:CC:DD:EE:FF"
11621 identifiers = {IdentifierType.MAC_ADDRESS: mac}
11622 universals = {}
11623 for universal_id, protocol_ids in (("up_a", ["cc_1"]), ("up_b", ["cc_2", "spb_2"])):
11624 universal = UniversalPlayer(
11625 provider=up_provider,
11626 player_id=universal_id,
11627 name=f"Soundbar ({universal_id})",
11628 device_info=DeviceInfo(model="Test", manufacturer="Test"),
11629 protocol_player_ids=protocol_ids,
11630 )
11631 universal._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, mac)
11632 universal._cache.clear()
11633 universal.update_state(signal_event=False)
11634 universal.set_initialized()
11635 universals[universal_id] = universal
11636
11637 native = MockPlayer(
11638 MockProvider("linkplay", mass=mock_mass), "native", "Soundbar", identifiers=identifiers
11639 )
11640 native.set_initialized()
11641
11642 cast_provider = MockProvider("chromecast", mass=mock_mass)
11643 cast_players = {}
11644 for cast_id in ("cc_1", "cc_2"):
11645 cast_player = MockPlayer(
11646 cast_provider,
11647 cast_id,
11648 f"Cast {cast_id}",
11649 player_type=PlayerType.PROTOCOL,
11650 identifiers=identifiers,
11651 )
11652 cast_player.set_initialized()
11653 cast_players[cast_id] = cast_player
11654
11655 derived = self._make_derived_player(mock_mass, "spb_2", "cc_2")
11656
11657 controller._players = {
11658 **universals,
11659 **cast_players,
11660 "native": native,
11661 "spb_2": derived,
11662 }
11663 controller._add_protocol_link(universals["up_a"], cast_players["cc_1"], "chromecast")
11664 if derived_first:
11665 controller._add_protocol_link(universals["up_b"], derived, "sendspin")
11666 controller._add_protocol_link(universals["up_b"], cast_players["cc_2"], "chromecast")
11667 else:
11668 controller._add_protocol_link(universals["up_b"], cast_players["cc_2"], "chromecast")
11669 controller._add_protocol_link(universals["up_b"], derived, "sendspin")
11670
11671 controller._check_replace_universal_player(native)
11672
11673 # the second universal player keeps the refused cast protocol and its bridge
11674 assert cast_players["cc_2"].protocol_parent_id == "up_b"
11675 assert derived.protocol_parent_id == "up_b"
11676 assert {link.output_protocol_id for link in universals["up_b"].linked_output_protocols} == {
11677 "cc_2",
11678 "spb_2",
11679 }
11680 # the native player only took over the protocol it could actually claim
11681 assert {link.output_protocol_id for link in native.linked_output_protocols} == {"cc_1"}
11682 assert "spb_2" not in (config_store.get("players/native/values/linked_protocol_ids") or [])
11683
11684 def test_base_stays_with_refused_derived_on_replacement(self, mock_mass: MagicMock) -> None:
11685 """
11686 Keep a base protocol with its derived protocol when the derived link is refused.
11687
11688 The native player already serves the sendspin domain, so the universal player's
11689 sendspin bridge cannot move. The cast protocol it rides on must stay behind with
11690 it instead of moving on its own.
11691 """
11692 controller = PlayerController(mock_mass)
11693 up_provider = create_mock_universal_provider(mock_mass)
11694
11695 config_store: dict[str, Any] = {
11696 f"players/{player_id}": {"enabled": True}
11697 for player_id in ("native", "up_b", "cc_2", "spb_2", "spb_native")
11698 }
11699 mock_mass.config.get = MagicMock(side_effect=config_store.get)
11700 mock_mass.config.set = MagicMock(side_effect=config_store.__setitem__)
11701 mock_mass.config.remove = MagicMock(side_effect=lambda key: config_store.pop(key, None))
11702 mock_mass.players = controller
11703 mock_mass.player_queues = MagicMock()
11704 mock_mass.call_later = MagicMock()
11705 mock_mass.loop = MagicMock()
11706 mock_mass.create_task = MagicMock()
11707
11708 mac = "AA:BB:CC:DD:EE:FF"
11709 identifiers = {IdentifierType.MAC_ADDRESS: mac}
11710 universal = UniversalPlayer(
11711 provider=up_provider,
11712 player_id="up_b",
11713 name="Soundbar (Universal)",
11714 device_info=DeviceInfo(model="Test", manufacturer="Test"),
11715 protocol_player_ids=["cc_2", "spb_2"],
11716 )
11717 universal._attr_device_info.add_identifier(IdentifierType.MAC_ADDRESS, mac)
11718 universal._cache.clear()
11719 universal.update_state(signal_event=False)
11720 universal.set_initialized()
11721
11722 native = MockPlayer(
11723 MockProvider("linkplay", mass=mock_mass), "native", "Soundbar", identifiers=identifiers
11724 )
11725 native.set_initialized()
11726 cast_player = MockPlayer(
11727 MockProvider("chromecast", mass=mock_mass),
11728 "cc_2",
11729 "Cast",
11730 player_type=PlayerType.PROTOCOL,
11731 identifiers=identifiers,
11732 )
11733 cast_player.set_initialized()
11734 derived = self._make_derived_player(mock_mass, "spb_2", "cc_2")
11735 sendspin_native = MockPlayer(
11736 MockProvider("sendspin", mass=mock_mass),
11737 "spb_native",
11738 "Soundbar (Sendspin)",
11739 player_type=PlayerType.PROTOCOL,
11740 identifiers=identifiers,
11741 )
11742 sendspin_native.set_initialized()
11743
11744 controller._players = {
11745 "up_b": universal,
11746 "native": native,
11747 "cc_2": cast_player,
11748 "spb_2": derived,
11749 "spb_native": sendspin_native,
11750 }
11751 controller._add_protocol_link(universal, cast_player, "chromecast")
11752 controller._add_protocol_link(universal, derived, "sendspin")
11753 controller._add_protocol_link(native, sendspin_native, "sendspin")
11754
11755 controller._check_replace_universal_player(native)
11756
11757 # the bridge could not move, so the cast protocol it rides on stays with it
11758 assert derived.protocol_parent_id == "up_b"
11759 assert cast_player.protocol_parent_id == "up_b"
11760 assert {link.output_protocol_id for link in universal.linked_output_protocols} == {
11761 "cc_2",
11762 "spb_2",
11763 }
11764 assert {link.output_protocol_id for link in native.linked_output_protocols} == {
11765 "spb_native"
11766 }
11767
11768 def test_save_underlying_player_id_persists_and_clears(self, mock_mass: MagicMock) -> None:
11769 """Test the derived edge is persisted, cleared when revoked and skipped otherwise."""
11770 controller = PlayerController(mock_mass)
11771 derived = self._make_derived_player(mock_mass, "spb_1", "ap_1")
11772 conf_key = "players/spb_1/values/underlying_player_id"
11773 stored: dict[str, Any] = {"players/spb_1": {"values": {}}}
11774 mock_mass.config.get = MagicMock(
11775 side_effect=lambda key, default=None: stored.get(key, default)
11776 )
11777 mock_mass.config.set = MagicMock(side_effect=stored.__setitem__)
11778
11779 # derived player: edge gets persisted
11780 controller._save_underlying_player_id(derived)
11781 assert stored[conf_key] == "ap_1"
11782
11783 # edge revoked (e.g. bridge client turned web player): stale value is cleared
11784 derived._attr_underlying_player_id = None
11785 controller._save_underlying_player_id(derived)
11786 assert stored[conf_key] is None
11787
11788 # nothing persisted and no edge: no write at all
11789 mock_mass.config.set.reset_mock()
11790 del stored[conf_key]
11791 controller._save_underlying_player_id(derived)
11792 mock_mass.config.set.assert_not_called()
11793
11794 # player config gone: never create partial entries
11795 derived._attr_underlying_player_id = "ap_1"
11796 del stored["players/spb_1"]
11797 controller._save_underlying_player_id(derived)
11798 mock_mass.config.set.assert_not_called()
11799
11800
11801class TestLocalAudioPlayerPromotion:
11802 """
11803 Tests for the local_audio reshape: attribution stub -> regular native player.
11804
11805 The local_audio device player (bare device-uuid player_id) is a regular,
11806 visible PLAYER that parents its Sendspin bridge directly. On upgrade, the
11807 previously auto-created universal player wrapper (up<uuid-hex>) must be
11808 absorbed by the native player without re-wrapping it.
11809 """
11810
11811 DEVICE_UUID = "aabbccdd-1122-3344-5566-77889900aabb"
11812 UNIVERSAL_ID = "upaabbccdd11223344556677889900aabb"
11813
11814 def test_native_local_player_absorbs_universal_wrapper(self, mock_mass: MagicMock) -> None:
11815 """The native player takes over the bridge protocol and the wrapper is emptied."""
11816 universal = _create_universal_player(
11817 mock_mass,
11818 self.UNIVERSAL_ID,
11819 "Dummy Output",
11820 protocol_player_ids=[self.DEVICE_UUID, "spb_1"],
11821 )
11822 native = MockPlayer(
11823 MockProvider("local_audio", mass=mock_mass),
11824 self.DEVICE_UUID,
11825 "Dummy Output",
11826 player_type=PlayerType.PLAYER,
11827 identifiers={IdentifierType.UUID: self.DEVICE_UUID},
11828 )
11829 native.set_initialized()
11830 spb = MockPlayer(
11831 MockProvider("sendspin", mass=mock_mass),
11832 "spb_1",
11833 "Dummy Output Sendspin",
11834 player_type=PlayerType.PROTOCOL,
11835 )
11836 spb._attr_underlying_player_id = self.DEVICE_UUID
11837 spb.set_initialized()
11838
11839 store: dict[str, Any] = {
11840 f"players/{self.DEVICE_UUID}": {"enabled": True},
11841 "players/spb_1": {"enabled": True},
11842 }
11843 mock_mass.config.get = MagicMock(
11844 side_effect=lambda key, default=None: store.get(key, default)
11845 )
11846 mock_mass.config.set = MagicMock(side_effect=store.__setitem__)
11847
11848 def _close_coro(coro: Any, *_args: Any, **_kwargs: Any) -> None:
11849 if hasattr(coro, "close"):
11850 coro.close()
11851
11852 mock_mass.create_task = MagicMock(side_effect=_close_coro)
11853 mock_mass.players = controller = PlayerController(mock_mass)
11854 controller._players = {
11855 self.UNIVERSAL_ID: universal,
11856 self.DEVICE_UUID: native,
11857 "spb_1": spb,
11858 }
11859 controller._add_protocol_link(universal, spb, "sendspin")
11860
11861 controller._try_link_protocols_to_native(native)
11862
11863 assert spb.protocol_parent_id == self.DEVICE_UUID
11864 assert [link.output_protocol_id for link in native.linked_output_protocols] == ["spb_1"]
11865 # the obsolete wrapper keeps neither the bridge nor the native player itself,
11866 # so its permanent cleanup has no orphaned protocols to re-evaluate
11867 assert universal._protocol_player_ids == []
11868 assert store.get("players/spb_1/values/protocol_parent_id") == self.DEVICE_UUID
11869
11870 async def test_delayed_eval_skips_type_changed_player(self, mock_mass: MagicMock) -> None:
11871 """A pending evaluation for a player that is not (or no longer) a protocol is a no-op."""
11872 controller, _ = TestEndToEndDuplicateProtocol._setup_e2e_controller(mock_mass)
11873 mock_mass.config.get = MagicMock(return_value=[])
11874
11875 native = MockPlayer(
11876 MockProvider("local_audio", mass=mock_mass),
11877 self.DEVICE_UUID,
11878 "Dummy Output",
11879 player_type=PlayerType.PLAYER,
11880 )
11881 native.set_initialized()
11882 controller._players = {self.DEVICE_UUID: native}
11883
11884 await controller._delayed_protocol_evaluation(self.DEVICE_UUID)
11885
11886 assert native.protocol_parent_id is None
11887 assert not any(pid.startswith("up") for pid in controller._players)
11888
11889
11890class TestLocalAudioStubMigration:
11891 """Tests for the config migration that promotes local_audio stubs to regular players."""
11892
11893 DEVICE_UUID = "aabbccdd-1122-3344-5566-77889900aabb"
11894 UNIVERSAL_ID = "upaabbccdd11223344556677889900aabb"
11895
11896 def _make_data(self) -> dict[str, Any]:
11897 """Build a settings dict as persisted by the previous local_audio setup."""
11898 return {
11899 CONF_PLAYERS: {
11900 self.DEVICE_UUID: {
11901 "player_id": self.DEVICE_UUID,
11902 "provider": "local_audio",
11903 "player_type": "protocol",
11904 "enabled": True,
11905 "values": {"protocol_parent_id": self.UNIVERSAL_ID},
11906 },
11907 self.UNIVERSAL_ID: {
11908 "player_id": self.UNIVERSAL_ID,
11909 "provider": "universal_player",
11910 "player_type": "group",
11911 "enabled": False,
11912 "name": "Kitchen Output",
11913 "values": {
11914 # ghost_spb has no config anymore (device gone) - must not crash
11915 "linked_protocol_ids": [self.DEVICE_UUID, "spb_1", "ghost_spb"],
11916 "device_identifiers": {"uuid": self.DEVICE_UUID},
11917 "device_info": {"model": "Dummy Output", "manufacturer": "Local Audio"},
11918 "expose_to_ha": False,
11919 "hide_in_ui": True,
11920 },
11921 },
11922 "spb_1": {
11923 "player_id": "spb_1",
11924 "provider": "sendspin",
11925 "player_type": "protocol",
11926 "enabled": True,
11927 "values": {"protocol_parent_id": self.UNIVERSAL_ID},
11928 },
11929 "syncgroup_1": {
11930 "player_id": "syncgroup_1",
11931 "provider": "sync_group",
11932 "player_type": "group",
11933 "enabled": True,
11934 "values": {
11935 "group_members": [self.UNIVERSAL_ID, "other_player"],
11936 "allowed_members": [self.UNIVERSAL_ID],
11937 },
11938 },
11939 },
11940 CONF_PLAYER_QUEUES: {
11941 self.UNIVERSAL_ID: {
11942 "queue_id": self.UNIVERSAL_ID,
11943 "values": {"autoplay_mode": "smart"},
11944 },
11945 },
11946 CONF_PLAYER_DSP: {
11947 self.UNIVERSAL_ID: {"enabled": True},
11948 },
11949 }
11950
11951 async def test_stub_promoted_and_universal_absorbed(self) -> None:
11952 """The stub becomes a regular player carrying the universal player's settings."""
11953 data = self._make_data()
11954
11955 assert await migrate(data) is True
11956
11957 stub_cfg = data[CONF_PLAYERS][self.DEVICE_UUID]
11958 assert stub_cfg["player_type"] == "player"
11959 # the universal player was the device toggle the user operated
11960 assert stub_cfg["enabled"] is False
11961 assert stub_cfg["name"] == "Kitchen Output"
11962 values = stub_cfg["values"]
11963 assert "protocol_parent_id" not in values
11964 assert values["expose_to_ha"] is False
11965 assert values["hide_in_ui"] is True
11966 assert values["linked_protocol_ids"] == ["spb_1", "ghost_spb"]
11967 assert "device_identifiers" not in values
11968 assert "device_info" not in values
11969
11970 # the wrapper is gone and the bridge protocol re-parented
11971 assert self.UNIVERSAL_ID not in data[CONF_PLAYERS]
11972 assert data[CONF_PLAYERS]["spb_1"]["values"]["protocol_parent_id"] == self.DEVICE_UUID
11973 assert data[CONF_PLAYERS]["spb_1"]["player_type"] == "protocol"
11974
11975 # queue settings, DSP config and group memberships follow the new player_id
11976 queue_cfg = data[CONF_PLAYER_QUEUES][self.DEVICE_UUID]
11977 assert queue_cfg["queue_id"] == self.DEVICE_UUID
11978 assert queue_cfg["values"]["autoplay_mode"] == "smart"
11979 assert self.UNIVERSAL_ID not in data[CONF_PLAYER_QUEUES]
11980 assert data[CONF_PLAYER_DSP] == {self.DEVICE_UUID: {"enabled": True}}
11981 group_values = data[CONF_PLAYERS]["syncgroup_1"]["values"]
11982 assert group_values["group_members"] == [self.DEVICE_UUID, "other_player"]
11983 assert group_values["allowed_members"] == [self.DEVICE_UUID]
11984
11985 async def test_stub_without_universal_wrapper(self) -> None:
11986 """A stub without a universal player wrapper is still promoted."""
11987 data = self._make_data()
11988 del data[CONF_PLAYERS][self.UNIVERSAL_ID]
11989
11990 assert await migrate(data) is True
11991
11992 stub_cfg = data[CONF_PLAYERS][self.DEVICE_UUID]
11993 assert stub_cfg["player_type"] == "player"
11994 assert stub_cfg["enabled"] is True
11995 assert "protocol_parent_id" not in stub_cfg["values"]
11996
11997 async def test_migration_is_idempotent(self) -> None:
11998 """A second run finds nothing left to migrate."""
11999 data = self._make_data()
12000
12001 assert await migrate(data) is True
12002 assert await migrate(data) is False
12003
12004
12005class _LockedMockPlayer(MockPlayer):
12006 """A player that keeps its group read-only (e.g. an externally-created mixed group)."""
12007
12008 @property
12009 def grouping_locked(self) -> bool:
12010 """Suppress grouping in the exposed state."""
12011 return True
12012
12013
12014class TestGroupingLockedPolicy:
12015 """A grouping-locked player withholds SET_MEMBERS and group targets in its final state."""
12016
12017 def test_locked_player_withholds_set_members(self, mock_mass: MagicMock) -> None:
12018 """A locked player drops SET_MEMBERS from its exposed features."""
12019 provider = MockProvider("wiim", instance_id="wiim_instance", mass=mock_mass)
12020 player = _LockedMockPlayer(provider, "shell_1", "Shell")
12021 player._attr_supported_features = {PlayerFeature.SET_MEMBERS, PlayerFeature.VOLUME_SET}
12022 player._cache.clear()
12023 player.update_state(signal_event=False)
12024 assert PlayerFeature.SET_MEMBERS not in player.state.supported_features
12025 assert PlayerFeature.VOLUME_SET in player.state.supported_features
12026
12027 def test_locked_player_withholds_protocol_derived_set_members(
12028 self, mock_mass: MagicMock
12029 ) -> None:
12030 """Even a linked protocol player's SET_MEMBERS is suppressed while locked."""
12031 controller = PlayerController(mock_mass)
12032 provider = MockProvider("wiim", instance_id="wiim_instance", mass=mock_mass)
12033 player = _LockedMockPlayer(provider, "shell_1", "Shell")
12034 player._attr_supported_features = set() # no native grouping of its own
12035 protocol = MockPlayer(provider, "airplay_p", "P (AirPlay)", player_type=PlayerType.PROTOCOL)
12036 protocol._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
12037 protocol._cache.clear()
12038 protocol.set_protocol_parent_id("shell_1")
12039 player.set_linked_output_protocols(
12040 [
12041 LinkedOutputProtocol(
12042 output_protocol_id="airplay_p", protocol_domain="airplay", priority=10
12043 )
12044 ]
12045 )
12046 mock_mass.players = controller
12047 controller._players = {"shell_1": player, "airplay_p": protocol}
12048 protocol.refresh_state(signal_event=False)
12049 player.refresh_state(signal_event=False)
12050 assert PlayerFeature.SET_MEMBERS not in player.state.supported_features
12051
12052 def test_locked_player_offers_no_group_targets(self, mock_mass: MagicMock) -> None:
12053 """A locked player exposes no group targets, even an otherwise groupable peer."""
12054 controller = PlayerController(mock_mass)
12055 provider = MockProvider("wiim", instance_id="wiim_instance", mass=mock_mass)
12056 player = _LockedMockPlayer(provider, "shell_1", "Shell")
12057 player._attr_supported_features = {PlayerFeature.SET_MEMBERS}
12058 player._attr_can_group_with = {"peer_1"}
12059 peer = MockPlayer(provider, "peer_1", "Peer")
12060 mock_mass.players = controller
12061 controller._players = {"shell_1": player, "peer_1": peer}
12062 player._cache.clear()
12063 peer.refresh_state(signal_event=False)
12064 player.refresh_state(signal_event=False)
12065 assert player.state.can_group_with == set()
12066
12067 def test_unlocked_player_keeps_grouping(self, mock_mass: MagicMock) -> None:
12068 """A normal (unlocked) player keeps SET_MEMBERS and its group targets."""
12069 controller = PlayerController(mock_mass)
12070 provider = MockProvider("wiim", instance_id="wiim_instance", mass=mock_mass)
12071 player = MockPlayer(provider, "shell_2", "Shell2")
12072 player._attr_supported_features = {PlayerFeature.SET_MEMBERS}
12073 player._attr_can_group_with = {"peer_2"}
12074 peer = MockPlayer(provider, "peer_2", "Peer2")
12075 mock_mass.players = controller
12076 controller._players = {"shell_2": player, "peer_2": peer}
12077 player._cache.clear()
12078 peer.refresh_state(signal_event=False)
12079 player.refresh_state(signal_event=False)
12080 assert PlayerFeature.SET_MEMBERS in player.state.supported_features
12081 assert "peer_2" in player.state.can_group_with
12082
12083 def test_locked_peer_excluded_from_group_targets(self, mock_mass: MagicMock) -> None:
12084 """An unlocked leader drops a locked peer but keeps an unlocked one as a target."""
12085 controller = PlayerController(mock_mass)
12086 provider = MockProvider("wiim", instance_id="wiim_instance", mass=mock_mass)
12087 leader = MockPlayer(provider, "shell_1", "Shell")
12088 leader._attr_supported_features = {PlayerFeature.SET_MEMBERS}
12089 leader._attr_can_group_with = {"locked_peer", "open_peer"}
12090 locked_peer = _LockedMockPlayer(provider, "locked_peer", "Locked Peer")
12091 open_peer = MockPlayer(provider, "open_peer", "Open Peer")
12092 mock_mass.players = controller
12093 controller._players = {
12094 "shell_1": leader,
12095 "locked_peer": locked_peer,
12096 "open_peer": open_peer,
12097 }
12098 leader._cache.clear()
12099 for player in (locked_peer, open_peer, leader):
12100 player.refresh_state(signal_event=False)
12101 # the locked peer keeps its own group read-only, so it is not offered as a target,
12102 # while the ordinary peer still is
12103 assert "locked_peer" not in leader.state.can_group_with
12104 assert "open_peer" in leader.state.can_group_with
12105
12106 def test_linked_protocol_cannot_reintroduce_locked_member(self, mock_mass: MagicMock) -> None:
12107 """A locked member offered by a linked protocol is still kept out of the targets."""
12108 controller = PlayerController(mock_mass)
12109 provider = MockProvider("wiim", instance_id="wiim_instance", mass=mock_mass)
12110 leader = MockPlayer(provider, "shell_1", "Shell")
12111 leader._attr_supported_features = set() # no native grouping of its own
12112 protocol = MockPlayer(provider, "airplay_p", "P (AirPlay)", player_type=PlayerType.PROTOCOL)
12113 protocol._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
12114 protocol._attr_can_group_with = {"locked_peer", "open_peer"}
12115 protocol._cache.clear()
12116 protocol.set_protocol_parent_id("shell_1")
12117 leader.set_linked_output_protocols(
12118 [
12119 LinkedOutputProtocol(
12120 output_protocol_id="airplay_p", protocol_domain="airplay", priority=10
12121 )
12122 ]
12123 )
12124 locked_peer = _LockedMockPlayer(provider, "locked_peer", "Locked Peer")
12125 open_peer = MockPlayer(provider, "open_peer", "Open Peer")
12126 mock_mass.players = controller
12127 controller._players = {
12128 "shell_1": leader,
12129 "airplay_p": protocol,
12130 "locked_peer": locked_peer,
12131 "open_peer": open_peer,
12132 }
12133 for player in (locked_peer, open_peer, protocol):
12134 player.refresh_state(signal_event=False)
12135 leader._cache.clear()
12136 leader.refresh_state(signal_event=False)
12137 # the linked protocol lists the locked peer, but the final filter still excludes it
12138 assert "locked_peer" not in leader.state.can_group_with
12139 assert "open_peer" in leader.state.can_group_with
12140
12141
12142class _NativeGroupingMockPlayer(MockPlayer):
12143 """A player that runs its own multiroom and prefers native grouping."""
12144
12145 @property
12146 def prefer_native_grouping(self) -> bool:
12147 """Prefer native grouping over any linked protocol."""
12148 return True
12149
12150
12151class _RejectsNativeGroupingMockPlayer(MockPlayer):
12152 """A parent that never accepts another player as a native group peer."""
12153
12154 def is_native_group_compatible(self, other: Player) -> bool:
12155 """Reject every peer as native-incompatible (e.g. a cross-backend device)."""
12156 return False
12157
12158
12159class TestPreferNativeGrouping:
12160 """A player that prefers native grouping uses it before its preferred output protocol."""
12161
12162 def test_prefer_native_uses_native_before_child_preferred(self, mock_mass: MagicMock) -> None:
12163 """A prefer-native child groups natively even with an explicit protocol preference."""
12164 controller = PlayerController(mock_mass)
12165 provider = MockProvider("wiim", instance_id="wiim_instance", mass=mock_mass)
12166 parent = MockPlayer(provider, "shell_parent", "Parent")
12167 child = _NativeGroupingMockPlayer(provider, "shell_child", "Child")
12168 # an explicit child output-protocol preference that would otherwise win
12169 mock_mass.config.get_raw_player_config_value = MagicMock(return_value="airplay_child")
12170 mock_mass.players = controller
12171 controller._players = {"shell_parent": parent, "shell_child": child}
12172 native_members: list[str] = []
12173 protocol_members: list[str] = []
12174 controller._select_grouping_for_member(
12175 child, parent, None, None, True, protocol_members, native_members
12176 )
12177 assert native_members == ["shell_child"]
12178 assert protocol_members == []
12179
12180 def test_prefer_native_falls_through_same_instance_not_native_peer(
12181 self, mock_mass: MagicMock
12182 ) -> None:
12183 """A same-instance pair the parent rejects as a native peer is not forced native."""
12184 controller = PlayerController(mock_mass)
12185 # official + generic LinkPlay share one wiim provider instance, but a cross-backend
12186 # peer is not native-group compatible, so the seam must not force native grouping.
12187 provider = MockProvider("wiim", instance_id="wiim_instance", mass=mock_mass)
12188 parent = _RejectsNativeGroupingMockPlayer(provider, "shell_parent", "Parent")
12189 child = _NativeGroupingMockPlayer(provider, "shell_child", "Child")
12190 mock_mass.config.get_raw_player_config_value = MagicMock(return_value=None)
12191 mock_mass.players = controller
12192 controller._players = {"shell_parent": parent, "shell_child": child}
12193 native_members: list[str] = []
12194 protocol_members: list[str] = []
12195 controller._select_grouping_for_member(
12196 child, parent, None, None, True, protocol_members, native_members
12197 )
12198 assert native_members == []
12199
12200 def test_prefer_native_falls_through_when_incompatible(self, mock_mass: MagicMock) -> None:
12201 """When native grouping is not possible (cross-backend), the seam does not force it."""
12202 controller = PlayerController(mock_mass)
12203 parent_provider = MockProvider("wiim", instance_id="wiim_instance", mass=mock_mass)
12204 child_provider = MockProvider("other", instance_id="other_instance", mass=mock_mass)
12205 parent = MockPlayer(parent_provider, "shell_parent", "Parent")
12206 parent._attr_can_group_with = set() # does not accept the cross-backend child
12207 child = _NativeGroupingMockPlayer(child_provider, "other_child", "Child")
12208 mock_mass.config.get_raw_player_config_value = MagicMock(return_value=None)
12209 mock_mass.players = controller
12210 controller._players = {"shell_parent": parent, "other_child": child}
12211 native_members: list[str] = []
12212 protocol_members: list[str] = []
12213 controller._select_grouping_for_member(
12214 child, parent, None, None, True, protocol_members, native_members
12215 )
12216 # the preferred-native seam did not force a cross-backend native group
12217 assert native_members == []
12218
12219 def test_default_player_keeps_protocol_first_ordering(self, mock_mass: MagicMock) -> None:
12220 """An ordinary player (no native preference) is unaffected by the seam."""
12221 controller = PlayerController(mock_mass)
12222 provider = MockProvider("wiim", instance_id="wiim_instance", mass=mock_mass)
12223 parent = MockPlayer(provider, "shell_parent", "Parent")
12224 child = MockPlayer(provider, "plain_child", "Child")
12225 assert child.prefer_native_grouping is False
12226 mock_mass.config.get_raw_player_config_value = MagicMock(return_value=None)
12227 mock_mass.players = controller
12228 controller._players = {"shell_parent": parent, "plain_child": child}
12229 native_members: list[str] = []
12230 protocol_members: list[str] = []
12231 controller._select_grouping_for_member(
12232 child, parent, None, None, True, protocol_members, native_members
12233 )
12234 # with no preferred/active/common protocol, the default player still reaches
12235 # native grouping via the normal priority (Priority 3), not the preferred seam
12236 assert native_members == ["plain_child"]
12237
12238
12239def _live_source(item_id: str, provider: str = "spotify_connect") -> AudioSource:
12240 """Build the AudioSource a live session publishes on a player."""
12241 return AudioSource(
12242 item_id=item_id,
12243 provider=provider,
12244 name=f"Live source ({item_id})",
12245 provider_mappings={
12246 ProviderMapping(item_id=item_id, provider_domain=provider, provider_instance=provider)
12247 },
12248 )
12249
12250
12251class TestCanGroupWithExternalSource:
12252 """Grouping candidates while something other than the player's queue is playing."""
12253
12254 @staticmethod
12255 def _build_rig(mock_mass: MagicMock) -> tuple[PlayerController, MockPlayer]:
12256 """
12257 Wire a player with one native peer and one reachable only over AirPlay.
12258
12259 Returns the controller and the player whose grouping candidates are asserted on.
12260 """
12261 controller = PlayerController(mock_mass)
12262 sonos_provider = MockProvider("sonos", instance_id="sonos_instance", mass=mock_mass)
12263 airplay_provider = MockProvider("airplay", instance_id="airplay_instance", mass=mock_mass)
12264
12265 sonos_player = MockPlayer(
12266 sonos_provider,
12267 "sonos_123",
12268 "Living Room",
12269 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
12270 )
12271 sonos_player._attr_supported_features.add(PlayerFeature.PLAY_MEDIA)
12272 sonos_player._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
12273 sonos_player._attr_can_group_with = {"sonos_456"}
12274 sonos_player_b = MockPlayer(
12275 sonos_provider,
12276 "sonos_456",
12277 "Kitchen",
12278 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:02"},
12279 )
12280 sonos_airplay = MockPlayer(
12281 airplay_provider,
12282 "airplay_sonos",
12283 "Living Room (AirPlay)",
12284 player_type=PlayerType.PROTOCOL,
12285 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:01"},
12286 )
12287 sonos_airplay._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
12288 sonos_airplay._attr_can_group_with = {"airplay_other"}
12289 sonos_airplay.set_protocol_parent_id("sonos_123")
12290
12291 wiim_player = MockPlayer(
12292 sonos_provider,
12293 "wiim_789",
12294 "Bedroom",
12295 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:03"},
12296 )
12297 airplay_other = MockPlayer(
12298 airplay_provider,
12299 "airplay_other",
12300 "Bedroom (AirPlay)",
12301 player_type=PlayerType.PROTOCOL,
12302 identifiers={IdentifierType.MAC_ADDRESS: "AA:BB:CC:DD:EE:03"},
12303 )
12304 airplay_other._attr_supported_features.add(PlayerFeature.SET_MEMBERS)
12305 airplay_other._attr_can_group_with = {"airplay_sonos"}
12306 airplay_other.set_protocol_parent_id("wiim_789")
12307
12308 for player, protocol_id in (
12309 (sonos_player, "airplay_sonos"),
12310 (wiim_player, "airplay_other"),
12311 ):
12312 player.set_linked_output_protocols(
12313 [
12314 LinkedOutputProtocol(
12315 output_protocol_id=protocol_id,
12316 protocol_domain="airplay",
12317 priority=10,
12318 )
12319 ]
12320 )
12321
12322 mock_mass.players = controller
12323 # nothing here is a registered queue, so the external-source check is reachable
12324 mock_mass.player_queues.get = MagicMock(return_value=None)
12325 controller._players = {
12326 "sonos_123": sonos_player,
12327 "sonos_456": sonos_player_b,
12328 "wiim_789": wiim_player,
12329 "airplay_sonos": sonos_airplay,
12330 "airplay_other": airplay_other,
12331 }
12332 for registered in controller._players.values():
12333 registered._cache.clear()
12334 sonos_airplay.refresh_state(signal_event=False)
12335 airplay_other.refresh_state(signal_event=False)
12336 sonos_player.refresh_state(signal_event=False)
12337 sonos_player_b.refresh_state(signal_event=False)
12338 wiim_player.refresh_state(signal_event=False)
12339 return controller, sonos_player
12340
12341 def test_live_audio_source_keeps_protocol_candidates(self, mock_mass: MagicMock) -> None:
12342 """A source MA streams itself (e.g. Spotify Connect) can still be grouped."""
12343 controller, sonos_player = self._build_rig(mock_mass)
12344 controller._start_audio_source_session(
12345 "sonos_123", _live_source("sonos_123"), "spotify_connect"
12346 )
12347 sonos_player.refresh_state(signal_event=False)
12348
12349 assert sonos_player.state.active_source == "spotify_connect://audio_source/sonos_123"
12350 # MA produces the audio, so both the native peer and the one reachable
12351 # only over AirPlay can be added to it
12352 assert sonos_player.state.can_group_with == {"sonos_456", "wiim_789"}
12353
12354 def test_device_own_external_source_hides_protocol_candidates(
12355 self, mock_mass: MagicMock
12356 ) -> None:
12357 """The device can still group its own line-in natively, just not over a protocol."""
12358 controller, sonos_player = self._build_rig(mock_mass)
12359 # a live source elsewhere says nothing about what this player is playing
12360 controller._start_audio_source_session("wiim_789", _live_source("wiim_789"), "vban")
12361 sonos_player._attr_active_source = "tv"
12362 sonos_player._attr_playback_state = PlaybackState.PLAYING
12363 sonos_player.refresh_state(signal_event=False)
12364
12365 assert sonos_player.state.active_source == "tv"
12366 # the device distributes its own input to its own kind, but MA cannot put
12367 # audio it never receives onto an AirPlay/Sendspin protocol player
12368 assert sonos_player.state.can_group_with == {"sonos_456"}
12369
12370
12371class TestExternalSourceTakeover:
12372 """Whether a source change while a protocol renders the audio counts as a takeover."""
12373
12374 @staticmethod
12375 def _playing_over_airplay(
12376 mock_mass: MagicMock,
12377 ) -> tuple[PlayerController, MockPlayer]:
12378 """Wire a player rendering through its AirPlay protocol player."""
12379 controller, sonos_player = TestCanGroupWithExternalSource._build_rig(mock_mass)
12380 sonos_player._attr_playback_state = PlaybackState.PLAYING
12381 sonos_player.set_active_output_protocol("airplay_sonos")
12382 sonos_player.refresh_state(signal_event=False)
12383 return controller, sonos_player
12384
12385 def test_live_audio_source_is_not_a_takeover(self, mock_mass: MagicMock) -> None:
12386 """MA putting a live source on the player must not tear down its protocol group."""
12387 controller, sonos_player = self._playing_over_airplay(mock_mass)
12388 controller._start_audio_source_session(
12389 "sonos_123", _live_source("sonos_123"), "spotify_connect"
12390 )
12391 sonos_player.refresh_state(signal_event=False)
12392
12393 controller._check_external_source_takeover(sonos_player)
12394
12395 assert sonos_player.active_output_protocol == "airplay_sonos"
12396
12397 def test_device_own_external_source_stays_external(self, mock_mass: MagicMock) -> None:
12398 """A source MA does not produce is still classified as external."""
12399 # checked on the classifier directly: while an output protocol renders the audio,
12400 # __final_active_source overrules what the device reports, so a device-local
12401 # source cannot be driven through _check_external_source_takeover at all
12402 controller, sonos_player = TestCanGroupWithExternalSource._build_rig(mock_mass)
12403
12404 assert not controller._is_ma_managed_source(sonos_player, "tv")
12405