Merge branch 'esp8266-native-parallel-extract' into espidf-parallel-tool-extract

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/component_tests/esp32/config/exclusion_reincludes_internal_temperature.yaml

@@ -0,0 +1,11 @@
+esphome:
+  name: test
+
+esp32:
+  board: esp32dev
+  framework:
+    type: esp-idf
+
+sensor:
+  - platform: internal_temperature
+    name: Internal Temperature

tests/component_tests/esp32/config/exclusion_stays_internal_temperature_s3.yaml

@@ -0,0 +1,11 @@
+esphome:
+  name: test
+
+esp32:
+  board: esp32-s3-devkitc-1
+  framework:
+    type: esp-idf
+
+sensor:
+  - platform: internal_temperature
+    name: Internal Temperature

tests/component_tests/esp32/test_esp32.py

@@ -313,6 +313,12 @@ def test_esp32_configuration_errors(
             ("esp_wifi",),
             id="espnow",
         ),
+        pytest.param(
+            # temprature_sens_read() on the original ESP32 lives in the esp_phy blob.
+            "exclusion_reincludes_internal_temperature.yaml",
+            ("esp_phy",),
+            id="internal_temperature",
+        ),
     ],
 )
 def test_default_exclusions_reincluded_by_owning_components(
@@ -337,6 +343,15 @@ def test_default_exclusions_reincluded_by_owning_components(
     assert ("esp_http_server" in excluded) == ("esp_http_server" not in reincluded)
 
 
+def test_esp_phy_stays_excluded_for_internal_temperature_on_newer_variants(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+) -> None:
+    """Only the original ESP32 reads the PHY blob; other variants use esp_driver_tsens."""
+    generate_main(component_config_path("exclusion_stays_internal_temperature_s3.yaml"))
+    assert "esp_phy" in CORE.data[KEY_ESP32][KEY_EXCLUDE_COMPONENTS]
+
+
 def test_nvs_sec_provider_stays_excluded_when_encryption_is_off(
     generate_main: Callable[[str | Path], str],
     component_config_path: Callable[[str], Path],

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/components/lvgl/lvgl-package.yaml

@@ -209,6 +209,63 @@ lvgl:
           position: 212
         - color: 0xFF0000
           position: 255
+    - id: linear_grad
+      direction: LINEAR
+      linear:
+        from_x: 0%
+        from_y: 0%
+        to_x: 100%
+        to_y: 0%
+        extend: REFLECT
+      stops:
+        - color: 0xFF0000
+          position: 0
+        - color: 0x0000FF
+          position: 255
+    - id: radial_grad
+      direction: RADIAL
+      radial:
+        center_x: 50%
+        center_y: 50%
+        to_x: 100%
+        to_y: 50%
+        extend: PAD
+      stops:
+        - color: 0xFFFFFF
+          position: 0
+        - color: 0x000000
+          position: 255
+    - id: radial_focal_grad
+      direction: RADIAL
+      radial:
+        center_x: 50%
+        center_y: 50%
+        to_x: 100%
+        to_y: 50%
+        focal_x: 40%
+        focal_y: 40%
+        focal_radius: 10
+        extend: REPEAT
+      stops:
+        - color: 0xFF0000
+          position: 0
+        - color: 0x0000FF
+          position: 255
+    - id: conical_grad
+      direction: CONICAL
+      conical:
+        center_x: 50%
+        center_y: 50%
+        start_angle: 0
+        end_angle: 360
+        extend: PAD
+      stops:
+        - color: 0xFF0000
+          position: 0
+        - color: 0x00FF00
+          position: 127
+        - color: 0xFF0000
+          position: 255
 
   style_definitions:
     - id: style_test
@@ -1070,6 +1127,14 @@ lvgl:
               logger.log:
                 format: Slider released at %d/%d with value %.0f
                 args: ['(int) point.x', '(int) point.y', x]
+
+        # Exercises the style-application path for a complex gradient, not just its
+        # lv_grad_*_init() codegen: the other new gradients are only ever declared.
+        - obj:
+            bg_opa: cover
+            bg_grad: conical_grad
+            width: 40
+            height: 40
         - button:
             styles: spin_button
             id: spin_up

tests/components/modbus/common.h

@@ -11,7 +11,14 @@ namespace esphome::modbus::testing {
 // A UART that discards all writes, for tests that never inspect the wire.
 class NullUART : public uart::UARTComponent {
  public:
-  NullUART() { this->set_baud_rate(115200); }
+  // 8N1, matching what the uart schema emits for a real hub; the framing drives the modbus
+  // interframe timing, so leaving data/stop bits at their zero defaults would not be representative.
+  NullUART() {
+    this->set_baud_rate(115200);
+    this->set_data_bits(8);
+    this->set_stop_bits(1);
+    this->set_parity(uart::UART_CONFIG_PARITY_NONE);
+  }
   void write_array(const uint8_t *data, size_t len) override {}
   bool peek_byte(uint8_t *data) override { return false; }
   bool read_array(uint8_t *data, size_t len) override { return false; }

tests/components/modbus/modbus_framing_test.cpp

@@ -0,0 +1,64 @@
+#include <gtest/gtest.h>
+
+#include <cstdint>
+
+#include "common.h"
+#include "esphome/components/modbus/modbus.h"
+
+namespace esphome::modbus::testing {
+
+namespace {
+
+// Exposes the timing values setup() derives from the UART framing.
+class FramingProbeHub : public ModbusClientHub {
+ public:
+  uint32_t bits_per_char() const { return this->bits_per_char_; }
+  uint32_t frame_delay_us() const { return this->frame_delay_us_; }
+};
+
+class FramedUART : public NullUART {
+ public:
+  FramedUART(uint32_t baud_rate, uint8_t data_bits, uint8_t stop_bits, uart::UARTParityOptions parity) {
+    this->set_baud_rate(baud_rate);
+    this->set_data_bits(data_bits);
+    this->set_stop_bits(stop_bits);
+    this->set_parity(parity);
+  }
+};
+
+}  // namespace
+
+// 8N1 is 10 bits on the wire, so t3.5 at 9600 baud is 3.5 * 10 / 9600 = 3645.8us.
+TEST(ModbusFraming, EightNoneOneDerivesTenBits) {
+  FramedUART uart(9600, 8, 1, uart::UART_CONFIG_PARITY_NONE);
+  FramingProbeHub hub;
+  hub.set_uart_parent(&uart);
+  hub.setup();
+
+  EXPECT_EQ(hub.bits_per_char(), 10u);
+  EXPECT_EQ(hub.frame_delay_us(), 3646u);
+}
+
+// Spec-conformant RTU framing is 11 bits, which lengthens the interframe gap to
+// 3.5 * 11 / 9600 = 4010.4us, rounded up.
+TEST(ModbusFraming, EightEvenOneDerivesElevenBits) {
+  FramedUART uart(9600, 8, 1, uart::UART_CONFIG_PARITY_EVEN);
+  FramingProbeHub hub;
+  hub.set_uart_parent(&uart);
+  hub.setup();
+
+  EXPECT_EQ(hub.bits_per_char(), 11u);
+  EXPECT_EQ(hub.frame_delay_us(), 4011u);
+}
+
+// Above 19200 baud the spec's fixed 1750us floor governs instead of 3.5 characters.
+TEST(ModbusFraming, FastBaudUsesSpecFloor) {
+  FramedUART uart(115200, 8, 1, uart::UART_CONFIG_PARITY_NONE);
+  FramingProbeHub hub;
+  hub.set_uart_parent(&uart);
+  hub.setup();
+
+  EXPECT_EQ(hub.frame_delay_us(), 1750u);
+}
+
+}  // namespace esphome::modbus::testing

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)

tests/unit_tests/components/esp32/test_sdkconfig.py

@@ -0,0 +1,72 @@
+"""Tests for the esp32 sdkconfig write and its toolchain-gated clean."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import time
+from unittest.mock import patch
+
+import pytest
+
+from esphome.components.esp32 import _write_sdkconfig
+from esphome.components.esp32.const import KEY_SDKCONFIG_OPTIONS
+from esphome.const import KEY_CORE, KEY_ESP32, KEY_FRAMEWORK_VERSION, Toolchain
+from esphome.core import CORE
+from esphome.espidf.toolchain import has_outdated_files
+
+
+def _setup_core(tmp_path: Path, toolchain: Toolchain | None) -> None:
+    CORE.config_path = tmp_path / "test.yaml"
+    CORE.build_path = tmp_path
+    CORE.toolchain = toolchain
+    CORE.data[KEY_ESP32] = {KEY_SDKCONFIG_OPTIONS: {"CONFIG_X": "y"}}
+    CORE.data[KEY_CORE] = {KEY_FRAMEWORK_VERSION: "5.5.5"}
+
+
+def _seed_configured_build(tmp_path: Path) -> None:
+    """A settled native build: configure outputs predate what comes next."""
+    build = tmp_path / "build"
+    (build / "config").mkdir(parents=True)
+    (build / "config" / "sdkconfig.h").write_text("")
+    (build / "CMakeCache.txt").write_text("")
+    (build / "build.ninja").write_text("")
+    # Explicitly older than what the test writes next: has_outdated_files()
+    # compares st_mtime with a strict >, so same-tick writes would pass
+    past = time.time() - 60
+    for f in build.rglob("*"):
+        os.utime(f, (past, past))
+
+
+@pytest.mark.parametrize(
+    ("toolchain", "clean_expected"),
+    [(Toolchain.ESP_IDF, False), (Toolchain.PLATFORMIO, True), (None, True)],
+)
+def test_write_sdkconfig_cleans_only_on_platformio(
+    tmp_path: Path, toolchain: Toolchain | None, clean_expected: bool
+) -> None:
+    """A changed sdkconfig forces a full clean only under PlatformIO; the
+    esp-idf toolchain reconfigures via has_outdated_files() instead; an
+    unresolved toolchain fails safe onto the clean."""
+    _setup_core(tmp_path, toolchain)
+    _seed_configured_build(tmp_path)
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.components.esp32.clean_build") as clean,
+    ):
+        _write_sdkconfig()
+        assert "CONFIG_X" in CORE.relative_build_path("sdkconfig.test").read_text()
+        assert clean.called is clean_expected
+        if clean_expected:
+            clean.assert_called_once_with(clear_pio_cache=False)
+        # The change must still trigger a reconfigure: the internal
+        # sdkconfig snapshot is now newer than build/CMakeCache.txt
+        assert has_outdated_files() is True
+        clean.reset_mock()
+        # A settled configure restamps the cache; an unchanged rewrite
+        # must then neither clean nor mark the build stale
+        future = time.time() + 60
+        os.utime(CORE.relative_build_path("build/CMakeCache.txt"), (future, future))
+        _write_sdkconfig()
+        clean.assert_not_called()
+        assert has_outdated_files() is False

tests/unit_tests/core/test_config.py

@@ -1127,6 +1127,34 @@ def test_config_hash_same_for_different_config_dirs(tmp_path: Path) -> None:
     assert hash1 == hash2
 
 
+def test_config_hash_same_for_different_data_dirs(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Test that downloaded file paths hash the same wherever data_dir lives."""
+    config_dir = tmp_path / "config"
+    config_dir.mkdir()
+
+    CORE.reset()
+    CORE.config_path = config_dir / "device.yaml"
+    CORE.config = {
+        "esphome": {"name": "test"},
+        "file": config_dir / ".esphome" / "image" / "c44630d6",
+    }
+    hash1 = CORE.config_hash
+
+    other_data_dir = tmp_path / "data"
+    CORE.reset()
+    monkeypatch.setenv("ESPHOME_DATA_DIR", str(other_data_dir))
+    CORE.config_path = config_dir / "device.yaml"
+    CORE.config = {
+        "esphome": {"name": "test"},
+        "file": other_data_dir / "image" / "c44630d6",
+    }
+    hash2 = CORE.config_hash
+
+    assert hash1 == hash2
+
+
 def test_make_app_name_cpp_no_mac_simple() -> None:
     """Test simple name without MAC suffix returns string literal."""
     cpp_expr, global_decl, byte_len = make_app_name_cpp(

tests/unit_tests/test_yaml_util.py

@@ -1706,6 +1706,53 @@ def test_dump_path_dotdot_reference_outside_anchor() -> None:
     assert output.strip() == "file: ../shared/font.ttf"
 
 
+@pytest.mark.parametrize(
+    "data_dir",
+    [
+        pytest.param(Path("/config/.esphome"), id="cli"),
+        pytest.param(Path("/data"), id="addon"),
+    ],
+)
+def test_dump_path_under_data_dir_uses_default_location(data_dir: Path) -> None:
+    """Test that Path values under data_dir dump as .esphome/<rest> for any layout."""
+    anchor = Path("/config").absolute()
+    path = data_dir.absolute() / "image" / "c44630d6"
+    output = yaml_util.dump(
+        {"file": path}, relative_to=anchor, data_dir=data_dir.absolute()
+    )
+    assert output.strip() == "file: .esphome/image/c44630d6"
+
+
+def test_dump_path_equal_to_data_dir() -> None:
+    """Test that the data dir itself dumps as .esphome, matching the default layout."""
+    anchor = Path("/config").absolute()
+    data_dir = Path("/data").absolute()
+    output = yaml_util.dump({"dir": data_dir}, relative_to=anchor, data_dir=data_dir)
+    assert output.strip() == "dir: .esphome"
+    default = yaml_util.dump(
+        {"dir": anchor / ".esphome"}, relative_to=anchor, data_dir=anchor / ".esphome"
+    )
+    assert default == output
+
+
+def test_dump_path_outside_data_dir_still_relative_to_anchor() -> None:
+    """Test that data_dir does not affect paths that are not under it."""
+    anchor = Path("/config").absolute()
+    path = anchor / "fonts" / "arial.ttf"
+    output = yaml_util.dump(
+        {"file": path}, relative_to=anchor, data_dir=Path("/data").absolute()
+    )
+    assert output.strip() == "file: fonts/arial.ttf"
+
+
+def test_dump_path_data_dir_without_relative_to_is_unchanged() -> None:
+    """Test that data_dir alone does not change the output."""
+    data_dir = Path("/data").absolute()
+    path = data_dir / "image" / "c44630d6"
+    output = yaml_util.dump({"file": path}, data_dir=data_dir)
+    assert output.strip() == f"file: {path}"
+
+
 def test_dump_relative_to_does_not_leak_between_calls() -> None:
     """Test that the relative_to flag is scoped to a single dump call."""
     anchor = Path("/config/esphome").absolute()