Disable experimental triggers according to labs flag setting (home-assistant#157320)

Author: emontnemery

homeassistant/components/automation/__init__.py

@@ -12,7 +12,7 @@
 from propcache.api import cached_property
 import voluptuous as vol
 
-from homeassistant.components import websocket_api
+from homeassistant.components import labs, websocket_api
 from homeassistant.components.blueprint import CONF_USE_BLUEPRINT
 from homeassistant.const import (
     ATTR_ENTITY_ID,
@@ -114,6 +114,34 @@
 ATTR_VARIABLES = "variables"
 SERVICE_TRIGGER = "trigger"
 
+NEW_TRIGGERS_CONDITIONS_FEATURE_FLAG = "new_triggers_conditions"
+
+_EXPERIMENTAL_TRIGGER_PLATFORMS = {
+    "alarm_control_panel",
+    "assist_satellite",
+    "climate",
+    "cover",
+    "fan",
+    "lawn_mower",
+    "light",
+    "media_player",
+    "text",
+    "vacuum",
+}
+
+
+@callback
+def is_disabled_experimental_trigger(hass: HomeAssistant, platform: str) -> bool:
+    """Check if the platform is a disabled experimental trigger platform."""
+    return (
+        platform in _EXPERIMENTAL_TRIGGER_PLATFORMS
+        and not labs.async_is_preview_feature_enabled(
+            hass,
+            DOMAIN,
+            NEW_TRIGGERS_CONDITIONS_FEATURE_FLAG,
+        )
+    )
+
 
 class IfAction(Protocol):
     """Define the format of if_action."""

homeassistant/helpers/trigger.py

@@ -83,6 +83,7 @@
 TRIGGER_DESCRIPTION_CACHE: HassKey[dict[str, dict[str, Any] | None]] = HassKey(
     "trigger_description_cache"
 )
+TRIGGER_DISABLED_TRIGGERS: HassKey[set[str]] = HassKey("trigger_disabled_triggers")
 TRIGGER_PLATFORM_SUBSCRIPTIONS: HassKey[
     list[Callable[[set[str]], Coroutine[Any, Any, None]]]
 ] = HassKey("trigger_platform_subscriptions")
@@ -124,9 +125,27 @@ def starts_with_dot(key: str) -> str:
 
 async def async_setup(hass: HomeAssistant) -> None:
     """Set up the trigger helper."""
+    from homeassistant.components import automation, labs  # noqa: PLC0415
+
     hass.data[TRIGGER_DESCRIPTION_CACHE] = {}
+    hass.data[TRIGGER_DISABLED_TRIGGERS] = set()
     hass.data[TRIGGER_PLATFORM_SUBSCRIPTIONS] = []
     hass.data[TRIGGERS] = {}
+
+    @callback
+    def new_triggers_conditions_listener() -> None:
+        """Handle new_triggers_conditions flag change."""
+        # Invalidate the cache
+        hass.data[TRIGGER_DESCRIPTION_CACHE] = {}
+        hass.data[TRIGGER_DISABLED_TRIGGERS] = set()
+
+    labs.async_listen(
+        hass,
+        automation.DOMAIN,
+        automation.NEW_TRIGGERS_CONDITIONS_FEATURE_FLAG,
+        new_triggers_conditions_listener,
+    )
+
     await async_process_integration_platforms(
         hass, "trigger", _register_trigger_platform, wait_for_platforms=True
     )
@@ -694,9 +713,19 @@ async def async_run(
 async def _async_get_trigger_platform(
     hass: HomeAssistant, trigger_key: str
 ) -> tuple[str, TriggerProtocol]:
+    from homeassistant.components import automation  # noqa: PLC0415
+
     platform_and_sub_type = trigger_key.split(".")
     platform = platform_and_sub_type[0]
     platform = _PLATFORM_ALIASES.get(platform, platform)
+
+    if automation.is_disabled_experimental_trigger(hass, platform):
+        raise vol.Invalid(
+            f"Trigger '{trigger_key}' requires the experimental 'New triggers and "
+            "conditions' feature to be enabled in Home Assistant Labs settings "
+            f"(feature flag: '{automation.NEW_TRIGGERS_CONDITIONS_FEATURE_FLAG}')"
+        )
+
     try:
         integration = await async_get_integration(hass, platform)
     except IntegrationNotFound:
@@ -976,6 +1005,8 @@ async def async_get_all_descriptions(
     hass: HomeAssistant,
 ) -> dict[str, dict[str, Any] | None]:
     """Return descriptions (i.e. user documentation) for all triggers."""
+    from homeassistant.components import automation  # noqa: PLC0415
+
     descriptions_cache = hass.data[TRIGGER_DESCRIPTION_CACHE]
 
     triggers = hass.data[TRIGGERS]
@@ -984,7 +1015,9 @@ async def async_get_all_descriptions(
     all_triggers = set(triggers)
     previous_all_triggers = set(descriptions_cache)
     # If the triggers are the same, we can return the cache
-    if previous_all_triggers == all_triggers:
+
+    # mypy complains: Invalid index type "HassKey[set[str]]" for "HassDict"
+    if previous_all_triggers | hass.data[TRIGGER_DISABLED_TRIGGERS] == all_triggers:  # type: ignore[index]
         return descriptions_cache
 
     # Files we loaded for missing descriptions
@@ -1022,6 +1055,9 @@ async def async_get_all_descriptions(
     new_descriptions_cache = descriptions_cache.copy()
     for missing_trigger in missing_triggers:
         domain = triggers[missing_trigger]
+        if automation.is_disabled_experimental_trigger(hass, domain):
+            hass.data[TRIGGER_DISABLED_TRIGGERS].add(missing_trigger)
+            continue
 
         if (
             yaml_description := new_triggers_descriptions.get(domain, {}).get(

tests/components/alarm_control_panel/test_trigger.py

@@ -1,12 +1,15 @@
 """Test alarm control panel triggers."""
 
+from collections.abc import Generator
+from unittest.mock import patch
+
 import pytest
 
 from homeassistant.components.alarm_control_panel import (
     AlarmControlPanelEntityFeature,
     AlarmControlPanelState,
 )
-from homeassistant.const import ATTR_SUPPORTED_FEATURES, CONF_ENTITY_ID
+from homeassistant.const import ATTR_LABEL_ID, ATTR_SUPPORTED_FEATURES, CONF_ENTITY_ID
 from homeassistant.core import HomeAssistant, ServiceCall
 from homeassistant.setup import async_setup_component
 
@@ -26,12 +29,48 @@ def stub_blueprint_populate_autouse(stub_blueprint_populate: None) -> None:
     """Stub copying the blueprints to the config folder."""
 
 
+@pytest.fixture(name="enable_experimental_triggers_conditions")
+def enable_experimental_triggers_conditions() -> Generator[None]:
+    """Enable experimental triggers and conditions."""
+    with patch(
+        "homeassistant.components.labs.async_is_preview_feature_enabled",
+        return_value=True,
+    ):
+        yield
+
+
 @pytest.fixture
 async def target_alarm_control_panels(hass: HomeAssistant) -> list[str]:
     """Create multiple alarm control panel entities associated with different targets."""
     return await target_entities(hass, "alarm_control_panel")
 
 
+@pytest.mark.parametrize(
+    "trigger_key",
+    [
+        "alarm_control_panel.armed",
+        "alarm_control_panel.armed_away",
+        "alarm_control_panel.armed_home",
+        "alarm_control_panel.armed_night",
+        "alarm_control_panel.armed_vacation",
+        "alarm_control_panel.disarmed",
+        "alarm_control_panel.triggered",
+    ],
+)
+async def test_alarm_control_panel_triggers_gated_by_labs_flag(
+    hass: HomeAssistant, caplog: pytest.LogCaptureFixture, trigger_key: str
+) -> None:
+    """Test the ACP triggers are gated by the labs flag."""
+    await arm_trigger(hass, trigger_key, None, {ATTR_LABEL_ID: "test_label"})
+    assert (
+        "Unnamed automation failed to setup triggers and has been disabled: Trigger "
+        f"'{trigger_key}' requires the experimental 'New triggers and conditions' "
+        "feature to be enabled in Home Assistant Labs settings (feature flag: "
+        "'new_triggers_conditions')"
+    ) in caplog.text
+
+
+@pytest.mark.usefixtures("enable_experimental_triggers_conditions")
 @pytest.mark.parametrize(
     ("trigger_target_config", "entity_id", "entities_in_target"),
     parametrize_target_entities("alarm_control_panel"),
@@ -142,6 +181,7 @@ async def test_alarm_control_panel_state_trigger_behavior_any(
         service_calls.clear()
 
 
+@pytest.mark.usefixtures("enable_experimental_triggers_conditions")
 @pytest.mark.parametrize(
     ("trigger_target_config", "entity_id", "entities_in_target"),
     parametrize_target_entities("alarm_control_panel"),
@@ -251,6 +291,7 @@ async def test_alarm_control_panel_state_trigger_behavior_first(
         assert len(service_calls) == 0
 
 
+@pytest.mark.usefixtures("enable_experimental_triggers_conditions")
 @pytest.mark.parametrize(
     ("trigger_target_config", "entity_id", "entities_in_target"),
     parametrize_target_entities("alarm_control_panel"),

tests/components/assist_satellite/test_trigger.py

@@ -1,9 +1,12 @@
 """Test assist satellite triggers."""
 
+from collections.abc import Generator
+from unittest.mock import patch
+
 import pytest
 
 from homeassistant.components.assist_satellite.entity import AssistSatelliteState
-from homeassistant.const import CONF_ENTITY_ID
+from homeassistant.const import ATTR_LABEL_ID, CONF_ENTITY_ID
 from homeassistant.core import HomeAssistant, ServiceCall
 from homeassistant.setup import async_setup_component
 
@@ -23,12 +26,45 @@ def stub_blueprint_populate_autouse(stub_blueprint_populate: None) -> None:
     """Stub copying the blueprints to the config folder."""
 
 
+@pytest.fixture(name="enable_experimental_triggers_conditions")
+def enable_experimental_triggers_conditions() -> Generator[None]:
+    """Enable experimental triggers and conditions."""
+    with patch(
+        "homeassistant.components.labs.async_is_preview_feature_enabled",
+        return_value=True,
+    ):
+        yield
+
+
 @pytest.fixture
 async def target_assist_satellites(hass: HomeAssistant) -> list[str]:
     """Create multiple assist satellite entities associated with different targets."""
     return await target_entities(hass, "assist_satellite")
 
 
+@pytest.mark.parametrize(
+    "trigger_key",
+    [
+        "assist_satellite.idle",
+        "assist_satellite.listening",
+        "assist_satellite.processing",
+        "assist_satellite.responding",
+    ],
+)
+async def test_assist_satellite_triggers_gated_by_labs_flag(
+    hass: HomeAssistant, caplog: pytest.LogCaptureFixture, trigger_key: str
+) -> None:
+    """Test the Assist satellite triggers are gated by the labs flag."""
+    await arm_trigger(hass, trigger_key, None, {ATTR_LABEL_ID: "test_label"})
+    assert (
+        "Unnamed automation failed to setup triggers and has been disabled: Trigger "
+        f"'{trigger_key}' requires the experimental 'New triggers and conditions' "
+        "feature to be enabled in Home Assistant Labs settings (feature flag: "
+        "'new_triggers_conditions')"
+    ) in caplog.text
+
+
+@pytest.mark.usefixtures("enable_experimental_triggers_conditions")
 @pytest.mark.parametrize(
     ("trigger_target_config", "entity_id", "entities_in_target"),
     parametrize_target_entities("assist_satellite"),
@@ -96,6 +132,7 @@ async def test_assist_satellite_state_trigger_behavior_any(
         service_calls.clear()
 
 
+@pytest.mark.usefixtures("enable_experimental_triggers_conditions")
 @pytest.mark.parametrize(
     ("trigger_target_config", "entity_id", "entities_in_target"),
     parametrize_target_entities("assist_satellite"),
@@ -162,6 +199,7 @@ async def test_assist_satellite_state_trigger_behavior_first(
         assert len(service_calls) == 0
 
 
+@pytest.mark.usefixtures("enable_experimental_triggers_conditions")
 @pytest.mark.parametrize(
     ("trigger_target_config", "entity_id", "entities_in_target"),
     parametrize_target_entities("assist_satellite"),

tests/components/climate/test_trigger.py

@@ -1,13 +1,16 @@
 """Test climate trigger."""
 
+from collections.abc import Generator
+from unittest.mock import patch
+
 import pytest
 
 from homeassistant.components.climate.const import (
     ATTR_HVAC_ACTION,
     HVACAction,
     HVACMode,
 )
-from homeassistant.const import CONF_ENTITY_ID
+from homeassistant.const import ATTR_LABEL_ID, CONF_ENTITY_ID
 from homeassistant.core import HomeAssistant, ServiceCall
 from homeassistant.setup import async_setup_component
 
@@ -27,12 +30,44 @@ def stub_blueprint_populate_autouse(stub_blueprint_populate: None) -> None:
     """Stub copying the blueprints to the config folder."""
 
 
+@pytest.fixture(name="enable_experimental_triggers_conditions")
+def enable_experimental_triggers_conditions() -> Generator[None]:
+    """Enable experimental triggers and conditions."""
+    with patch(
+        "homeassistant.components.labs.async_is_preview_feature_enabled",
+        return_value=True,
+    ):
+        yield
+
+
 @pytest.fixture
 async def target_climates(hass: HomeAssistant) -> list[str]:
     """Create multiple climate entities associated with different targets."""
     return await target_entities(hass, "climate")
 
 
+@pytest.mark.parametrize(
+    "trigger_key",
+    [
+        "climate.turned_off",
+        "climate.turned_on",
+        "climate.started_heating",
+    ],
+)
+async def test_climate_triggers_gated_by_labs_flag(
+    hass: HomeAssistant, caplog: pytest.LogCaptureFixture, trigger_key: str
+) -> None:
+    """Test the climate triggers are gated by the labs flag."""
+    await arm_trigger(hass, trigger_key, None, {ATTR_LABEL_ID: "test_label"})
+    assert (
+        "Unnamed automation failed to setup triggers and has been disabled: Trigger "
+        f"'{trigger_key}' requires the experimental 'New triggers and conditions' "
+        "feature to be enabled in Home Assistant Labs settings (feature flag: "
+        "'new_triggers_conditions')"
+    ) in caplog.text
+
+
+@pytest.mark.usefixtures("enable_experimental_triggers_conditions")
 @pytest.mark.parametrize(
     ("trigger_target_config", "entity_id", "entities_in_target"),
     parametrize_target_entities("climate"),
@@ -99,6 +134,7 @@ async def test_climate_state_trigger_behavior_any(
         service_calls.clear()
 
 
+@pytest.mark.usefixtures("enable_experimental_triggers_conditions")
 @pytest.mark.parametrize(
     ("trigger_target_config", "entity_id", "entities_in_target"),
     parametrize_target_entities("climate"),
@@ -151,6 +187,7 @@ async def test_climate_state_attribute_trigger_behavior_any(
         service_calls.clear()
 
 
+@pytest.mark.usefixtures("enable_experimental_triggers_conditions")
 @pytest.mark.parametrize(
     ("trigger_target_config", "entity_id", "entities_in_target"),
     parametrize_target_entities("climate"),
@@ -216,6 +253,7 @@ async def test_climate_state_trigger_behavior_first(
         assert len(service_calls) == 0
 
 
+@pytest.mark.usefixtures("enable_experimental_triggers_conditions")
 @pytest.mark.parametrize(
     ("trigger_target_config", "entity_id", "entities_in_target"),
     parametrize_target_entities("climate"),
@@ -267,6 +305,7 @@ async def test_climate_state_attribute_trigger_behavior_first(
         assert len(service_calls) == 0
 
 
+@pytest.mark.usefixtures("enable_experimental_triggers_conditions")
 @pytest.mark.parametrize(
     ("trigger_target_config", "entity_id", "entities_in_target"),
     parametrize_target_entities("climate"),
@@ -331,6 +370,7 @@ async def test_climate_state_trigger_behavior_last(
         service_calls.clear()
 
 
+@pytest.mark.usefixtures("enable_experimental_triggers_conditions")
 @pytest.mark.parametrize(
     ("trigger_target_config", "entity_id", "entities_in_target"),
     parametrize_target_entities("climate"),