[api] Add description and example metadata to user-defined actions (#18881)

Co-authored-by: J. Nick Koston <nick@home-assistant.io>

tests/component_tests/api/test_action_metadata.py

@@ -0,0 +1,155 @@
+"""Tests for user-defined action field metadata (description / example)."""
+
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+from esphome.components.api import (
+    _action_strings,
+    _action_strings_size,
+    _has_action_metadata,
+    _validate_esp8266_action_strings,
+    validate_variable,
+)
+from esphome.config_validation import Invalid
+from esphome.const import PlatformFramework
+from esphome.core import CORE
+from esphome.cpp_generator import safe_exp
+from esphome.helpers import fnv1_hash
+from tests.component_tests.helpers import get_define_value
+from tests.component_tests.types import SetCoreConfigCallable
+
+CONFIG = "tests/component_tests/api/test_action_metadata.yaml"
+CONFIG_ESP8266 = "tests/component_tests/api/test_action_metadata_esp8266.yaml"
+CONFIG_SHORTHAND = "tests/component_tests/api/test_action_metadata_shorthand.yaml"
+
+
+def test_metadata_is_emitted_as_progmem_table(
+    generate_main: Callable[[str | Path], str],
+) -> None:
+    """Every action string is a PROGMEM array referenced from one PROGMEM table."""
+    main_cpp = generate_main(CONFIG)
+
+    assert (
+        'static constexpr char api_action_str0[] PROGMEM = "play_buzzer";' in main_cpp
+    )
+    assert (
+        'static constexpr char api_action_str1[] PROGMEM = "Play an RTTTL melody on the buzzer";'
+        in main_cpp
+    )
+    assert (
+        'static constexpr char api_action_str4[] PROGMEM = "two_short:d=4,o=5,b=100:16e6,16e6";'
+        in main_cpp
+    )
+    assert (
+        "static constexpr const char * api_action0_strings[] PROGMEM = {"
+        "api_action_str0, api_action_str1, api_action_str2, api_action_str3, "
+        "api_action_str4, api_action_str5, nullptr, nullptr};" in main_cpp
+    )
+    # An action without metadata still carries the metadata slots (as nullptr)
+    assert (
+        "static constexpr const char * api_action1_strings[] PROGMEM = {"
+        "api_action_str6, nullptr, api_action_str7, nullptr, nullptr};" in main_cpp
+    )
+    assert f"(api_action0_strings, {safe_exp(fnv1_hash('play_buzzer'))});" in main_cpp
+    assert "USE_API_USER_DEFINED_ACTION_METADATA" in {d.name for d in CORE.defines}
+    assert get_define_value("API_USER_ACTION_STRINGS_SCRATCH_SIZE") is None
+
+
+def test_esp8266_sizes_scratch_buffer_for_largest_action(
+    generate_main: Callable[[str | Path], str],
+) -> None:
+    """ESP8266 gets a scratch buffer define equal to the byte total of the largest action."""
+    generate_main(CONFIG_ESP8266)
+
+    # play_buzzer: name, description, two variable names, one description, one example,
+    # each with a terminator
+    assert get_define_value("API_USER_ACTION_STRINGS_SCRATCH_SIZE") == "117"
+
+
+def test_shorthand_variables_emit_no_metadata(
+    generate_main: Callable[[str | Path], str],
+) -> None:
+    """The name: type shorthand emits a name-only table and no define."""
+    main_cpp = generate_main(CONFIG_SHORTHAND)
+
+    assert (
+        "static constexpr const char * api_action0_strings[] PROGMEM = "
+        "{api_action_str0, api_action_str1};" in main_cpp
+    )
+    assert "USE_API_USER_DEFINED_ACTION_METADATA" not in {d.name for d in CORE.defines}
+
+
+def test_variable_shorthand_normalizes_to_mapping() -> None:
+    """A bare type string validates to the mapping form."""
+    assert validate_variable("string") == {"type": "string"}
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        {"description": "no type given"},
+        {"type": "string", "selector": "text"},
+        "stringy",
+        {"type": "stringy"},
+    ],
+)
+def test_variable_rejects_invalid(value: object) -> None:
+    """Missing or unknown type and unknown keys raise in both forms."""
+    with pytest.raises(Invalid):
+        validate_variable(value)
+
+
+def _oversized_action_config() -> dict:
+    return {
+        "actions": [
+            {
+                "action": "big",
+                "description": "x" * 300,
+                "variables": {"a": {"type": "string", "example": "y" * 300}},
+            }
+        ]
+    }
+
+
+def test_esp8266_rejects_actions_over_string_budget(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    set_core_config(PlatformFramework.ESP8266_ARDUINO)
+    with pytest.raises(Invalid, match="ESP8266 allows at most 384 bytes"):
+        _validate_esp8266_action_strings(_oversized_action_config())
+
+
+def test_other_platforms_have_no_string_budget(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    set_core_config(PlatformFramework.ESP32_IDF)
+    config = _oversized_action_config()
+    assert _validate_esp8266_action_strings(config) is config
+
+
+def test_empty_metadata_is_unset_and_not_counted() -> None:
+    """An empty description or example emits nullptr and takes no scratch space."""
+    conf = {
+        "action": "a",
+        "description": "",
+        "variables": {"b": {"type": "int", "description": "", "example": "ex"}},
+    }
+    strings = _action_strings(conf, has_metadata=True)
+    assert strings == ["a", None, "b", None, "ex"]
+    # Every emitted string counts its terminator: "a" + "b" + "ex"
+    assert _action_strings_size(strings) == 2 + 2 + 3
+
+
+def test_empty_metadata_does_not_enable_the_define() -> None:
+    actions = [
+        {
+            "action": "a",
+            "description": "",
+            "variables": {"b": {"type": "int", "example": ""}},
+        }
+    ]
+    assert not _has_action_metadata(actions)
+    actions[0]["variables"]["b"]["example"] = "1"
+    assert _has_action_metadata(actions)

tests/component_tests/api/test_action_metadata.yaml

@@ -0,0 +1,14 @@
+esphome:
+  name: test
+
+esp32:
+  board: esp32dev
+
+wifi:
+  ssid: MySSID
+  password: password1
+
+logger:
+
+packages:
+  api: !include test_action_metadata_common.yaml

tests/component_tests/api/test_action_metadata_common.yaml

@@ -0,0 +1,18 @@
+api:
+  actions:
+    - action: play_buzzer
+      description: Play an RTTTL melody on the buzzer
+      variables:
+        song_str:
+          type: string
+          description: RTTTL melody string
+          example: "two_short:d=4,o=5,b=100:16e6,16e6"
+        volume:
+          type: int
+      then:
+        - logger.log: Action Called
+    - action: plain_action
+      variables:
+        value: int
+      then:
+        - logger.log: Action Called

tests/component_tests/api/test_action_metadata_esp8266.yaml

@@ -0,0 +1,14 @@
+esphome:
+  name: test
+
+esp8266:
+  board: d1_mini
+
+wifi:
+  ssid: MySSID
+  password: password1
+
+logger:
+
+packages:
+  api: !include test_action_metadata_common.yaml

tests/component_tests/api/test_action_metadata_shorthand.yaml

@@ -0,0 +1,19 @@
+esphome:
+  name: test
+
+esp32:
+  board: esp32dev
+
+wifi:
+  ssid: MySSID
+  password: password1
+
+logger:
+
+api:
+  actions:
+    - action: plain_action
+      variables:
+        value: int
+      then:
+        - logger.log: Action Called

tests/component_tests/api/test_homeassistant_action.py

@@ -9,7 +9,7 @@ def test_synchronous_chain_keeps_zero_copy_args(generate_main):
 
     assert (
         "api::UserServiceTrigger<api::enums::SUPPORTS_RESPONSE_NONE, StringRef>"
-        '("zero_copy_args", {"message"})' in main_cpp
+        "(api_action0_strings," in main_cpp
     )
 
 
@@ -22,7 +22,7 @@ def test_response_callback_args_are_owning(generate_main):
 
     assert (
         "api::UserServiceTrigger<api::enums::SUPPORTS_RESPONSE_NONE, std::string>"
-        '("response_args", {"message"})' in main_cpp
+        "(api_action1_strings," in main_cpp
     )
     assert "api::HomeAssistantServiceCallAction<std::string>" in main_cpp
     assert "api::HomeAssistantServiceCallAction<StringRef>" not in main_cpp

tests/components/api/common-base.yaml

@@ -61,8 +61,12 @@ api:
   reboot_timeout: 0min
   actions:
     - action: hello_world
+      description: Log a greeting
       variables:
-        name: string
+        name:
+          type: string
+          description: Name to greet
+          example: World
       then:
         - logger.log:
             format: Hello World %s!

tests/components/api/common.yaml

@@ -1,4 +1,5 @@
-<<: !include common-base.yaml
+packages:
+  base: !include common-base.yaml
 
 api:
   encryption:

tests/integration/fixtures/api_action_metadata.yaml

@@ -0,0 +1,26 @@
+esphome:
+  name: api-action-metadata-test
+host:
+api:
+  batch_delay: 0ms
+  actions:
+    - action: play_buzzer
+      description: Play an RTTTL melody on the buzzer
+      variables:
+        song_str:
+          type: string
+          description: RTTTL melody string
+          example: "two_short:d=4,o=5,b=100:16e6,16e6"
+        volume:
+          type: int
+      then:
+        - logger.log:
+            format: "Buzzer: %s"
+            args: [song_str.c_str()]
+    - action: plain_action
+      variables:
+        value: int
+      then:
+        - logger.log: "Plain action called"
+
+logger:

tests/integration/test_api_action_metadata.py

@@ -0,0 +1,65 @@
+"""Integration test for user-defined action field metadata."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+
+import pytest
+
+from esphome.helpers import fnv1_hash
+
+from .types import APIClientConnectedFactory, RunCompiledFunction
+
+
+@pytest.mark.asyncio
+async def test_api_action_metadata(
+    yaml_config: str,
+    run_compiled: RunCompiledFunction,
+    api_client_connected: APIClientConnectedFactory,
+) -> None:
+    """Action and argument metadata reach the client and the actions still run."""
+    loop = asyncio.get_running_loop()
+    buzzer_called = loop.create_future()
+    plain_called = loop.create_future()
+    buzzer_pattern = re.compile(r"Buzzer: two_short")
+    plain_pattern = re.compile(r"Plain action called")
+
+    def check_output(line: str) -> None:
+        if not buzzer_called.done() and buzzer_pattern.search(line):
+            buzzer_called.set_result(True)
+        elif not plain_called.done() and plain_pattern.search(line):
+            plain_called.set_result(True)
+
+    async with (
+        run_compiled(yaml_config, line_callback=check_output),
+        api_client_connected() as client,
+    ):
+        _, services = await client.list_entities_services()
+
+        by_name = {service.name: service for service in services}
+        assert set(by_name) == {"play_buzzer", "plain_action"}
+        # Keys are hashed at codegen time and must match what the client expects
+        for name, service in by_name.items():
+            assert service.key == fnv1_hash(name), name
+
+        buzzer = by_name["play_buzzer"]
+        assert buzzer.description == "Play an RTTTL melody on the buzzer"
+        args = {arg.name: arg for arg in buzzer.args}
+        assert args["song_str"].description == "RTTTL melody string"
+        assert args["song_str"].example == "two_short:d=4,o=5,b=100:16e6,16e6"
+        # An arg without metadata sends empty strings
+        assert args["volume"].description == ""
+        assert args["volume"].example == ""
+
+        # An action without metadata sends empty strings
+        plain = by_name["plain_action"]
+        assert plain.description == ""
+        assert plain.args[0].description == ""
+
+        await client.execute_service(
+            buzzer, {"song_str": "two_short:d=4,o=5,b=100:16e6,16e6", "volume": 3}
+        )
+        await client.execute_service(plain, {"value": 1})
+        await asyncio.wait_for(buzzer_called, timeout=5.0)
+        await asyncio.wait_for(plain_called, timeout=5.0)