[core] Shared slot count factory for codegen sized listener storage (#18057)

tests/component_tests/ble_device_base/config/bk72xx_controller_only.yaml

@@ -0,0 +1,7 @@
+esphome:
+  name: slotcount-controller
+
+bk72xx:
+  board: generic-bk7252
+
+bk72xx_ble:

tests/component_tests/ble_device_base/config/bk72xx_tracker.yaml

@@ -0,0 +1,7 @@
+esphome:
+  name: slotcount-tracker
+
+bk72xx:
+  board: generic-bk7252
+
+bk72xx_ble_tracker:

tests/component_tests/ble_device_base/test_slot_counter.py

@@ -0,0 +1,63 @@
+"""Tests for the shared slot_counter codegen factory.
+
+The factory is exercised end to end through the real controllers: a tracker
+config must emit the platform's scan listener count define, and a
+controller-only config must emit nothing so the guarded StaticVector storage
+compiles out.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+from esphome.core import CORE
+
+from ..helpers import get_define_value
+
+
+def test_tracker_requests_one_slot(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+) -> None:
+    """The tracker's to_code requests a slot; the FINAL job emits the count.
+
+    The neutral listener count must stay absent from the same build: no BLE
+    consumer registered through register_ble_device().
+    """
+    generate_main(component_config_path("bk72xx_tracker.yaml"))
+    assert get_define_value("BK72XX_BLE_SCAN_LISTENER_COUNT") == "1"
+    assert get_define_value("ESPHOME_BLE_DEVICE_BASE_LISTENER_COUNT") is None
+
+
+def test_controller_only_emits_no_count(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+) -> None:
+    """No consumer, no define — the guarded listener storage compiles out."""
+    generate_main(component_config_path("bk72xx_controller_only.yaml"))
+    assert get_define_value("BK72XX_BLE_SCAN_LISTENER_COUNT") is None
+
+
+def test_neutral_listener_count_emitted_when_requested() -> None:
+    """Registering through register_ble_device() emits the neutral count.
+
+    No in-tree sensor registers through ble_device_base.register_ble_device()
+    yet (consumer migration is a follow-up), so the coroutine is driven with a
+    mock hub instead of a config; every tracker's #ifdef-guarded listener
+    storage keys on this define, and a broken emit path would compile the
+    storage out silently.
+    """
+    import esphome.codegen as cg
+    from esphome.components import ble_device_base
+    from esphome.core import ID
+
+    hub_id = ID("hub", type=ble_device_base.BLEHub)
+    CORE.register_variable(hub_id, cg.MockObj("hub"))
+    CORE.add_job(
+        ble_device_base.register_ble_device,
+        cg.MockObj("listener"),
+        {ble_device_base.CONF_BLE_HUB_ID: hub_id},
+    )
+    CORE.flush_tasks()
+    assert get_define_value(ble_device_base.LISTENER_COUNT_DEFINE) == "1"

tests/component_tests/helpers.py

@@ -27,3 +27,19 @@ def extract_packed_value(main_cpp: str, var_name: str) -> int:
     match = re.search(combined_pattern, main_cpp) or re.search(legacy_pattern, main_cpp)
     assert match, f"configure call not found for {var_name}"
     return int(match.group(1))
+
+
+def get_define_value(name: str) -> str | None:
+    """Rendered value of a CORE define, or None when absent.
+
+    Values are codegen expressions (IntLiteral); they are compared rendered.
+    A value-less define (e.g. USE_BK72XX_BLE) is present but renders as the
+    string "None", while an absent define returns the None object — easy to
+    conflate in assertions, so use this helper for valued defines only.
+    """
+    from esphome.core import CORE
+
+    for define in CORE.defines:
+        if define.name == name:
+            return str(define.value)
+    return None

tests/unit_tests/test_cpp_helpers.py

@@ -4,6 +4,7 @@ from unittest.mock import Mock
 import pytest
 
 from esphome import const, cpp_helpers as ch
+from esphome.core import CoroPriority, coroutine_with_priority
 from esphome.cpp_helpers import ComponentSourcePool, register_component_source
 
 
@@ -167,3 +168,53 @@ def test_register_component_source_overflow_suppressed_in_testing_mode(
         idx = register_component_source("overflow_component")
     assert idx == 0
     assert "Too many unique component source names" not in caplog.text
+
+
+def _define_value(name: str) -> str | None:
+    for define in ch.CORE.defines:
+        if define.name == name:
+            # Values are codegen expressions (IntLiteral); compare rendered.
+            return str(define.value)
+    return None
+
+
+def test_slot_counter_emits_requested_count() -> None:
+    """Each request bumps the count; the self-scheduled FINAL job emits it."""
+    request = ch.slot_counter("TEST_SLOT_COUNT")
+    request()
+    request()
+    ch.CORE.flush_tasks()
+    assert _define_value("TEST_SLOT_COUNT") == "2"
+
+
+def test_slot_counter_without_requests_emits_nothing() -> None:
+    """No requests, no job, no define — the guarded storage compiles out."""
+    ch.slot_counter("TEST_SLOT_COUNT_UNUSED")
+    ch.CORE.flush_tasks()
+    assert _define_value("TEST_SLOT_COUNT_UNUSED") is None
+
+
+def test_slot_counter_request_from_final_job_still_emits() -> None:
+    """The FIRST request for a define may come from a FINAL job: its emit job
+    is scheduled mid-drain and flush_tasks() loops until the heap is empty.
+    Later requests do not get this guarantee — see the companion test."""
+    request = ch.slot_counter("TEST_SLOT_COUNT_LATE")
+
+    @coroutine_with_priority(CoroPriority.FINAL)
+    async def late_requester() -> None:
+        request()
+
+    ch.CORE.add_job(late_requester)
+    ch.CORE.flush_tasks()
+    assert _define_value("TEST_SLOT_COUNT_LATE") == "1"
+
+
+def test_slot_counter_request_after_emit_raises() -> None:
+    """The boundary of FINAL-time requests: once the define was emitted, a
+    further request would silently undersize the storage, so it fails loudly."""
+    request = ch.slot_counter("TEST_SLOT_COUNT_TOO_LATE")
+    request()
+    ch.CORE.flush_tasks()
+    assert _define_value("TEST_SLOT_COUNT_TOO_LATE") == "1"
+    with pytest.raises(ValueError, match="TEST_SLOT_COUNT_TOO_LATE"):
+        request()