[ble_device_base] Hub provider registry and shared consumer helpers (#18081)

Co-authored-by: J. Nick Koston <nick@koston.org>

tests/component_tests/ble_device_base/test_hub_binding.py

@@ -0,0 +1,204 @@
+"""Tests for the BLE hub provider registry and the missing-hub diagnostics."""
+
+from collections.abc import Generator
+from importlib import import_module
+from pathlib import Path
+
+import pytest
+
+import esphome.codegen as cg
+from esphome.components import ble_device_base
+import esphome.config_validation as cv
+from esphome.const import KEY_TARGET_PLATFORM, Platform
+from esphome.core import CORE, ID, KEY_CORE
+from esphome.cpp_generator import MockObjClass
+
+COMPONENTS_DIR = Path(ble_device_base.__file__).parent.parent
+
+
+@pytest.fixture
+def hub_registry() -> Generator[set[str]]:
+    """Save/restore _HUB_PROVIDERS — a module global with no reset hook.
+
+    CORE state needs no bookkeeping here: conftest's autouse reset_core
+    fixture reassigns it after every test.
+    """
+    saved = set(ble_device_base._HUB_PROVIDERS)
+    yield ble_device_base._HUB_PROVIDERS
+    ble_device_base._HUB_PROVIDERS.clear()
+    ble_device_base._HUB_PROVIDERS.update(saved)
+
+
+def _generated_id() -> ID:
+    """An ID as cv.GenerateID leaves it before the ID-assignment pass."""
+    return ID(None, is_declaration=False, type="ble_device_base::BLEHub")
+
+
+def _set_platform(platform: str | None) -> None:
+    core_data = CORE.data.setdefault(KEY_CORE, {})
+    if platform is None:
+        core_data.pop(KEY_TARGET_PLATFORM, None)
+    else:
+        core_data[KEY_TARGET_PLATFORM] = platform
+
+
+# The missing-hub diagnostics: one test per path so a regression in one
+# scenario cannot mask the others. The hub binding must fail with a
+# tracker-naming message, not use_id's C++-class error, regardless of
+# config-step ordering internals.
+
+
+def test_empty_registry_names_every_in_tree_tracker(hub_registry: set[str]) -> None:
+    # The common failure: a fresh CLI process where the tracker was simply
+    # forgotten, so no tracker module was ever imported and the registry is
+    # empty. The error must still name the in-tree trackers.
+    hub_registry.clear()
+    CORE.loaded_integrations.clear()
+    _set_platform(None)
+    with pytest.raises(
+        cv.Invalid,
+        match="add one of: bk72xx_ble_tracker, esp32_ble_tracker, ln882h_ble_tracker, rp2_ble_tracker",
+    ):
+        ble_device_base._require_hub(_generated_id())
+
+
+def test_platform_filters_the_suggested_trackers(hub_registry: set[str]) -> None:
+    hub_registry.clear()
+    CORE.loaded_integrations.clear()
+    _set_platform("esp32")
+    with pytest.raises(cv.Invalid, match="add one of: esp32_ble_tracker$"):
+        ble_device_base._require_hub(_generated_id())
+
+
+def test_ble_less_platform_is_not_misdirected(hub_registry: set[str]) -> None:
+    # A known platform with no in-tree hub must not be pointed at other
+    # platforms' trackers; out-of-tree BLE hubs are not supported.
+    hub_registry.clear()
+    CORE.loaded_integrations.clear()
+    _set_platform("esp8266")
+    with pytest.raises(
+        cv.Invalid,
+        match="No BLE tracker exists for esp8266; BLE components are not supported",
+    ):
+        ble_device_base._require_hub(_generated_id())
+
+
+def test_explicit_id_bypasses_the_registry(hub_registry: set[str]) -> None:
+    # Explicit ble_hub_id: is the multi-hub disambiguation case; the ID pass
+    # owns that diagnosis and its error names the missing id.
+    hub_registry.clear()
+    CORE.loaded_integrations.clear()
+    explicit = ID("my_hub", is_declaration=False, type="ble_device_base::BLEHub")
+    assert ble_device_base._require_hub(explicit) is explicit
+
+
+def test_registered_and_loaded_provider_passes(hub_registry: set[str]) -> None:
+    hub_registry.add("esp32_ble_tracker")
+    CORE.loaded_integrations.add("esp32_ble_tracker")
+    generated = _generated_id()
+    assert ble_device_base._require_hub(generated) is generated
+
+
+def _module_name(path: Path) -> str:
+    """Dotted module name for a file under esphome/components."""
+    rel = path.relative_to(COMPONENTS_DIR.parent)
+    parts = rel.with_suffix("").parts
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+    return "esphome." + ".".join(parts)
+
+
+def _hub_component_modules() -> list[str]:
+    """Components whose codegen class inherits ble_device_base.BLEHub.
+
+    The source-text pass only selects import candidates (importing all ~900
+    component packages is too slow); membership is decided by the class
+    hierarchy via MockObjClass.inherits_from on every module whose source
+    matched — nested declaring modules included — so a comment mentioning
+    BLEHub in a consumer cannot produce a false positive.
+    """
+    hub_modules = []
+    for pkg in sorted(COMPONENTS_DIR.iterdir()):
+        if pkg.name == "ble_device_base" or not (pkg / "__init__.py").is_file():
+            continue
+        matched = [
+            path
+            for path in pkg.rglob("*.py")
+            if "BLEHub" in path.read_text(encoding="utf-8")
+        ]
+        if not matched:
+            continue
+        for path in matched:
+            mod = import_module(_module_name(path))
+            if any(
+                isinstance(attr, MockObjClass)
+                and attr is not ble_device_base.BLEHub
+                and attr.inherits_from(ble_device_base.BLEHub)
+                for attr in vars(mod).values()
+            ):
+                hub_modules.append(pkg.name)
+                break
+    return hub_modules
+
+
+def test_every_in_tree_hub_registers_as_provider() -> None:
+    """A BLEHub subclass that forgets register_hub_provider() makes _require_hub
+    reject valid configs for that platform — fail CI instead of the user."""
+    hub_modules = _hub_component_modules()
+    assert hub_modules, "hub discovery found no BLEHub subclasses — scan stale?"
+    for name in hub_modules:
+        assert name in ble_device_base._HUB_PROVIDERS, (
+            f"{name} subclasses ble_device_base.BLEHub but never calls "
+            "register_hub_provider(); a valid config using it would be rejected"
+        )
+    # The per-platform error table must know every in-tree hub, keyed by real
+    # platform names — a typo'd key would silently route that platform into
+    # the no-in-tree-tracker branch.
+    assert set(ble_device_base._IN_TREE_HUB_PROVIDERS.values()) == set(hub_modules)
+    platforms = {platform.value for platform in Platform}
+    assert set(ble_device_base._IN_TREE_HUB_PROVIDERS) <= platforms
+
+
+def test_ble_device_schema_declares_the_binding_key(hub_registry: set[str]) -> None:
+    """Extending BLE_DEVICE_SCHEMA keeps ble_hub_id a declared key on a strict
+    schema, for both the generated and the explicit form, and the missing-hub
+    rejection surfaces through the schema itself."""
+    schema = cv.Schema({}).extend(ble_device_base.BLE_DEVICE_SCHEMA)
+    hub_registry.clear()
+    CORE.loaded_integrations.discard("esp32_ble_tracker")
+    with pytest.raises(cv.Invalid, match="No BLE tracker configured"):
+        schema({})
+    hub_registry.add("esp32_ble_tracker")
+    CORE.loaded_integrations.add("esp32_ble_tracker")
+    generated = schema({})[ble_device_base.CONF_BLE_HUB_ID]
+    assert isinstance(generated, ID) and generated.id is None
+    explicit = schema({"ble_hub_id": "my_hub"})[ble_device_base.CONF_BLE_HUB_ID]
+    assert explicit.id == "my_hub"
+
+
+def test_rename_legacy_hub_id_migrates_the_old_key() -> None:
+    validator = ble_device_base.rename_legacy_hub_id("my_sensor")
+    migrated = validator({"esp32_ble_id": "tracker1"})
+    assert migrated == {ble_device_base.CONF_BLE_HUB_ID: "tracker1"}
+    untouched = validator({"name": "x"})
+    assert untouched == {"name": "x"}
+
+
+def test_add_service_uuid_dispatches_by_width(monkeypatch: pytest.MonkeyPatch) -> None:
+    emitted: list[str] = []
+    monkeypatch.setattr(
+        "esphome.components.ble_device_base.cg.add", lambda e: emitted.append(str(e))
+    )
+    var = cg.MockObj("trig")
+    ble_device_base.add_service_uuid(var, "11AA")
+    ble_device_base.add_service_uuid(var, "11223344")
+    ble_device_base.add_service_uuid(var, "11223344-5566-7788-99aa-bbccddeeff00")
+    assert "set_service_uuid16" in emitted[0]
+    assert "set_service_uuid32" in emitted[1]
+    assert "set_service_uuid128" in emitted[2]
+    # BLE wire order: the 128-bit array must be byte-reversed — as_hex_array
+    # in its place would still emit the right setter name and silently never
+    # match on-air.
+    assert "0x00,0xff,0xee,0xdd" in emitted[2]
+    with pytest.raises(ValueError, match="Unsupported UUID format"):
+        ble_device_base.add_service_uuid(var, "123")