Deprecate async_track_state_change in favor of async_track_state_change_event (#115558)

homeassistant/helpers/event.py

@@ -38,6 +38,7 @@ from homeassistant.util import dt as dt_util
 from homeassistant.util.async_ import run_callback_threadsafe
 from homeassistant.util.event_type import EventType
 
+from . import frame
 from .device_registry import (
     EVENT_DEVICE_REGISTRY_UPDATED,
     EventDeviceRegistryUpdatedData,
@@ -203,8 +204,16 @@ def async_track_state_change(
     being None, async_track_state_change_event should be used instead
     as it is slightly faster.
 
+    This function is deprecated and will be removed in Home Assistant 2025.5.
+
     Must be run within the event loop.
     """
+    frame.report(
+        "calls `async_track_state_change` instead of `async_track_state_change_event`"
+        " which is deprecated and will be removed in Home Assistant 2025.5",
+        error_if_core=False,
+    )
+
     if from_state is not None:
         match_from_state = process_state_match(from_state)
     if to_state is not None:

tests/helpers/test_event.py

@@ -4804,3 +4804,18 @@ async def test_async_track_device_registry_updated_event_with_a_callback_that_th
     unsub2()
 
     assert event_data[0] == {"action": "create", "device_id": device_id}
+
+
+async def test_track_state_change_deprecated(
+    hass: HomeAssistant, caplog: pytest.LogCaptureFixture
+) -> None:
+    """Test track_state_change is deprecated."""
+    async_track_state_change(
+        hass, "light.Bowl", lambda entity_id, old_state, new_state: None, "on", "off"
+    )
+
+    assert (
+        "Detected code that calls `async_track_state_change` instead "
+        "of `async_track_state_change_event` which is deprecated and "
+        "will be removed in Home Assistant 2025.5. Please report this issue."
+    ) in caplog.text