Merge branch 'neutral-ble-client' into radon-eye-single-node

tests/benchmarks/components/api/__init__.py

@@ -15,6 +15,7 @@ def override_manifest(manifest: ComponentManifestOverride) -> None:
         # components have hardware dependencies (BLE/UART/RMT); lightweight
         # stub headers in tests/benchmarks/stubs/ satisfy the includes.
         cg.add_define("USE_BLUETOOTH_PROXY")
+        cg.add_define("USE_BLUETOOTH_PROXY_CONNECTIONS")
         cg.add_define("BLUETOOTH_PROXY_MAX_CONNECTIONS", 3)
         cg.add_define("BLUETOOTH_PROXY_ADVERTISEMENT_BATCH_SIZE", 16)
         cg.add_define("USE_ZWAVE_PROXY")

tests/component_tests/bk72xx_ble/config/test_bk7231n.yaml

@@ -0,0 +1,7 @@
+esphome:
+  name: bk-family-gate-n
+
+bk72xx:
+  board: cb2s
+
+bk72xx_ble:

tests/component_tests/bk72xx_ble/config/test_bk7231q.yaml

@@ -0,0 +1,7 @@
+esphome:
+  name: bk-family-gate-q
+
+bk72xx:
+  board: wa2
+
+bk72xx_ble:

tests/component_tests/bk72xx_ble/config/test_bk7231t.yaml

@@ -0,0 +1,7 @@
+esphome:
+  name: bk-family-gate-t
+
+bk72xx:
+  board: generic-bk7231t-qfn32-tuya
+
+bk72xx_ble:

tests/component_tests/bk72xx_ble/config/test_bk7252.yaml

@@ -0,0 +1,7 @@
+esphome:
+  name: bk-family-gate-7252
+
+bk72xx:
+  board: generic-bk7252
+
+bk72xx_ble:

tests/component_tests/bk72xx_ble/test_family_gate.py

@@ -0,0 +1,40 @@
+"""The non-5.x family rejection lives in to_code (config validation must stay
+family-agnostic for the validate-only CI fixtures), so codegen is the only
+place it can be pinned."""
+
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+from esphome.core import EsphomeError
+
+
+@pytest.mark.parametrize(
+    ("config_file", "match"),
+    [
+        ("test_bk7231t.yaml", "BK7231T.*BLE 4.2"),
+        ("test_bk7252.yaml", "BK7251.*BLE 4.2"),
+        ("test_bk7231q.yaml", "BK7231Q.*no BLE"),
+    ],
+)
+def test_unsupported_family_rejected(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+    config_file: str,
+    match: str,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    with pytest.raises(EsphomeError, match=match):
+        generate_main(component_config_path(config_file))
+    # Validation itself must not fail (CI validate fixtures run on a BLE 4.2
+    # board), but it warns before codegen raises.
+    assert "cannot compile" in caplog.text
+
+
+def test_ble5_family_generates(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+) -> None:
+    main_cpp = generate_main(component_config_path("test_bk7231n.yaml"))
+    assert "bk72xx_ble::BK72xxBLE" in main_cpp

tests/component_tests/ble_device_base/config/bk72xx_controller_only.yaml

@@ -2,6 +2,6 @@ esphome:
   name: slotcount-controller
 
 bk72xx:
-  board: generic-bk7252
+  board: cb2s
 
 bk72xx_ble:

tests/component_tests/ble_device_base/config/bk72xx_tracker.yaml

@@ -2,6 +2,6 @@ esphome:
   name: slotcount-tracker
 
 bk72xx:
-  board: generic-bk7252
+  board: cb2s
 
 bk72xx_ble_tracker:

tests/component_tests/ble_device_base/test_scan_parameter_validation.py

@@ -57,7 +57,12 @@ def test_bk72xx_defaults_are_valid() -> None:
 
 
 def test_esp32_defaults_are_valid() -> None:
-    """esp32 pins the ESP-IDF reference rate and exposes active (default on)."""
+    """esp32 pins the ESP-IDF reference rate and exposes active (default on).
+
+    Without wifi loaded, the conditional window default falls back to the
+    historical 30 ms; the wifi-aware resolution is covered by the
+    esp32_ble_tracker component tests.
+    """
     config = ESP32_SCHEMA({})
     assert to_ble_units(config["interval"]) == 512
     assert to_ble_units(config["window"]) == 48

tests/component_tests/esp32_ble_tracker/test_scan_window_default.py

@@ -0,0 +1,122 @@
+"""Tests for the esp32_ble_tracker conditional scan window default.
+
+The scan window default depends on wifi coexistence and the IDF version:
+IDF 5.5.5 fixed a coexistence bug where BLE scans ran far longer than the
+configured window (espressif/esp-idf#18931), so on fixed versions the
+historical 30 ms default would only listen 9.4 % of the time and miss most
+advertisements. With the coexistence arbiter compiled in on a fixed IDF, the
+window instead defaults to the interval, as Espressif recommends; without the
+arbiter a full-duty scan would starve wifi, so the 30 ms default is kept.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import pytest
+
+from esphome import config_validation as cv
+from esphome.components.ble_device_base import to_ble_units
+from esphome.components.const import CONF_SCAN_PARAMETERS, CONF_WINDOW
+from esphome.components.esp32 import KEY_IDF_VERSION
+from esphome.components.esp32_ble_tracker import (
+    CONF_SOFTWARE_COEXISTENCE,
+    CONFIG_SCHEMA,
+)
+from esphome.const import CONF_INTERVAL, PlatformFramework
+from esphome.core import CORE
+from esphome.types import ConfigType
+
+from ..types import SetCoreConfigCallable
+
+
+@pytest.fixture
+def stage_esp32(
+    set_core_config: SetCoreConfigCallable,
+) -> Callable[..., None]:
+    """Stage an esp32 build with a given IDF version and wifi presence."""
+
+    def stage(idf: str, *, wifi: bool) -> None:
+        set_core_config(
+            PlatformFramework.ESP32_IDF,
+            platform_data={KEY_IDF_VERSION: cv.Version.parse(idf)},
+        )
+        if wifi:
+            # Makes cv.OnlyWith default software_coexistence to True, exactly
+            # as a real config with wifi: does.
+            CORE.loaded_integrations.add("wifi")
+
+    return stage
+
+
+def _scan_params(config: ConfigType) -> ConfigType:
+    return CONFIG_SCHEMA(config)[CONF_SCAN_PARAMETERS]
+
+
+@pytest.mark.parametrize(
+    ("idf", "config", "expected_units"),
+    [
+        ("5.5.5", {}, 512),  # first fixed version, default 320 ms interval
+        ("6.0.1", {}, 512),  # any newer version behaves the same
+        # Follows a user-set interval.
+        ("5.5.5", {"scan_parameters": {"interval": "1s"}}, 1600),
+    ],
+)
+def test_wifi_on_fixed_idf_defaults_window_to_interval(
+    stage_esp32: Callable[..., None],
+    idf: str,
+    config: ConfigType,
+    expected_units: int,
+) -> None:
+    """With wifi coexistence on a fixed IDF, the window defaults to the interval."""
+    stage_esp32(idf, wifi=True)
+    params = _scan_params(config)
+    assert params[CONF_WINDOW] == params[CONF_INTERVAL]
+    assert to_ble_units(params[CONF_WINDOW]) == expected_units
+
+
+@pytest.mark.parametrize(
+    ("idf", "wifi", "config"),
+    [
+        # Buggy IDF over-scans anyway; keep the 30 ms default.
+        ("5.5.4", True, {}),
+        # No wifi (e.g. ethernet) means no radio contention.
+        ("5.5.5", False, {}),
+        # Coexistence disabled: no arbiter, so a full-duty scan would starve
+        # wifi outright.
+        ("5.5.5", True, {CONF_SOFTWARE_COEXISTENCE: False}),
+    ],
+)
+def test_30ms_default_kept(
+    stage_esp32: Callable[..., None],
+    idf: str,
+    wifi: bool,
+    config: ConfigType,
+) -> None:
+    stage_esp32(idf, wifi=wifi)
+    assert to_ble_units(_scan_params(config)[CONF_WINDOW]) == 48
+
+
+@pytest.mark.parametrize("window", ["60ms", "30ms"])
+def test_explicit_window_is_never_touched(
+    stage_esp32: Callable[..., None], window: str
+) -> None:
+    """A user-set window wins over the conditional default.
+
+    The explicit 30 ms case matters: it is indistinguishable from the
+    defaulted value by inspection, so the defaulted flag must separate them.
+    """
+    stage_esp32("5.5.5", wifi=True)
+    params = _scan_params({"scan_parameters": {"window": window}})
+    assert to_ble_units(params[CONF_WINDOW]) == to_ble_units(
+        cv.positive_time_period(window)
+    )
+
+
+def test_short_interval_without_window_still_rejected(
+    stage_esp32: Callable[..., None],
+) -> None:
+    """The provisional 30 ms default validates against the interval as before."""
+    stage_esp32("5.5.5", wifi=True)
+    with pytest.raises(cv.Invalid, match="needs to be smaller than scan interval"):
+        _scan_params({"scan_parameters": {"interval": "20ms"}})

tests/component_tests/esp32_hosted/test_init.py

@@ -0,0 +1,35 @@
+"""Tests for the esp32_hosted ESP-IDF version gate."""
+
+import pytest
+
+from esphome import config_validation as cv
+from esphome.components.esp32 import KEY_IDF_VERSION
+from esphome.components.esp32_hosted import _final_validate
+from esphome.const import PlatformFramework
+
+from ..types import SetCoreConfigCallable
+
+
+@pytest.mark.parametrize("idf", ["5.3.0", "5.4.2", "5.5.5"])
+def test_final_validate_accepts_supported_idf(
+    set_core_config: SetCoreConfigCallable, idf: str
+) -> None:
+    """ESP-IDF 5.3 and newer passes validation unchanged."""
+    set_core_config(
+        PlatformFramework.ESP32_IDF,
+        platform_data={KEY_IDF_VERSION: cv.Version.parse(idf)},
+    )
+    _final_validate({})
+
+
+@pytest.mark.parametrize("idf", ["5.0.0", "5.2.2"])
+def test_final_validate_rejects_old_idf(
+    set_core_config: SetCoreConfigCallable, idf: str
+) -> None:
+    """ESP-IDF older than 5.3 is rejected with a clear error."""
+    set_core_config(
+        PlatformFramework.ESP32_IDF,
+        platform_data={KEY_IDF_VERSION: cv.Version.parse(idf)},
+    )
+    with pytest.raises(cv.Invalid, match="requires ESP-IDF 5.3 or newer"):
+        _final_validate({})

tests/component_tests/gpio_expander/test_init.py

@@ -0,0 +1,61 @@
+"""Tests for the shared io expander interrupt_pin validator."""
+
+from __future__ import annotations
+
+import importlib
+
+import pytest
+
+from esphome import config_validation as cv
+from esphome.components.esp32 import KEY_BOARD, KEY_VARIANT, VARIANT_ESP32
+from esphome.components.gpio_expander import validate_interrupt_pin
+from esphome.const import PlatformFramework
+from tests.component_tests.types import SetCoreConfigCallable
+
+
+@pytest.fixture
+def stage_esp32(set_core_config: SetCoreConfigCallable) -> None:
+    set_core_config(
+        PlatformFramework.ESP32_IDF,
+        platform_data={KEY_BOARD: "esp32dev", KEY_VARIANT: VARIANT_ESP32},
+    )
+
+
+def test_plain_pin_accepted(stage_esp32: None) -> None:
+    value = validate_interrupt_pin(
+        {"number": 16, "mode": {"input": True, "pullup": True}}
+    )
+    assert value["number"] == 16
+
+
+def test_inverted_rejected(stage_esp32: None) -> None:
+    with pytest.raises(cv.Invalid, match="'inverted: true' is not supported"):
+        validate_interrupt_pin({"number": 16, "inverted": True})
+
+
+def test_allow_other_uses_rejected(stage_esp32: None) -> None:
+    with pytest.raises(cv.Invalid, match="'allow_other_uses: true' is not supported"):
+        validate_interrupt_pin({"number": 16, "allow_other_uses": True})
+
+
+# mcp23017 covers the shared mcp23xxx_base schema
+@pytest.mark.parametrize(
+    "component",
+    [
+        "pcf8574",
+        "pca9554",
+        "tca9555",
+        "pca6416a",
+        "pi4ioe5v6408",
+        "mcp23016",
+        "mcp23017",
+    ],
+)
+def test_component_schemas_route_through_validator(
+    stage_esp32: None, component: str
+) -> None:
+    module = importlib.import_module(f"esphome.components.{component}")
+    with pytest.raises(cv.Invalid, match="'inverted: true' is not supported"):
+        module.CONFIG_SCHEMA(
+            {"id": "expander_hub", "interrupt_pin": {"number": 16, "inverted": True}}
+        )

tests/component_tests/image/test_init.py

@@ -21,16 +21,20 @@ from esphome.components.image import (
     CONF_OPAQUE,
     CONF_TRANSPARENCY,
     PLATFORM_FILE,
+    _expand_platform_entry,
     _flatten_legacy_image_config,
     _is_legacy_image_format,
     _is_new_image_format,
     _migrate_legacy_image_config,
+    expand_platform_config,
     get_all_image_metadata,
     get_image_metadata,
 )
 from esphome.const import (
+    CONF_DEFAULTS,
     CONF_DITHER,
     CONF_FILE,
+    CONF_FILES,
     CONF_ID,
     CONF_PLATFORM,
     CONF_RAW_DATA_ID,
@@ -259,6 +263,15 @@ def test_flatten_keeps_byte_order_for_endian_type() -> None:
     assert out[0][CONF_BYTE_ORDER] == "little_endian"
 
 
+def test_flatten_drops_byte_order_written_directly_on_legacy_entry() -> None:
+    """The legacy flattener drops an incompatible byte_order even when written directly on the entry."""
+    out = _flatten_legacy_image_config(
+        {"binary": [{"id": "a", "file": "x.png", "byte_order": "little_endian"}]}
+    )
+    assert out == [{"id": "a", "file": "x.png", "type": "binary"}]
+    assert CONF_BYTE_ORDER not in out[0]
+
+
 def test_flatten_skips_meta_and_unknown_keys() -> None:
     out = _flatten_legacy_image_config(
         {
@@ -342,6 +355,42 @@ def test_migrate_legacy_warns_and_prepends_platform(
         ),
         pytest.param({"foo": 1}, False, id="dict_unknown_keys"),
         pytest.param("a string", False, id="scalar"),
+        # A `platform:`-tagged dict is the new format written without list brackets.
+        pytest.param(
+            {CONF_PLATFORM: "file", "id": "a", "file": "x.png"},
+            False,
+            id="platform_tagged_flat_dict",
+        ),
+        pytest.param(
+            {
+                CONF_PLATFORM: "file",
+                "defaults": {"type": "rgb565"},
+                "files": [{"id": "a", "file": "x.png"}],
+            },
+            False,
+            id="platform_tagged_defaults_files_dict",
+        ),
+        # `files:` without `platform:` is not legacy either -- the flattener has no branch for it.
+        pytest.param(
+            {
+                "defaults": {"type": "rgb565"},
+                "files": [{"id": "a", "file": "x.png"}],
+            },
+            False,
+            id="defaults_files_dict_without_platform",
+        ),
+        # Same as above in a list -- without this exclusion it would be silently
+        # migrated to a hard-coded `platform: file` instead of raising the error.
+        pytest.param(
+            [
+                {
+                    "defaults": {"type": "rgb565"},
+                    "files": [{"id": "a", "file": "x.png"}],
+                }
+            ],
+            False,
+            id="defaults_files_list_entry_without_platform",
+        ),
     ],
 )
 def test_is_legacy_image_format(config: object, expected: bool) -> None:
@@ -359,39 +408,313 @@ def test_is_legacy_image_format(config: object, expected: bool) -> None:
 def test_migrate_returns_none_for_invalid_legacy_shapes(
     config: object, caplog: pytest.LogCaptureFixture
 ) -> None:
-    """Unrecognised shapes are not migrated (and emit no warning) so normal
-    platform validation surfaces a proper error instead of silently dropping
-    the offending input."""
+    """Unrecognised shapes are not migrated (and emit no warning), so normal platform validation reports them."""
     with caplog.at_level(logging.WARNING):
         assert _migrate_legacy_image_config(config) is None
     assert "deprecated" not in caplog.text
 
 
+def test_migrate_returns_none_for_mapping_form_defaults_files() -> None:
+    """A `platform:`-tagged `defaults:`/`files:` mapping must not be swallowed by the legacy migrator."""
+    config = {
+        CONF_PLATFORM: "file",
+        "defaults": {"type": "rgb565"},
+        "files": [{"id": "a", "file": "a.png"}],
+    }
+    assert _migrate_legacy_image_config(config) is None
+
+
+def test_migrate_returns_none_for_defaults_files_dict_without_platform() -> None:
+    """`defaults:`/`files:` without `platform:` must not be swallowed either -- the flattener has
+    no `files:` branch and would silently return `[]`."""
+    config = {
+        "defaults": {"type": "rgb565"},
+        "files": [{"id": "a", "file": "a.png"}],
+    }
+    assert _migrate_legacy_image_config(config) is None
+
+
+def test_migrate_returns_none_for_defaults_files_list_entry_without_platform() -> None:
+    """Same, in a list -- previously the list branch migrated it to a hard-coded
+    `platform: file` instead of raising a missing-platform error."""
+    config = [
+        {
+            "defaults": {"type": "rgb565"},
+            "files": [{"id": "a", "file": "a.png"}],
+        }
+    ]
+    assert _migrate_legacy_image_config(config) is None
+
+
 # --------------------------- end legacy migration --------------------------
 
 
+def test_expand_platform_entry_passes_through_plain_entry() -> None:
+    entry = {CONF_PLATFORM: "file", "id": "a", "file": "x.png"}
+    assert _expand_platform_entry(0, entry) == [entry]
+
+
+def test_expand_platform_entry_expands_files_with_defaults() -> None:
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_DEFAULTS: {"type": "RGB565", "transparency": "opaque"},
+        CONF_FILES: [
+            {"id": "img1", "file": "foo.png"},
+            {"id": "img2", "file": "bar.png", "type": "GRAYSCALE"},
+        ],
+    }
+    assert _expand_platform_entry(0, entry) == [
+        {
+            CONF_PLATFORM: "file",
+            "id": "img1",
+            "file": "foo.png",
+            "type": "RGB565",
+            "transparency": "opaque",
+        },
+        {
+            CONF_PLATFORM: "file",
+            "id": "img2",
+            "file": "bar.png",
+            "type": "GRAYSCALE",
+            "transparency": "opaque",
+        },
+    ]
+
+
+def test_expand_platform_entry_files_without_defaults() -> None:
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_FILES: [{"id": "img1", "file": "foo.png"}],
+    }
+    assert _expand_platform_entry(0, entry) == [
+        {CONF_PLATFORM: "file", "id": "img1", "file": "foo.png"}
+    ]
+
+
+def test_expand_platform_entry_preserves_source_range() -> None:
+    """A merged entry keeps the source range of its `files:` item so whole-entry errors anchor there."""
+    from esphome import yaml_util
+
+    file_entry = yaml_util.make_data_base({"id": "img1", "file": "foo.png"})
+    file_entry._esp_range = "sentinel-range"
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_DEFAULTS: {"type": "RGB565"},
+        CONF_FILES: [file_entry],
+    }
+    [out] = _expand_platform_entry(0, entry)
+    assert isinstance(out, yaml_util.ESPHomeDataBase)
+    assert out.esp_range == "sentinel-range"
+
+
+def test_expand_platform_entry_plain_dict_file_entry_has_no_source_range() -> None:
+    """Plain-dict `files:` items must not crash -- `from_database` reads `.esp_range` unconditionally."""
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_FILES: [{"id": "img1", "file": "foo.png"}],
+    }
+    [out] = _expand_platform_entry(0, entry)
+    assert out == {CONF_PLATFORM: "file", "id": "img1", "file": "foo.png"}
+
+
+def test_expand_platform_entry_per_file_overrides_win() -> None:
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_DEFAULTS: {"type": "RGB565"},
+        CONF_FILES: [{"id": "img1", "file": "foo.png", "type": "BINARY"}],
+    }
+    [out] = _expand_platform_entry(0, entry)
+    assert out["type"] == "BINARY"
+
+
+def test_expand_platform_entry_drops_byte_order_for_non_endian_override() -> None:
+    """A `byte_order` default merged into a non-endian override is dropped, as the legacy flattener did."""
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_DEFAULTS: {"type": "rgb565", "byte_order": "little_endian"},
+        CONF_FILES: [
+            {"id": "a", "file": "x.png"},
+            {"id": "b", "file": "y.png", "type": "binary"},
+        ],
+    }
+    out = _expand_platform_entry(0, entry)
+    assert out[0]["byte_order"] == "little_endian"
+    assert "byte_order" not in out[1]
+
+
+def test_expand_platform_entry_invalid_byte_order_in_defaults_raises() -> None:
+    """A dropped `byte_order` inherited from `defaults:` is still validated, so a typo raises."""
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_DEFAULTS: {"type": "rgb565", "byte_order": "little_andian"},
+        CONF_FILES: [{"id": "a", "file": "x.png", "type": "binary"}],
+    }
+    with pytest.raises(cv.Invalid, match="did you mean") as excinfo:
+        _expand_platform_entry(0, entry)
+    assert excinfo.value.path == [0]
+
+
+def test_expand_platform_entry_keeps_byte_order_for_endian_override() -> None:
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_DEFAULTS: {"type": "rgb565", "byte_order": "big_endian"},
+        CONF_FILES: [{"id": "a", "file": "x.png", "type": "rgb565"}],
+    }
+    [out] = _expand_platform_entry(0, entry)
+    assert out["byte_order"] == "big_endian"
+
+
+def test_expand_platform_entry_keeps_explicit_byte_order_conflict() -> None:
+    """A `byte_order` written directly on the entry is kept so validate_settings raises the normal error."""
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_DEFAULTS: {"type": "rgb565"},
+        CONF_FILES: [
+            {
+                "id": "a",
+                "file": "x.png",
+                "type": "binary",
+                "byte_order": "little_endian",
+            }
+        ],
+    }
+    [out] = _expand_platform_entry(0, entry)
+    assert out["byte_order"] == "little_endian"
+
+
+def test_expand_platform_entry_defaults_without_files_raises() -> None:
+    entry = {CONF_PLATFORM: "file", CONF_DEFAULTS: {"type": "RGB565"}}
+    with pytest.raises(cv.Invalid, match="may only be used together with") as excinfo:
+        _expand_platform_entry(0, entry)
+    assert excinfo.value.path == [0]
+
+
+def test_expand_platform_entry_null_files_raises_not_empty() -> None:
+    """A `files:` key with no value parses to `None` and must be reported clearly."""
+    entry = {CONF_PLATFORM: "file", CONF_DEFAULTS: {"type": "RGB565"}, CONF_FILES: None}
+    with pytest.raises(cv.Invalid, match="must not be empty"):
+        _expand_platform_entry(0, entry)
+
+
+def test_expand_platform_entry_empty_files_list_raises_not_empty() -> None:
+    """An explicit `files: []` must not silently drop the whole platform entry."""
+    entry = {CONF_PLATFORM: "file", CONF_FILES: []}
+    with pytest.raises(cv.Invalid, match="must not be empty"):
+        _expand_platform_entry(0, entry)
+
+
+def test_expand_platform_entry_files_with_stray_key_raises() -> None:
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_FILES: [{"id": "a", "file": "x.png"}],
+        "extra": 1,
+    }
+    with pytest.raises(cv.Invalid, match="cannot be combined with"):
+        _expand_platform_entry(0, entry)
+
+
+def test_expand_platform_entry_id_in_defaults_raises() -> None:
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_DEFAULTS: {CONF_ID: "a"},
+        CONF_FILES: [{"file": "x.png"}],
+    }
+    with pytest.raises(cv.Invalid, match="not allowed inside"):
+        _expand_platform_entry(0, entry)
+
+
+def test_expand_platform_entry_platform_in_defaults_raises() -> None:
+    """`platform:` inside `defaults:` would silently reassign every file's platform."""
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_DEFAULTS: {CONF_PLATFORM: "animation"},
+        CONF_FILES: [{"id": "a", "file": "x.png"}],
+    }
+    with pytest.raises(cv.Invalid, match="not allowed inside"):
+        _expand_platform_entry(0, entry)
+
+
+def test_expand_platform_entry_platform_in_file_entry_raises() -> None:
+    """`platform:` on a `files:` item must not silently override the entry's platform."""
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_FILES: [{"id": "a", "file": "x.png", CONF_PLATFORM: "animation"}],
+    }
+    with pytest.raises(cv.Invalid, match="not allowed inside"):
+        _expand_platform_entry(0, entry)
+
+
+def test_expand_platform_entry_files_not_list_raises() -> None:
+    entry = {CONF_PLATFORM: "file", CONF_FILES: "not-a-list"}
+    with pytest.raises(cv.Invalid, match="must be a list"):
+        _expand_platform_entry(0, entry)
+
+
+def test_expand_platform_entry_defaults_not_mapping_raises() -> None:
+    entry = {
+        CONF_PLATFORM: "file",
+        CONF_DEFAULTS: "not-a-mapping",
+        CONF_FILES: [{"id": "a", "file": "x.png"}],
+    }
+    with pytest.raises(cv.Invalid, match="must be a mapping"):
+        _expand_platform_entry(0, entry)
+
+
+def test_expand_platform_entry_file_item_not_mapping_raises() -> None:
+    entry = {CONF_PLATFORM: "file", CONF_FILES: [1, 2]}
+    with pytest.raises(cv.Invalid, match="must be a mapping"):
+        _expand_platform_entry(0, entry)
+
+
+def test_expand_platform_config_mixes_plain_and_expanded_entries() -> None:
+    config = [
+        {
+            CONF_PLATFORM: "file",
+            CONF_DEFAULTS: {"type": "RGB565"},
+            CONF_FILES: [
+                {"id": "img1", "file": "foo.png"},
+                {"id": "img2", "file": "bar.png"},
+            ],
+        },
+        {CONF_PLATFORM: "file", "id": "plain", "file": "baz.png", "type": "BINARY"},
+    ]
+    out = expand_platform_config(config)
+    assert [entry["id"] for entry in out] == ["img1", "img2", "plain"]
+
+
+def test_expand_platform_config_ignores_non_platform_entries() -> None:
+    # Not expanded here -- legacy_config_migrate runs before this hook and is
+    # responsible for tagging/flattening pre-platform shapes.
+    config = ["not-a-platform-entry"]
+    assert expand_platform_config(config) == config
+
+
+# --------------------- end defaults/files expansion -------------------------
+
+
 def test_validate_image_final_defaults_to_little_endian() -> None:
-    out = validate_image_final({CONF_FILE: "x.png"})
-    assert out[CONF_BYTE_ORDER] == "LITTLE_ENDIAN"
+    config = {CONF_FILE: "x.png"}
+    validate_image_final(config)
+    assert config[CONF_BYTE_ORDER] == "LITTLE_ENDIAN"
 
 
 def test_validate_image_final_keeps_little_endian(
     caplog: pytest.LogCaptureFixture,
 ) -> None:
+    config = {CONF_FILE: "x.png", CONF_BYTE_ORDER: "LITTLE_ENDIAN"}
     with caplog.at_level(logging.WARNING):
-        out = validate_image_final(
-            {CONF_FILE: "x.png", CONF_BYTE_ORDER: "LITTLE_ENDIAN"}
-        )
-    assert out[CONF_BYTE_ORDER] == "LITTLE_ENDIAN"
+        validate_image_final(config)
+    assert config[CONF_BYTE_ORDER] == "LITTLE_ENDIAN"
     assert "big-endian" not in caplog.text
 
 
 def test_validate_image_final_warns_on_big_endian(
     caplog: pytest.LogCaptureFixture,
 ) -> None:
+    config = {CONF_FILE: "x.png", CONF_BYTE_ORDER: "BIG_ENDIAN"}
     with caplog.at_level(logging.WARNING):
-        out = validate_image_final({CONF_FILE: "x.png", CONF_BYTE_ORDER: "BIG_ENDIAN"})
-    assert out[CONF_BYTE_ORDER] == "BIG_ENDIAN"
+        validate_image_final(config)
+    assert config[CONF_BYTE_ORDER] == "BIG_ENDIAN"
     assert "big-endian" in caplog.text
 
 

tests/component_tests/provisioning/test_provisioning.py

@@ -37,7 +37,7 @@ def test_provisioning_accepts_a_registered_source(
     set_core_config(PlatformFramework.ESP32_IDF)
     register_source("network")
     # Should not raise.
-    assert FINAL_VALIDATE_SCHEMA({}) == {}
+    FINAL_VALIDATE_SCHEMA({})
 
 
 def test_provisioning_warns_on_hardcoded_credentials(
@@ -49,7 +49,7 @@ def test_provisioning_warns_on_hardcoded_credentials(
     register_source("network")
     report_hardcoded_credentials("wifi")
     with caplog.at_level(logging.WARNING):
-        assert FINAL_VALIDATE_SCHEMA({}) == {}
+        FINAL_VALIDATE_SCHEMA({})
     assert "wifi" in caplog.text
     assert "credentials" in caplog.text
 
@@ -62,7 +62,7 @@ def test_provisioning_no_warning_without_hardcoded_credentials(
     set_core_config(PlatformFramework.ESP32_IDF)
     register_source("network")
     with caplog.at_level(logging.WARNING):
-        assert FINAL_VALIDATE_SCHEMA({}) == {}
+        FINAL_VALIDATE_SCHEMA({})
     assert "credentials" not in caplog.text
 
 

tests/components/addressable_light/common-ard-esp32_rmt_led_strip.yaml

@@ -3,7 +3,7 @@ light:
     id: led_matrix_32x8
     default_transition_length: 500ms
     chipset: ws2812
-    rgb_order: GRB
+    channel_colors: GRB
     num_leds: 256
     pin: ${pin}
 

tests/components/addressable_light/common-idf-esp32_rmt_led_strip.yaml

@@ -3,7 +3,7 @@ light:
     id: led_matrix_32x8
     default_transition_length: 500ms
     chipset: ws2812
-    rgb_order: GRB
+    channel_colors: GRB
     num_leds: 256
     pin: ${pin}
 

tests/components/animation/validate-platform-defaults.host.yaml

@@ -0,0 +1,21 @@
+# `platform: animation` entry exercising the shared `defaults:`/`files:` expansion.
+display:
+  - platform: sdl
+    id: animation_display
+    auto_clear_enabled: false
+    dimensions:
+      width: 480
+      height: 480
+
+image:
+  - platform: animation
+    defaults:
+      type: rgb565
+      transparency: opaque
+      resize: 50x50
+    files:
+      - id: platform_defaults_animation
+        file: $component_dir/anim.gif
+      - id: platform_defaults_animation_rgb
+        file: $component_dir/anim.apng
+        type: rgb

tests/components/beken_spi_led_strip/test.bk72xx-ard.yaml

@@ -1,6 +1,6 @@
 light:
   - platform: beken_spi_led_strip
-    rgb_order: GRB
+    channel_colors: GRB
     pin: P16
     num_leds: 30
     chipset: ws2812

tests/components/beken_spi_led_strip/validate-legacy.bk72xx-ard.yaml

@@ -0,0 +1,10 @@
+# The deprecated rgb_order / is_rgbw / is_wrgb keys, kept working until 2027.3.0.
+# Config-only, and only one strip because P16 is the sole supported pin.
+light:
+  - platform: beken_spi_led_strip
+    name: Legacy RGBW
+    pin: P16
+    num_leds: 30
+    chipset: sk6812
+    rgb_order: GRB
+    is_rgbw: true # -> GRBW

tests/components/core/test_helpers.cpp

@@ -1,6 +1,7 @@
 #include <gtest/gtest.h>
 #include <cstring>
 
+#include "esphome/core/alloc_helpers.h"
 #include "esphome/core/helpers.h"
 
 namespace esphome::core::testing {
@@ -213,4 +214,70 @@ TEST(BufAppendSepStr, Truncation) {
   EXPECT_EQ(end - buf, 7);
 }
 
+// --- base64 encode/decode ---
+
+static const char BASE64_ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+// Pack 6-bit indices 0..63 into 48 bytes so encoding yields the full alphabet in order
+TEST(Base64, EncodeProducesCanonicalAlphabet) {
+  uint8_t bytes[48];
+  size_t n = 0;
+  for (uint8_t i = 0; i < 64; i += 4) {
+    bytes[n++] = (i << 2) | ((i + 1) >> 4);
+    bytes[n++] = ((i + 1) & 0x0F) << 4 | ((i + 2) >> 2);
+    bytes[n++] = ((i + 2) & 0x03) << 6 | (i + 3);
+  }
+  std::string encoded = base64_encode(bytes, sizeof(bytes));  // NOLINT(esphome-heap-allocation) - host test
+  EXPECT_EQ(encoded, BASE64_ALPHABET);
+}
+
+// Decode the alphabet then re-encode: locks the encode and decode mappings together
+TEST(Base64, DecodeCanonicalAlphabetRoundTrip) {
+  uint8_t buf[48];
+  size_t len = base64_decode(std::string(BASE64_ALPHABET), buf, sizeof(buf));
+  EXPECT_EQ(len, 48u);
+  std::string reencoded = base64_encode(buf, len);  // NOLINT(esphome-heap-allocation) - host test
+  EXPECT_EQ(reencoded, BASE64_ALPHABET);
+}
+
+TEST(Base64, DecodeBase64UrlMatchesStandard) {
+  std::string url = BASE64_ALPHABET;
+  for (char &c : url) {
+    if (c == '+')
+      c = '-';
+    if (c == '/')
+      c = '_';
+  }
+  uint8_t standard[48], urlsafe[48];
+  size_t len_standard = base64_decode(std::string(BASE64_ALPHABET), standard, sizeof(standard));
+  size_t len_url = base64_decode(url, urlsafe, sizeof(urlsafe));
+  EXPECT_EQ(len_standard, len_url);
+  EXPECT_EQ(memcmp(standard, urlsafe, len_standard), 0);
+}
+
+// RFC 4648 vectors cover both padding cases (len % 3 == 1 and len % 3 == 2)
+TEST(Base64, Rfc4648Vectors) {
+  const struct {
+    const char *plain;
+    const char *encoded;
+  } vectors[] = {
+      {"", ""},
+      {"f", "Zg=="},
+      {"fo", "Zm8="},
+      {"foo", "Zm9v"},
+      {"foob", "Zm9vYg=="},
+      {"fooba", "Zm9vYmE="},
+      {"foobar", "Zm9vYmFy"},
+  };
+  for (const auto &v : vectors) {
+    const auto *plain = reinterpret_cast<const uint8_t *>(v.plain);
+    std::string encoded = base64_encode(plain, strlen(v.plain));  // NOLINT(esphome-heap-allocation) - host test
+    EXPECT_EQ(encoded, v.encoded);
+    uint8_t buf[8];
+    size_t len = base64_decode(reinterpret_cast<const uint8_t *>(v.encoded), strlen(v.encoded), buf, sizeof(buf));
+    EXPECT_EQ(len, strlen(v.plain));
+    EXPECT_EQ(memcmp(buf, v.plain, len), 0);
+  }
+}
+
 }  // namespace esphome::core::testing

tests/components/e131/common-ard.yaml

@@ -5,7 +5,7 @@ light:
     id: led_matrix_32x8
     default_transition_length: 500ms
     chipset: ws2812
-    rgb_order: GRB
+    channel_colors: GRB
     num_leds: 256
     pin: ${pin}
     effects:

tests/components/e131/common-idf.yaml

@@ -5,7 +5,7 @@ light:
     id: led_matrix_32x8
     default_transition_length: 500ms
     chipset: ws2812
-    rgb_order: GRB
+    channel_colors: GRB
     num_leds: 256
     pin: ${pin}
     effects:

tests/components/e131/test.rp2040-ard.yaml

@@ -6,7 +6,7 @@ light:
     pin: 2
     pio: 0
     num_leds: 256
-    rgb_order: GRB
+    channel_colors: GRB
     chipset: WS2812
     effects:
       - e131:

tests/components/esp32_rmt_led_strip/common.yaml

@@ -3,13 +3,13 @@ light:
     id: led_strip1
     pin: ${pin1}
     num_leds: 60
-    rgb_order: GRB
+    channel_colors: GRB
     chipset: ws2812
   - platform: esp32_rmt_led_strip
     id: led_strip2
     pin: ${pin2}
     num_leds: 60
-    rgbw_order: RWGB
+    channel_colors: RWGB
     bit0_high: 100us
     bit0_low: 100us
     bit1_high: 100us

tests/components/esp32_rmt_led_strip/test.esp32-s3-idf.yaml

@@ -8,14 +8,14 @@ light:
     id: led_strip1
     pin: ${pin1}
     num_leds: 60
-    rgb_order: GRB
+    channel_colors: GRB
     chipset: ws2812
     use_dma: "true"
   - platform: esp32_rmt_led_strip
     id: led_strip2
     pin: ${pin2}
     num_leds: 60
-    rgb_order: RGB
+    channel_colors: RGB
     bit0_high: 100us
     bit0_low: 100us
     bit1_high: 100us

tests/components/esp32_rmt_led_strip/validate-legacy.esp32-idf.yaml

@@ -0,0 +1,23 @@
+# The deprecated rgb_order / is_rgbw / is_wrgb keys, kept working until 2027.3.0.
+# Config-only: each strip below must migrate to the channel_colors shown in the comment.
+light:
+  - platform: esp32_rmt_led_strip
+    id: legacy_rgb
+    pin: GPIO13
+    num_leds: 60
+    chipset: ws2812
+    rgb_order: GRB # -> GRB
+  - platform: esp32_rmt_led_strip
+    id: legacy_rgbw
+    pin: GPIO14
+    num_leds: 60
+    chipset: sk6812
+    rgb_order: GRB
+    is_rgbw: true # -> GRBW
+  - platform: esp32_rmt_led_strip
+    id: legacy_wrgb
+    pin: GPIO15
+    num_leds: 60
+    chipset: sk6812
+    rgb_order: GRB
+    is_wrgb: true # -> WGRB

tests/components/image/validate-platform-defaults.host.yaml

@@ -0,0 +1,24 @@
+# `platform: file` entry using the `defaults:`/`files:` shape, including the
+# per-type byte_order drop when an entry overrides to a non-endian type.
+display:
+  - platform: sdl
+    id: image_display
+    auto_clear_enabled: false
+    dimensions:
+      width: 480
+      height: 480
+
+image:
+  - platform: file
+    defaults:
+      type: rgb565
+      transparency: opaque
+      byte_order: little_endian
+      resize: 50x50
+      dither: FloydSteinberg
+    files:
+      - id: platform_defaults_image
+        file: ../../pnglogo.png
+      - id: platform_defaults_binary
+        file: ../../pnglogo.png
+        type: binary

tests/components/modbus/common.h

@@ -1,7 +1,10 @@
 #pragma once
 #include <cstdint>
+#include <cstring>
+#include <span>
 #include <vector>
 #include "esphome/components/uart/uart_component.h"
+#include "esphome/core/helpers.h"
 
 namespace esphome::modbus::testing {
 
@@ -30,4 +33,37 @@ class RecordingUART : public NullUART {
   std::vector<uint8_t> written;
 };
 
+// A UART the test can inject received bytes into, so frames travel the full receive path
+// (receive_modbus_frames -> parse -> dispatch) through hub.loop(). Writes are recorded.
+class InjectableUART : public RecordingUART {
+ public:
+  bool peek_byte(uint8_t *data) override {
+    if (this->rx_.empty())
+      return false;
+    *data = this->rx_.front();
+    return true;
+  }
+  bool read_array(uint8_t *data, size_t len) override {
+    if (len > this->rx_.size())
+      return false;
+    memcpy(data, this->rx_.data(), len);
+    this->rx_.erase(this->rx_.begin(), this->rx_.begin() + len);
+    return true;
+  }
+  size_t available() override { return this->rx_.size(); }
+
+  // Queues a complete wire frame: address + PDU + CRC16 (low byte first).
+  void inject_frame(uint8_t address, std::span<const uint8_t> pdu) {
+    size_t start = this->rx_.size();
+    this->rx_.push_back(address);
+    this->rx_.insert(this->rx_.end(), pdu.begin(), pdu.end());
+    uint16_t crc = crc16(this->rx_.data() + start, this->rx_.size() - start);
+    this->rx_.push_back(crc & 0xFF);
+    this->rx_.push_back(crc >> 8);
+  }
+
+ private:
+  std::vector<uint8_t> rx_;
+};
+
 }  // namespace esphome::modbus::testing

tests/components/modbus/modbus_unknown_function_test.cpp

@@ -0,0 +1,141 @@
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <span>
+#include <vector>
+
+#include "common.h"
+#include "esphome/components/modbus/modbus.h"
+
+namespace esphome::modbus::testing {
+
+namespace {
+
+// Records custom-response dispatches so tests can assert an unknown-length frame reached the device.
+class CustomRecordingDevice : public ModbusClientDevice {
+ public:
+  using ModbusClientDevice::ModbusClientDevice;
+  void on_custom_response(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu,
+                          ResponseStatus status) override {
+    this->requests.emplace_back(request_pdu.begin(), request_pdu.end());
+    this->responses.emplace_back(response_pdu.begin(), response_pdu.end());
+    this->statuses.push_back(status);
+  }
+  std::vector<std::vector<uint8_t>> requests;
+  std::vector<std::vector<uint8_t>> responses;
+  std::vector<ResponseStatus> statuses;
+};
+
+// Every handler keeps its ILLEGAL_FUNCTION default; the hub's dispatch is what is under test.
+class SilentServerDevice : public ModbusServerDevice {};
+
+// Drives full client frames through the server hub's receive path (same shape as the broadcast tests).
+class TestServerHub : public ModbusServerHub {
+ public:
+  bool tx_blocked() override { return false; }
+
+  // Builds a complete client frame (address + FC + data + CRC) and runs the full receive-side parser.
+  // Returns true once the buffer has fully drained.
+  bool run_receive_parser_for_test(uint8_t address, uint8_t function_code, std::span<const uint8_t> data) {
+    this->rx_buffer_.clear();
+    this->rx_buffer_.reserve(data.size() + 4);
+    this->rx_buffer_.push_back(address);
+    this->rx_buffer_.push_back(function_code);
+    this->rx_buffer_.insert(this->rx_buffer_.end(), data.begin(), data.end());
+    uint16_t crc = crc16(this->rx_buffer_.data(), this->rx_buffer_.size());
+    this->rx_buffer_.push_back(crc & 0xFF);
+    this->rx_buffer_.push_back(crc >> 8);
+    this->parse_modbus_frames();
+    return this->rx_buffer_.empty();
+  }
+};
+
+}  // namespace
+
+// The frame-length parsers have explicit cases for exactly these 13 codes; every other value - the
+// assigned-but-unimplemented management codes, both user-defined ranges, and all unassigned codes -
+// must classify as unknown length. The exception flag masks off first.
+TEST(ModbusUnknownFunction, HelperMatchesParserCoverage) {
+  for (uint8_t fc : {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x0F, 0x10, 0x14, 0x15, 0x16, 0x17, 0x18}) {
+    EXPECT_FALSE(helpers::is_function_code_unknown_length(fc)) << "fc 0x" << std::hex << int(fc);
+  }
+  for (uint8_t fc : {0x07, 0x08, 0x0B, 0x0C, 0x11, 0x2A, 0x41, 0x48, 0x49, 0x64, 0x6E, 0x00, 0x7F}) {
+    EXPECT_TRUE(helpers::is_function_code_unknown_length(fc)) << "fc 0x" << std::hex << int(fc);
+  }
+  // Exception replies classify by their base code.
+  EXPECT_FALSE(helpers::is_function_code_unknown_length(0x83));
+  EXPECT_TRUE(helpers::is_function_code_unknown_length(0x87));
+  // Strictly wider than the user-defined ranges: every custom code is unknown-length, but not vice versa.
+  for (int fc = 0; fc <= 0xFF; fc++) {
+    if (helpers::is_function_code_custom(fc))
+      EXPECT_TRUE(helpers::is_function_code_unknown_length(fc)) << "fc 0x" << std::hex << fc;
+  }
+  EXPECT_FALSE(helpers::is_function_code_custom(0x49));
+
+  // Derived contract check: the helper must say "unknown" exactly when both length parsers fall
+  // through to default. With a zero-filled max-size PDU every explicit case returns at least 2
+  // (file records bottom out at 2, FIFO at 3) and only default returns MIN_PDU_SIZE, so comparing
+  // against MIN_PDU_SIZE detects a case added to either switch without updating the helper. The
+  // loop stops at 0x7F: above it the helper masks the exception flag off while client_pdu_length()
+  // switches on the unmasked byte and server_pdu_length() early-returns the exception length.
+  for (int fc = 0; fc <= 0x7F; fc++) {
+    const uint8_t pdu[MAX_PDU_SIZE] = {static_cast<uint8_t>(fc)};  // zero header fields
+    EXPECT_EQ(helpers::is_function_code_unknown_length(fc),
+              helpers::client_pdu_length(pdu, sizeof(pdu)) == MIN_PDU_SIZE)
+        << "client_pdu_length disagrees for fc 0x" << std::hex << fc;
+    EXPECT_EQ(helpers::is_function_code_unknown_length(fc),
+              helpers::server_pdu_length(pdu, sizeof(pdu)) == MIN_PDU_SIZE)
+        << "server_pdu_length disagrees for fc 0x" << std::hex << fc;
+  }
+}
+
+// A response with a function code outside the user-defined ranges (0x49) has no length case in
+// server_pdu_length(), so the parser must find the frame end by CRC scan - the same way it already
+// handles user-defined codes. Frame: address + FC 0x49 + 3 data bytes + CRC = 7 bytes. Without the
+// scan the parser assumes a 4-byte frame, fails the CRC, and the response never reaches the device.
+TEST(ModbusUnknownFunction, ClientParsesUnknownLengthResponse) {
+  InjectableUART uart;
+  ModbusClientHub hub;
+  hub.set_uart_parent(&uart);
+  hub.setup();  // computes frame timing from the baud rate
+  CustomRecordingDevice device(&hub, 0x02);
+
+  const uint8_t request[] = {0x49, 0x01};
+  ASSERT_TRUE(device.queue_pdu(request));
+  hub.loop();  // transmit
+  ASSERT_FALSE(uart.written.empty());
+
+  const uint8_t response_pdu[] = {0x49, 0x02, 0xAA, 0xBB};
+  uart.inject_frame(0x02, response_pdu);
+  hub.loop();  // receive + parse + match + dispatch
+
+  ASSERT_EQ(device.responses.size(), 1u);
+  EXPECT_EQ(device.requests[0], std::vector<uint8_t>(request, request + sizeof(request)));
+  EXPECT_EQ(device.responses[0], std::vector<uint8_t>(response_pdu, response_pdu + sizeof(response_pdu)));
+  EXPECT_FALSE(device.statuses[0].has_value());
+}
+
+// The server side of the same gap: a request with FC 0x49 for a registered device must parse (CRC
+// scan again) so the hub can answer ILLEGAL_FUNCTION per the spec. Without the scan the frame fails
+// to parse and the client gets silence instead of the exception.
+TEST(ModbusUnknownFunction, ServerRepliesIllegalFunctionToUnknownLengthRequest) {
+  TestServerHub hub;
+  RecordingUART uart;
+  hub.set_uart_parent(&uart);
+
+  SilentServerDevice device;
+  device.set_address(0x02);
+  hub.register_device(&device);
+
+  const uint8_t data[] = {0x02, 0xAA, 0xBB};
+  ASSERT_TRUE(hub.run_receive_parser_for_test(0x02, 0x49, data));
+
+  // Expected reply: address + FC with exception flag + ILLEGAL_FUNCTION + CRC.
+  std::vector<uint8_t> expected = {0x02, 0xC9, 0x01};
+  uint16_t crc = crc16(expected.data(), expected.size());
+  expected.push_back(crc & 0xFF);
+  expected.push_back(crc >> 8);
+  EXPECT_EQ(uart.written, expected);
+}
+
+}  // namespace esphome::modbus::testing

tests/components/partition/common-ard.yaml

@@ -4,7 +4,7 @@ light:
     default_transition_length: 500ms
     chipset: ws2812
     num_leds: 256
-    rgb_order: GRB
+    channel_colors: GRB
     pin: ${pin}
   - platform: partition
     name: Partition Light

tests/components/partition/common-idf.yaml

@@ -4,7 +4,7 @@ light:
     default_transition_length: 500ms
     chipset: ws2812
     num_leds: 256
-    rgb_order: GRB
+    channel_colors: GRB
     pin: ${pin}
   - platform: partition
     name: Partition Light

tests/components/rp2040_pio_led_strip/common.yaml

@@ -4,14 +4,14 @@ light:
     pin: 4
     num_leds: 60
     pio: 0
-    rgb_order: GRB
+    channel_colors: GRB
     chipset: WS2812
   - platform: rp2040_pio_led_strip
     id: led_strip_custom_timings
     pin: 5
     num_leds: 60
     pio: 1
-    rgb_order: GRB
+    channel_colors: GRB
     bit0_high: .1us
     bit0_low: 1.2us
     bit1_high: .69us

tests/components/rp2040_pio_led_strip/validate-legacy.rp2040-ard.yaml

@@ -0,0 +1,18 @@
+# The deprecated rgb_order / is_rgbw keys, kept working until 2027.3.0.
+# Config-only: each strip below must migrate to the channel_colors shown in the comment.
+light:
+  - platform: rp2040_pio_led_strip
+    id: legacy_rgb
+    pin: 4
+    num_leds: 60
+    pio: 0
+    chipset: WS2812
+    rgb_order: GRB # -> GRB
+  - platform: rp2040_pio_led_strip
+    id: legacy_rgbw
+    pin: 5
+    num_leds: 60
+    pio: 1
+    chipset: SK6812
+    rgb_order: GRB
+    is_rgbw: true # -> GRBW

tests/components/wled/test.esp32-ard.yaml

@@ -9,7 +9,7 @@ light:
     id: led_matrix_32x8
     default_transition_length: 500ms
     chipset: ws2812
-    rgb_order: GRB
+    channel_colors: GRB
     num_leds: 256
     pin: 2
     effects:

tests/integration/conftest.py

@@ -60,7 +60,11 @@ def _get_platformio_env(cache_dir: Path) -> dict[str, str]:
     env = os.environ.copy()
     env["PLATFORMIO_CORE_DIR"] = str(cache_dir)
     env["PLATFORMIO_CACHE_DIR"] = str(cache_dir / ".cache")
-    env["PLATFORMIO_LIBDEPS_DIR"] = str(cache_dir / "libdeps")
+    # libdeps is keyed only by env name (the device name), and fixtures share
+    # names; two xdist workers first-compiling the same name race pio pkg
+    # install in the same directory. Keep libdeps per worker.
+    worker = os.environ.get("PYTEST_XDIST_WORKER", "master")
+    env["PLATFORMIO_LIBDEPS_DIR"] = str(cache_dir / "libdeps" / worker)
     # Prevent cache cleaning during integration tests
     env["ESPHOME_SKIP_CLEAN_BUILD"] = "1"
     # Compile with THIS tree's esphome sources, not wherever the venv's editable

tests/integration/entity_utils.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from esphome.helpers import fnv1_hash_name, sanitize, snake_case
+from esphome.helpers import fnv1_hash_object_id, sanitize, snake_case
 
 if TYPE_CHECKING:
     from aioesphomeapi import DeviceInfo, EntityInfo
@@ -25,16 +25,15 @@ def infer_name_add_mac_suffix(device_info: DeviceInfo) -> bool:
     return device_info.name.endswith(f"-{mac_suffix}")
 
 
-def _resolve_entity_name(
+def _get_name_for_object_id(
     entity: EntityInfo,
     device_info: DeviceInfo,
     device_id_to_name: dict[int, str],
 ) -> str:
-    """Resolve the effective name for an entity.
+    """Get the name used for object_id computation.
 
     This is the algorithm that aioesphomeapi will use to determine which
-    name to use for computing object_id client-side from API data; the same
-    name is what the device hashes into the entity key.
+    name to use for computing object_id client-side from API data.
 
     Args:
         entity: The entity to get name for
@@ -73,27 +72,27 @@ def compute_entity_object_id(
     Returns:
         The computed object_id string
     """
-    name = _resolve_entity_name(entity, device_info, device_id_to_name)
-    return compute_object_id(name)
+    name_for_id = _get_name_for_object_id(entity, device_info, device_id_to_name)
+    return compute_object_id(name_for_id)
 
 
-def compute_entity_key(
+def compute_entity_hash(
     entity: EntityInfo,
     device_info: DeviceInfo,
     device_id_to_name: dict[int, str],
 ) -> int:
-    """Compute expected entity key for an entity.
+    """Compute expected object_id hash for an entity.
 
     Args:
-        entity: The entity to compute the key for
+        entity: The entity to compute hash for
         device_info: Device info from the API
         device_id_to_name: Mapping of device_id to device name for sub-devices
 
     Returns:
-        The computed FNV-1 hash of the raw name
+        The computed FNV-1 hash
     """
-    name = _resolve_entity_name(entity, device_info, device_id_to_name)
-    return fnv1_hash_name(name)
+    name_for_id = _get_name_for_object_id(entity, device_info, device_id_to_name)
+    return fnv1_hash_object_id(name_for_id)
 
 
 def verify_entity_object_id(
@@ -119,7 +118,7 @@ def verify_entity_object_id(
         f"expected '{expected_object_id}', got '{entity.object_id}'"
     )
 
-    expected_hash = compute_entity_key(entity, device_info, device_id_to_name)
+    expected_hash = compute_entity_hash(entity, device_info, device_id_to_name)
     assert entity.key == expected_hash, (
         f"hash mismatch for entity '{entity.name}': "
         f"expected {expected_hash:#x}, got {entity.key:#x}"

tests/integration/fixtures/camera_mock.yaml

@@ -0,0 +1,19 @@
+esphome:
+  name: camera-mock-test
+
+host:
+api:
+logger:
+  level: VERBOSE
+
+external_components:
+  - source:
+      type: local
+      path: EXTERNAL_COMPONENT_PATH
+
+mock_camera:
+  name: Mock Camera
+  # Larger than MAX_BATCH_PACKET_SIZE (1390) so the image is split across
+  # multiple CameraImageResponse chunks and the client must reassemble.
+  # Must match IMAGE_SIZE in test_camera_mock.py.
+  image_size: 4096

tests/integration/fixtures/external_components/mock_camera/__init__.py

@@ -0,0 +1,28 @@
+import esphome.codegen as cg
+import esphome.config_validation as cv
+from esphome.const import CONF_ID
+from esphome.core.entity_helpers import setup_entity
+from esphome.types import ConfigType
+
+CODEOWNERS = ["@esphome/tests"]
+AUTO_LOAD = ["camera"]
+
+CONF_IMAGE_SIZE = "image_size"
+
+mock_camera_ns = cg.esphome_ns.namespace("mock_camera")
+MockCamera = mock_camera_ns.class_("MockCamera", cg.Component, cg.EntityBase)
+
+CONFIG_SCHEMA = cv.ENTITY_BASE_SCHEMA.extend(
+    {
+        cv.GenerateID(): cv.declare_id(MockCamera),
+        cv.Optional(CONF_IMAGE_SIZE, default=1024): cv.positive_not_null_int,
+    }
+).extend(cv.COMPONENT_SCHEMA)
+
+
+async def to_code(config: ConfigType) -> None:
+    cg.add_define("USE_CAMERA")
+    var = cg.new_Pvariable(config[CONF_ID])
+    await setup_entity(var, config, "camera")
+    await cg.register_component(var, config)
+    cg.add(var.set_image_size(config[CONF_IMAGE_SIZE]))

tests/integration/fixtures/external_components/mock_camera/mock_camera.cpp

@@ -0,0 +1,30 @@
+#include "mock_camera.h"
+#include "esphome/core/application.h"
+#include "esphome/core/log.h"
+
+namespace esphome::mock_camera {
+
+static const char *const TAG = "mock_camera";
+
+void MockCamera::loop() {
+  uint8_t requesters = this->single_requesters_ | this->stream_requesters_;
+  if (requesters == 0)
+    return;
+  uint32_t now = App.get_loop_component_start_time();
+  if (now - this->last_frame_ms_ < FRAME_INTERVAL_MS)
+    return;
+  this->last_frame_ms_ = now;
+  this->single_requesters_ = 0;
+
+  auto image = std::make_shared<MockCameraImage>(this->image_size_, this->frame_counter_, requesters);
+  ESP_LOGV(TAG, "Producing frame %u (%u bytes, requesters 0x%02X)", this->frame_counter_, this->image_size_,
+           requesters);
+  this->frame_counter_++;
+  for (auto *listener : this->listeners_) {
+    listener->on_camera_image(image);
+  }
+}
+
+void MockCamera::dump_config() { ESP_LOGCONFIG(TAG, "Mock Camera (%u byte frames)", this->image_size_); }
+
+}  // namespace esphome::mock_camera

tests/integration/fixtures/external_components/mock_camera/mock_camera.h

@@ -0,0 +1,80 @@
+#pragma once
+
+#include "esphome/components/camera/camera.h"
+#include "esphome/core/component.h"
+
+#include <memory>
+#include <vector>
+
+namespace esphome::mock_camera {
+
+/** Deterministic in-memory camera image.
+ *  Byte i of frame N is (N + i) & 0xFF so tests can validate
+ *  reassembled data from just the first byte.
+ */
+class MockCameraImage : public camera::CameraImage {
+ public:
+  MockCameraImage(size_t size, uint8_t frame_counter, uint8_t requesters)
+      : data_(new uint8_t[size]), size_(size), requesters_(requesters) {
+    for (size_t i = 0; i < size; i++) {
+      this->data_[i] = static_cast<uint8_t>(frame_counter + i);
+    }
+  }
+  uint8_t *get_data_buffer() override { return this->data_.get(); }
+  size_t get_data_length() override { return this->size_; }
+  bool was_requested_by(camera::CameraRequester requester) const override {
+    return (this->requesters_ & (1 << requester)) != 0;
+  }
+
+ protected:
+  std::unique_ptr<uint8_t[]> data_;
+  size_t size_;
+  uint8_t requesters_;
+};
+
+class MockCameraImageReader : public camera::CameraImageReader {
+ public:
+  void set_image(std::shared_ptr<camera::CameraImage> image) override {
+    this->image_ = std::move(image);
+    this->offset_ = 0;
+  }
+  size_t available() const override { return this->image_ ? this->image_->get_data_length() - this->offset_ : 0; }
+  uint8_t *peek_data_buffer() override { return this->image_->get_data_buffer() + this->offset_; }
+  void consume_data(size_t consumed) override { this->offset_ += consumed; }
+  void return_image() override {
+    this->image_.reset();
+    this->offset_ = 0;
+  }
+
+ protected:
+  std::shared_ptr<camera::CameraImage> image_;
+  size_t offset_{0};
+};
+
+/** Virtual camera producing deterministic frames on request or stream. */
+class MockCamera : public camera::Camera {
+ public:
+  void loop() override;
+  void dump_config() override;
+
+  void add_listener(camera::CameraListener *listener) override { this->listeners_.push_back(listener); }
+  camera::CameraImageReader *create_image_reader() override { return new MockCameraImageReader(); }
+  void request_image(camera::CameraRequester requester) override { this->single_requesters_ |= (1 << requester); }
+  void start_stream(camera::CameraRequester requester) override { this->stream_requesters_ |= (1 << requester); }
+  void stop_stream(camera::CameraRequester requester) override { this->stream_requesters_ &= ~(1 << requester); }
+
+  void set_image_size(uint32_t size) { this->image_size_ = size; }
+
+ protected:
+  static constexpr uint32_t FRAME_INTERVAL_MS = 50;
+
+  // Members ordered largest to smallest to minimize padding
+  std::vector<camera::CameraListener *> listeners_;
+  uint32_t image_size_{1024};
+  uint32_t last_frame_ms_{0};
+  uint8_t frame_counter_{0};
+  uint8_t single_requesters_{0};
+  uint8_t stream_requesters_{0};
+};
+
+}  // namespace esphome::mock_camera

tests/integration/fixtures/fnv1_hash_object_id.yaml

@@ -71,38 +71,6 @@ esphome:
           ESP_LOGE("FNV1_OID", "empty FAILED: 0x%08x != 0x811c9dc5", hash_empty);
         }
 
-        // Raw name hash: matches Python fnv1_hash_name("My Sensor Name")
-        uint32_t hash_raw = esphome::fnv1_hash_bytes("My Sensor Name", 14);
-        if (hash_raw == 0x8cec6fb0) {
-          ESP_LOGI("FNV1_OID", "raw PASSED");
-        } else {
-          ESP_LOGE("FNV1_OID", "raw FAILED: 0x%08x != 0x8cec6fb0", hash_raw);
-        }
-
-        // Raw name hash over UTF-8 bytes: matches Python fnv1_hash_name("Température")
-        uint32_t hash_raw_utf8 = esphome::fnv1_hash_bytes("Temp\xc3\xa9rature", 12);
-        if (hash_raw_utf8 == 0x531a74aa) {
-          ESP_LOGI("FNV1_OID", "raw_utf8 PASSED");
-        } else {
-          ESP_LOGE("FNV1_OID", "raw_utf8 FAILED: 0x%08x != 0x531a74aa", hash_raw_utf8);
-        }
-
-        // Old-key UTF-8 variant: matches Python fnv1_hash_object_id("Température")
-        uint32_t hash_old_utf8 = esphome::fnv1_hash_object_id("Temp\xc3\xa9rature", 12, true);
-        if (hash_old_utf8 == 0x965698f3) {
-          ESP_LOGI("FNV1_OID", "old_utf8 PASSED");
-        } else {
-          ESP_LOGE("FNV1_OID", "old_utf8 FAILED: 0x%08x != 0x965698f3", hash_old_utf8);
-        }
-
-        // Old-key UTF-8 variant with multi-byte only name: Python fnv1_hash_object_id("温度")
-        uint32_t hash_old_cjk = esphome::fnv1_hash_object_id("\xe6\xb8\xa9\xe5\xba\xa6", 6, true);
-        if (hash_old_cjk == 0x3276cb9f) {
-          ESP_LOGI("FNV1_OID", "old_cjk PASSED");
-        } else {
-          ESP_LOGE("FNV1_OID", "old_cjk FAILED: 0x%08x != 0x3276cb9f", hash_old_cjk);
-        }
-
 host:
 api:
 logger:

tests/integration/fixtures/multi_device_preferences.yaml

@@ -156,17 +156,10 @@ button:
           ESP_LOGI("test", "Device A Mode: %s", id(mode_device_a).current_option().c_str());
           ESP_LOGI("test", "Device B Mode: %s", id(mode_device_b).current_option().c_str());
           ESP_LOGI("test", "Main Mode: %s", id(mode_main).current_option().c_str());
-          // Log preference key bases for entities that actually store preferences.
-          // This is the key base make_entity_preference() uses: entity key XOR device id.
-          ESP_LOGI("test", "Device A Switch Pref Hash: %u",
-                   id(light_device_a).get_entity_key() ^ id(light_device_a).get_device_id_or_zero());
-          ESP_LOGI("test", "Device B Switch Pref Hash: %u",
-                   id(light_device_b).get_entity_key() ^ id(light_device_b).get_device_id_or_zero());
-          ESP_LOGI("test", "Main Switch Pref Hash: %u",
-                   id(light_main).get_entity_key() ^ id(light_main).get_device_id_or_zero());
-          ESP_LOGI("test", "Device A Number Pref Hash: %u",
-                   id(setpoint_device_a).get_entity_key() ^ id(setpoint_device_a).get_device_id_or_zero());
-          ESP_LOGI("test", "Device B Number Pref Hash: %u",
-                   id(setpoint_device_b).get_entity_key() ^ id(setpoint_device_b).get_device_id_or_zero());
-          ESP_LOGI("test", "Main Number Pref Hash: %u",
-                   id(setpoint_main).get_entity_key() ^ id(setpoint_main).get_device_id_or_zero());
+          // Log preference hashes for entities that actually store preferences
+          ESP_LOGI("test", "Device A Switch Pref Hash: %u", id(light_device_a).get_preference_hash());
+          ESP_LOGI("test", "Device B Switch Pref Hash: %u", id(light_device_b).get_preference_hash());
+          ESP_LOGI("test", "Main Switch Pref Hash: %u", id(light_main).get_preference_hash());
+          ESP_LOGI("test", "Device A Number Pref Hash: %u", id(setpoint_device_a).get_preference_hash());
+          ESP_LOGI("test", "Device B Number Pref Hash: %u", id(setpoint_device_b).get_preference_hash());
+          ESP_LOGI("test", "Main Number Pref Hash: %u", id(setpoint_main).get_preference_hash());

tests/integration/fixtures/preference_key_stability.yaml

@@ -1,5 +1,5 @@
 esphome:
-  name: host-pref-key-migration
+  name: host-pref-key-stability
 
 host:
 api:

tests/integration/fixtures/sensor_filters_delta.yaml

@@ -33,6 +33,11 @@ sensor:
     id: source_sensor_5
     accuracy_decimals: 1
 
+  - platform: template
+    name: "Source Sensor 6"
+    id: source_sensor_6
+    accuracy_decimals: 1
+
   - platform: copy
     source_id: source_sensor_1
     name: "Filter Min"
@@ -81,6 +86,13 @@ sensor:
     filters:
       - delta: 50%
 
+  - platform: copy
+    source_id: source_sensor_6
+    name: "Filter NaN"
+    id: filter_nan
+    filters:
+      - delta: 0
+
 script:
   - id: test_filter_min
     then:
@@ -188,6 +200,24 @@ script:
           id: source_sensor_5
           state: 250.0  # Passes (delta=90 > 80)
 
+  - id: test_filter_nan
+    then:
+      - sensor.template.publish:
+          id: source_sensor_6
+          state: 1.0
+      - delay: 20ms
+      - sensor.template.publish:
+          id: source_sensor_6
+          state: !lambda "return NAN;"
+      - delay: 20ms
+      - sensor.template.publish:
+          id: source_sensor_6
+          state: !lambda "return NAN;"  # Filtered out
+      - delay: 20ms
+      - sensor.template.publish:
+          id: source_sensor_6
+          state: 2.0
+
 button:
   - platform: template
     name: "Test Filter Min"
@@ -218,3 +248,9 @@ button:
     id: btn_filter_percentage
     on_press:
       - script.execute: test_filter_percentage
+
+  - platform: template
+    name: "Test Filter NaN"
+    id: btn_filter_nan
+    on_press:
+      - script.execute: test_filter_nan

tests/integration/test_camera_mock.py

@@ -0,0 +1,73 @@
+"""Integration test for the camera API flow using a mock camera platform."""
+
+from __future__ import annotations
+
+import asyncio
+
+from aioesphomeapi import CameraInfo, CameraState, EntityState
+import pytest
+
+from .state_utils import require_entity
+from .types import APIClientConnectedFactory, RunCompiledFunction
+
+# Must match image_size in fixtures/camera_mock.yaml
+IMAGE_SIZE = 4096
+STREAM_FRAMES = 3
+
+
+def _verify_frame(data: bytes) -> int:
+    """Verify the deterministic frame pattern and return the frame counter."""
+    assert len(data) == IMAGE_SIZE, f"expected {IMAGE_SIZE} bytes, got {len(data)}"
+    counter = data[0]
+    assert data == bytes((counter + i) & 0xFF for i in range(IMAGE_SIZE)), (
+        "frame pattern mismatch"
+    )
+    return counter
+
+
+@pytest.mark.asyncio
+async def test_camera_mock(
+    yaml_config: str,
+    run_compiled: RunCompiledFunction,
+    api_client_connected: APIClientConnectedFactory,
+) -> None:
+    """Single-image and stream requests deliver reassembled deterministic frames."""
+    async with run_compiled(yaml_config), api_client_connected() as client:
+        entities, _ = await client.list_entities_services()
+        camera = require_entity(entities, "mock_camera", CameraInfo)
+
+        loop = asyncio.get_running_loop()
+        images: list[bytes] = []
+        single_image: asyncio.Future[None] = loop.create_future()
+        stream_done: asyncio.Future[None] = loop.create_future()
+
+        def on_state(state: EntityState) -> None:
+            if not (isinstance(state, CameraState) and state.key == camera.key):
+                return
+            images.append(bytes(state.data))
+            if not single_image.done():
+                single_image.set_result(None)
+            elif len(images) >= STREAM_FRAMES and not stream_done.done():
+                stream_done.set_result(None)
+
+        client.subscribe_states(on_state)
+
+        # Single image request: one complete frame arrives, reassembled
+        # from multiple chunks (4096 > 1390 byte packets)
+        client.request_single_image()
+        await asyncio.wait_for(single_image, timeout=10)
+        first_counter = _verify_frame(images[0])
+
+        # Stream request: multiple consecutive frames arrive
+        images.clear()
+        client.request_image_stream()
+        await asyncio.wait_for(stream_done, timeout=10)
+
+        # Frames are distinct, ordered, and fresh per the mock's counter.
+        # Not exactly consecutive: the API drops frames by design while the
+        # previous image is still being sent, so allow small gaps.
+        counters = [_verify_frame(img) for img in images[:STREAM_FRAMES]]
+        for prev, cur in zip(counters, counters[1:], strict=False):
+            assert cur != prev, f"duplicate frames: {counters}"
+            assert ((cur - prev) & 0xFF) < 16, f"frames out of order: {counters}"
+        assert counters[0] != first_counter, "stream should produce new frames"

tests/integration/test_fnv1_hash_object_id.py

@@ -37,10 +37,6 @@ async def test_fnv1_hash_object_id(
         "special",
         "complex",
         "empty",
-        "raw",
-        "raw_utf8",
-        "old_utf8",
-        "old_cjk",
     }
 
     def on_log_line(line: str) -> None:

tests/integration/test_object_id_api_verification.py

@@ -2,8 +2,8 @@
 
 This test verifies a three-way match between:
 1. C++ object_id generation (get_object_id_to using to_sanitized_char/to_snake_case_char)
-2. C++ entity key generation (fnv1_hash of the raw name in helpers.h)
-3. Python computation (sanitize/snake_case and fnv1_hash_name in helpers.py)
+2. C++ hash generation (fnv1_hash_object_id in helpers.h)
+3. Python computation (sanitize/snake_case in helpers.py, fnv1_hash_object_id)
 
 The API response contains C++ computed values, so verifying API == Python
 implicitly verifies C++ == Python == API for both object_id and hash.
@@ -25,7 +25,7 @@ from __future__ import annotations
 
 import pytest
 
-from esphome.helpers import fnv1_hash_name
+from esphome.helpers import fnv1_hash_object_id
 
 from .entity_utils import compute_object_id, verify_all_entities
 from .types import APIClientConnectedFactory, RunCompiledFunction
@@ -123,7 +123,7 @@ async def test_object_id_api_verification(
             )
 
             # Verify hash can be computed from the name
-            hash_from_name = fnv1_hash_name(entity_name)
+            hash_from_name = fnv1_hash_object_id(entity_name)
             assert hash_from_name == entity.key, (
                 f"Entity '{entity_name}': hash mismatch. "
                 f"Python hash {hash_from_name:#x}, API key {entity.key:#x}"
@@ -164,7 +164,7 @@ async def test_object_id_api_verification(
             )
 
             # Verify hash matches
-            expected_hash = fnv1_hash_name(expected_name)
+            expected_hash = fnv1_hash_object_id(expected_name)
             assert entity.key == expected_hash, (
                 f"Empty-name entity (device_id={entity.device_id}): hash mismatch. "
                 f"API key: {entity.key:#x}, expected: {expected_hash:#x}"

tests/integration/test_object_id_friendly_name_no_mac_suffix.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 
 import pytest
 
-from esphome.helpers import fnv1_hash_name
+from esphome.helpers import fnv1_hash_object_id
 
 from .entity_utils import (
     compute_object_id,
@@ -62,7 +62,7 @@ async def test_object_id_friendly_name_no_mac_suffix(
         )
 
         # Hash should match friendly_name
-        expected_hash = fnv1_hash_name("My Friendly Device")
+        expected_hash = fnv1_hash_object_id("My Friendly Device")
         assert entity.key == expected_hash, (
             f"Expected hash {expected_hash:#x}, got {entity.key:#x}"
         )

tests/integration/test_object_id_no_friendly_name.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 
 import pytest
 
-from esphome.helpers import fnv1_hash_name
+from esphome.helpers import fnv1_hash_object_id
 
 from .entity_utils import compute_object_id, verify_all_entities
 from .types import APIClientConnectedFactory, RunCompiledFunction
@@ -96,7 +96,7 @@ async def test_object_id_no_friendly_name_no_mac_suffix(
     OLD behavior:
     - is_object_id_dynamic_() returned false (mac suffix not enabled)
     - Used object_id_c_str_ which was pre-computed in Python
-    - Python used get_base_entity_name() with fallback to CORE.name
+    - Python used get_base_entity_object_id() with fallback to CORE.name
 
     Result: object_id = sanitize(snake_case(device_name))
     """
@@ -126,7 +126,7 @@ async def test_object_id_no_friendly_name_no_mac_suffix(
         )
 
         # Hash should match device name
-        expected_hash = fnv1_hash_name("test-device")
+        expected_hash = fnv1_hash_object_id("test-device")
         assert entity.key == expected_hash, (
             f"Expected hash {expected_hash:#x}, got {entity.key:#x}"
         )

tests/integration/test_preference_key_stability.py

@@ -1,14 +1,14 @@
-"""Integration test for entity preference key migration.
+"""Integration test for entity preference key stability.
 
-Entity keys are now the FNV-1 hash of the raw name instead of the sanitized
-object_id (https://github.com/esphome/backlog/issues/85). On key-lookup
-preference backends, make_entity_preference() must move data stored under the
-old key to the new key, so devices keep their restored state after upgrading.
+Entity preferences are stored under keys derived from the sanitized object_id
+hash. This test seeds the host preferences file the way existing firmware
+wrote it and verifies the state is restored, proving the key scheme has not
+drifted; a save and reload round trip cannot catch drift because it writes
+and reads with the same code.
 
-This test seeds the host preferences file the way a pre-migration firmware
-would have written it and verifies:
-1. Data stored under the OLD key is restored (migration happened, no data loss)
-2. Data already stored under the NEW key is never overwritten by old data
+The second run also seeds the raw-name-hash entries a 2026.8 beta device left
+behind (see https://github.com/esphome/esphome/pull/18361) and proves they are
+ignored: the object_id entries win and the beta leftovers are inert.
 """
 
 from __future__ import annotations
@@ -33,22 +33,23 @@ from .host_prefs import clear_host_prefs, write_host_prefs
 from .state_utils import InitialStateHelper, require_entity
 from .types import CompileFunction, ConfigWriter
 
-DEVICE_NAME = "host-pref-key-migration"
+DEVICE_NAME = "host-pref-key-stability"
 
-# The pre-migration preference key was the sanitized object_id hash; the new
-# key is the raw-name hash. All entities are on the main device (device_id 0)
-# and their preferences use no version salt, so the key is just the hash.
-SWITCH_OLD_KEY = fnv1_hash_object_id("Test Switch")
-SWITCH_NEW_KEY = fnv1_hash_name("Test Switch")
-NUMBER_OLD_KEY = fnv1_hash_object_id("Test Number")
-NUMBER_NEW_KEY = fnv1_hash_name("Test Number")
+# All entities are on the main device (device_id 0) and their preferences use
+# no version salt, so the key is just the object_id hash.
+SWITCH_KEY = fnv1_hash_object_id("Test Switch")
+NUMBER_KEY = fnv1_hash_object_id("Test Number")
+
+# Raw-name-hash keys as written by 2026.8 beta firmware; never read by this build
+SWITCH_BETA_KEY = fnv1_hash_name("Test Switch")
+NUMBER_BETA_KEY = fnv1_hash_name("Test Number")
 
 # template_text salts its key with the length limits and pattern hash; this must
 # match TemplateText::setup() in template_text.cpp (min_length 0, max_length 20,
 # no pattern configured)
 TEXT_KEY_EXTRA = (0 << 2) + (20 << 4) + (fnv1_hash("") << 6)
-TEXT_OLD_KEY = (fnv1_hash_object_id("Test Text") + TEXT_KEY_EXTRA) & 0xFFFFFFFF
-TEXT_NEW_KEY = (fnv1_hash_name("Test Text") + TEXT_KEY_EXTRA) & 0xFFFFFFFF
+TEXT_KEY = (fnv1_hash_object_id("Test Text") + TEXT_KEY_EXTRA) & 0xFFFFFFFF
+TEXT_BETA_KEY = (fnv1_hash_name("Test Text") + TEXT_KEY_EXTRA) & 0xFFFFFFFF
 
 # TextSaver<20> stores a length-prefixed buffer of max_length + 1 bytes
 TEXT_MAX_LENGTH = 20
@@ -62,18 +63,18 @@ def text_pref_payload(value: str) -> bytes:
 
 
 @pytest.mark.asyncio
-async def test_preference_key_migration(
+async def test_preference_key_stability(
     yaml_config: str,
     write_yaml_config: ConfigWriter,
     compile_esphome: CompileFunction,
     reserved_tcp_port: tuple[int, socket.socket],
 ) -> None:
-    """Test that preferences stored under the old key survive the upgrade."""
+    """Test that preferences stored by earlier firmware are restored."""
     port, port_socket = reserved_tcp_port
 
-    assert SWITCH_OLD_KEY != SWITCH_NEW_KEY
-    assert NUMBER_OLD_KEY != NUMBER_NEW_KEY
-    assert TEXT_OLD_KEY != TEXT_NEW_KEY
+    assert SWITCH_KEY != SWITCH_BETA_KEY
+    assert NUMBER_KEY != NUMBER_BETA_KEY
+    assert TEXT_KEY != TEXT_BETA_KEY
 
     # Write and compile once
     config_path = await write_yaml_config(yaml_config)
@@ -117,49 +118,51 @@ async def test_preference_key_migration(
             return switch_state, number_state, text_state
 
     try:
-        # --- Run 1: only OLD keys present, as written by pre-migration firmware.
-        # The restored states prove the data was migrated to the new keys.
+        # --- Run 1: entries under the object_id-hash keys, exactly as any
+        # earlier firmware wrote them. The restored states prove the key
+        # scheme has not drifted.
         write_host_prefs(
             DEVICE_NAME,
             {
-                SWITCH_OLD_KEY: b"\x01",  # bool: switch was ON
-                NUMBER_OLD_KEY: struct.pack("<f", 42.5),
-                TEXT_OLD_KEY: text_pref_payload("hello"),
+                SWITCH_KEY: b"\x01",  # bool: switch was ON
+                NUMBER_KEY: struct.pack("<f", 42.5),
+                TEXT_KEY: text_pref_payload("hello"),
             },
         )
         switch_state, number_state, text_state = await boot_and_get_initial_states()
         assert switch_state.state is True, (
-            "Switch state stored under the old preference key was lost"
+            "Switch state stored under the object_id preference key was lost"
         )
         assert number_state.state == 42.5, (
-            "Number value stored under the old preference key was lost"
+            "Number value stored under the object_id preference key was lost"
         )
         assert text_state.state == "hello", (
-            "Text value stored under the old preference key was lost"
+            "Text value stored under the object_id preference key was lost"
         )
 
-        # --- Run 2: both keys present with different values. The NEW key holds
-        # the current data and must win; stale old-key data must never clobber it.
+        # --- Run 2: raw-name-hash entries from a 2026.8 beta device present
+        # alongside the object_id entries. The object_id data must win; the
+        # beta entries are never read.
         write_host_prefs(
             DEVICE_NAME,
             {
-                SWITCH_OLD_KEY: b"\x00",  # stale: OFF
-                SWITCH_NEW_KEY: b"\x01",  # current: ON
-                NUMBER_OLD_KEY: struct.pack("<f", 42.5),  # stale
-                NUMBER_NEW_KEY: struct.pack("<f", 13.5),  # current
-                TEXT_OLD_KEY: text_pref_payload("hello"),  # stale
-                TEXT_NEW_KEY: text_pref_payload("world"),  # current
+                SWITCH_KEY: b"\x01",  # current: ON
+                SWITCH_BETA_KEY: b"\x00",  # beta leftover: OFF
+                NUMBER_KEY: struct.pack("<f", 13.5),  # current
+                NUMBER_BETA_KEY: struct.pack("<f", 99.5),  # beta leftover
+                TEXT_KEY: text_pref_payload("world"),  # current
+                TEXT_BETA_KEY: text_pref_payload("ignored"),  # beta leftover
             },
         )
         switch_state, number_state, text_state = await boot_and_get_initial_states()
         assert switch_state.state is True, (
-            "Stale old-key data overwrote the current new-key switch state"
+            "Beta raw-name-key data overrode the object_id switch state"
         )
         assert number_state.state == 13.5, (
-            "Stale old-key data overwrote the current new-key number value"
+            "Beta raw-name-key data overrode the object_id number value"
         )
         assert text_state.state == "world", (
-            "Stale old-key data overwrote the current new-key text value"
+            "Beta raw-name-key data overrode the object_id text value"
         )
     finally:
         clear_host_prefs(DEVICE_NAME)

tests/integration/test_sensor_filters_delta.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import math
 
 from aioesphomeapi import ButtonInfo, EntityState, SensorState
 import pytest
@@ -25,6 +26,7 @@ async def test_sensor_filters_delta(
         "filter_baseline_max": [],
         "filter_zero_delta": [],
         "filter_percentage": [],
+        "filter_nan": [],
     }
 
     filter_min_done = loop.create_future()
@@ -32,16 +34,23 @@ async def test_sensor_filters_delta(
     filter_baseline_max_done = loop.create_future()
     filter_zero_delta_done = loop.create_future()
     filter_percentage_done = loop.create_future()
+    filter_nan_done = loop.create_future()
 
     def on_state(state: EntityState) -> None:
-        if not isinstance(state, SensorState) or state.missing_state:
+        if not isinstance(state, SensorState):
             return
 
         sensor_name = key_to_sensor.get(state.key)
         if sensor_name not in sensor_values:
             return
 
-        sensor_values[sensor_name].append(state.state)
+        if state.missing_state:
+            # Only the NaN test is interested in unavailable states
+            if sensor_name != "filter_nan":
+                return
+            sensor_values[sensor_name].append(math.nan)
+        else:
+            sensor_values[sensor_name].append(state.state)
 
         # Check completion conditions
         if (
@@ -74,6 +83,12 @@ async def test_sensor_filters_delta(
             and not filter_percentage_done.done()
         ):
             filter_percentage_done.set_result(True)
+        elif (
+            sensor_name == "filter_nan"
+            and len(sensor_values[sensor_name]) == 3
+            and not filter_nan_done.done()
+        ):
+            filter_nan_done.set_result(True)
 
     async with (
         run_compiled(yaml_config),
@@ -89,6 +104,7 @@ async def test_sensor_filters_delta(
                 "filter_baseline_max": "Filter Baseline Max",
                 "filter_zero_delta": "Filter Zero Delta",
                 "filter_percentage": "Filter Percentage",
+                "filter_nan": "Filter NaN",
             },
         )
 
@@ -108,13 +124,14 @@ async def test_sensor_filters_delta(
             "Test Filter Baseline Max": "filter_baseline_max",
             "Test Filter Zero Delta": "filter_zero_delta",
             "Test Filter Percentage": "filter_percentage",
+            "Test Filter NaN": "filter_nan",
         }
         buttons = {}
         for entity in entities:
             if isinstance(entity, ButtonInfo) and entity.name in button_name_map:
                 buttons[button_name_map[entity.name]] = entity.key
 
-        assert len(buttons) == 5, f"Expected 5 buttons, found {len(buttons)}"
+        assert len(buttons) == 6, f"Expected 6 buttons, found {len(buttons)}"
 
         # Test 1: Min
         sensor_values["filter_min"].clear()
@@ -186,3 +203,18 @@ async def test_sensor_filters_delta(
         assert sensor_values["filter_percentage"] == pytest.approx(expected), (
             f"Test 5 failed: expected {expected}, got {sensor_values['filter_percentage']}"
         )
+
+        # Test 6: NaN passes through once, then is suppressed
+        sensor_values["filter_nan"].clear()
+        client.button_command(buttons["filter_nan"])
+        try:
+            await asyncio.wait_for(filter_nan_done, timeout=2.0)
+        except TimeoutError:
+            pytest.fail(f"Test 6 timed out. Values: {sensor_values['filter_nan']}")
+
+        values = sensor_values["filter_nan"]
+        assert values[0] == pytest.approx(1.0), f"Test 6 failed: got {values}"
+        assert math.isnan(values[1]), (
+            f"Test 6 failed: NaN not passed through, got {values}"
+        )
+        assert values[2] == pytest.approx(2.0), f"Test 6 failed: got {values}"

tests/script/test_helpers.py

@@ -20,6 +20,7 @@ changed_files = helpers.changed_files
 filter_changed = helpers.filter_changed
 get_changed_components = helpers.get_changed_components
 _get_changed_files_from_command = helpers._get_changed_files_from_command
+run_gh_command = helpers.run_gh_command
 _get_pr_number_from_github_env = helpers._get_pr_number_from_github_env
 _get_changed_files_github_actions = helpers._get_changed_files_github_actions
 _filter_changed_ci = helpers._filter_changed_ci
@@ -243,6 +244,44 @@ def test_get_changed_files_github_actions_pull_request_large_pr(
         assert result == expected_files
 
 
+def test_get_changed_files_github_actions_pull_request_large_diff(
+    monkeypatch: MonkeyPatch,
+) -> None:
+    """Test _get_changed_files_github_actions fallback for PRs with >20000 diff lines."""
+    monkeypatch.setenv("GITHUB_EVENT_NAME", "pull_request")
+
+    expected_files = ["file1.py", "file2.cpp"]
+
+    with (
+        patch("helpers._get_pr_number_from_github_env", return_value="17909"),
+        patch("helpers._get_changed_files_from_command") as mock_get,
+    ):
+        # First call fails with too many diff lines error, second succeeds with API method
+        mock_get.side_effect = [
+            Exception(
+                "could not find pull request diff: HTTP 406: Sorry, "
+                "the diff exceeded the maximum number of lines (20000)"
+            ),
+            expected_files,
+        ]
+
+        result = _get_changed_files_github_actions()
+
+        assert mock_get.call_count == 2
+        mock_get.assert_any_call(["gh", "pr", "diff", "17909", "--name-only"])
+        mock_get.assert_any_call(
+            [
+                "gh",
+                "api",
+                "repos/esphome/esphome/pulls/17909/files",
+                "--paginate",
+                "--jq",
+                ".[].filename",
+            ]
+        )
+        assert result == expected_files
+
+
 def test_get_changed_files_github_actions_pull_request_other_error(
     monkeypatch: MonkeyPatch,
 ) -> None:
@@ -1872,3 +1911,123 @@ def test_is_validate_only_file(filename: str, expected: bool, tmp_path: Path) ->
 def test_base_python_changed(files: list[str], expected: bool) -> None:
     """Only Python modules directly in esphome/ count as base Python changes."""
     assert helpers.base_python_changed(files) is expected
+
+
+def _gh_error(stderr: str) -> subprocess.CalledProcessError:
+    return subprocess.CalledProcessError(1, ["gh"], output="", stderr=stderr)
+
+
+def _gh_success(stdout: str = "ok\n") -> subprocess.CompletedProcess:
+    return subprocess.CompletedProcess(["gh"], 0, stdout=stdout, stderr="")
+
+
+def test_run_gh_command_success() -> None:
+    """A successful command returns without retrying."""
+    with patch("helpers.subprocess.run", return_value=_gh_success()) as mock_run:
+        result = run_gh_command(["gh", "pr", "diff", "123", "--name-only"])
+
+    assert result.stdout == "ok\n"
+    mock_run.assert_called_once()
+
+
+@pytest.mark.parametrize(
+    "second_error",
+    [
+        (
+            'Post "https://api.github.com/graphql": tls: failed to verify'
+            " certificate: x509: certificate is not valid for any names,"
+            " but wanted to match api.github.com"
+        ),
+        'Post "https://api.github.com/graphql": EOF',
+        (
+            "error connecting to api.github.com\n"
+            "check your internet connection or https://githubstatus.com"
+        ),
+    ],
+)
+def test_run_gh_command_retries_transient_error(second_error: str) -> None:
+    """Transient server errors are retried with 2s/4s backoff."""
+    with (
+        patch(
+            "helpers.subprocess.run",
+            side_effect=[
+                _gh_error("HTTP 502: 502 Bad Gateway (https://api.github.com/graphql)"),
+                _gh_error(second_error),
+                _gh_success(),
+            ],
+        ) as mock_run,
+        patch("helpers.time.sleep") as mock_sleep,
+    ):
+        result = run_gh_command(["gh", "pr", "diff", "123", "--name-only"])
+
+    assert result.stdout == "ok\n"
+    assert mock_run.call_count == 3
+    assert [call.args[0] for call in mock_sleep.call_args_list] == [2, 4]
+
+
+def test_run_gh_command_gives_up_after_max_attempts() -> None:
+    """A persistent transient error raises after the third attempt."""
+    with (
+        patch(
+            "helpers.subprocess.run",
+            side_effect=_gh_error("HTTP 503: Service Unavailable"),
+        ) as mock_run,
+        patch("helpers.time.sleep") as mock_sleep,
+        pytest.raises(subprocess.CalledProcessError),
+    ):
+        run_gh_command(["gh", "pr", "diff", "123", "--name-only"])
+
+    assert mock_run.call_count == 3
+    assert mock_sleep.call_count == 2
+
+
+@pytest.mark.parametrize(
+    "stderr",
+    [
+        "HTTP 404: Not Found (https://api.github.com/repos/x)",
+        "HTTP 401: Bad credentials",
+        "HTTP 403: API rate limit exceeded for installation ID 123.",
+        "diff exceeded the maximum number of changed files (300)",
+        (
+            "GraphQL: Could not resolve to a PullRequest with the number of 999999."
+            " (repository.pullRequest)"
+        ),
+    ],
+)
+def test_run_gh_command_permanent_error_not_retried(stderr: str) -> None:
+    """Permanent failures raise immediately without any retry."""
+    with (
+        patch("helpers.subprocess.run", side_effect=_gh_error(stderr)) as mock_run,
+        patch("helpers.time.sleep") as mock_sleep,
+        pytest.raises(subprocess.CalledProcessError),
+    ):
+        run_gh_command(["gh", "pr", "diff", "123", "--name-only"])
+
+    mock_run.assert_called_once()
+    mock_sleep.assert_not_called()
+
+
+def test_run_gh_command_no_retry_for_non_idempotent_commands() -> None:
+    """retry=False fails on the first error even when it looks transient."""
+    with (
+        patch(
+            "helpers.subprocess.run",
+            side_effect=_gh_error("HTTP 502: 502 Bad Gateway"),
+        ) as mock_run,
+        patch("helpers.time.sleep") as mock_sleep,
+        pytest.raises(subprocess.CalledProcessError),
+    ):
+        run_gh_command(["gh", "pr", "comment", "123", "--body", "x"], retry=False)
+
+    mock_run.assert_called_once()
+    mock_sleep.assert_not_called()
+
+
+def test_get_changed_files_from_command_gh_failure_keeps_stderr() -> None:
+    """Failures from gh surface stderr so callers can detect the 300-file limit."""
+    stderr = "diff exceeded the maximum number of changed files (300)"
+    with (
+        patch("helpers.subprocess.run", side_effect=_gh_error(stderr)),
+        pytest.raises(Exception, match="maximum number of changed files"),
+    ):
+        _get_changed_files_from_command(["gh", "pr", "diff", "123", "--name-only"])

tests/unit_tests/components/light/test_channel_colors.py

@@ -0,0 +1,144 @@
+"""Tests for the shared addressable-strip channel order helpers."""
+
+import logging
+
+import pytest
+
+from esphome.components.const import CONF_CHANNEL_COLORS, CONF_IS_WRGB
+from esphome.components.light import (
+    channel_colors_struct,
+    migrate_channel_colors,
+    validate_channel_colors,
+)
+import esphome.config_validation as cv
+from esphome.const import CONF_IS_RGBW, CONF_RGB_ORDER
+from esphome.types import ConfigType
+
+NO_WHITE = "light::ChannelColors::NO_WHITE"
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [
+        ("RGB", "RGB"),
+        ("grb", "GRB"),
+        ("BRG", "BRG"),
+        ("rgbw", "RGBW"),
+        ("WRGB", "WRGB"),
+        ("GWRB", "GWRB"),
+    ],
+)
+def test_validate_channel_colors(value: str, expected: str) -> None:
+    assert validate_channel_colors(value) == expected
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "RG",  # missing a channel
+        "RGBB",  # duplicate channel
+        "RRGB",  # duplicate channel, correct length
+        "RGBWW",  # two white channels
+        "RGBX",  # unknown channel
+        "RGBWX",  # unknown channel, correct length
+        "",
+    ],
+)
+def test_validate_channel_colors_rejects_invalid(value: str) -> None:
+    with pytest.raises(cv.Invalid, match="is not a valid channel order"):
+        validate_channel_colors(value)
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [
+        ("RGB", (0, 1, 2, NO_WHITE)),
+        ("GRB", (1, 0, 2, NO_WHITE)),
+        ("BRG", (1, 2, 0, NO_WHITE)),
+        ("RGBW", (0, 1, 2, 3)),
+        ("GRBW", (1, 0, 2, 3)),
+        ("WRGB", (1, 2, 3, 0)),
+        ("GWRB", (2, 0, 3, 1)),
+    ],
+)
+def test_channel_colors_struct(value: str, expected: tuple[int, int, int, int]) -> None:
+    struct = channel_colors_struct(value)
+    assert str(struct.base) == "light::ChannelColors"
+    assert tuple(str(arg) for arg in struct.args.values()) == tuple(
+        str(field) for field in expected
+    )
+
+
+def _migrate(config: ConfigType) -> ConfigType:
+    return migrate_channel_colors(removed_in="2027.3.0", component="test_strip")(config)
+
+
+def test_migrate_passes_through_channel_colors() -> None:
+    config = {CONF_CHANNEL_COLORS: "GRBW"}
+    assert _migrate(config) == {CONF_CHANNEL_COLORS: "GRBW"}
+
+
+@pytest.mark.parametrize(
+    ("deprecated", "expected", "named"),
+    [
+        ({}, "GRB", "'rgb_order' is"),
+        (
+            {CONF_IS_RGBW: False, CONF_IS_WRGB: False},
+            "GRB",
+            "'rgb_order', 'is_rgbw' and 'is_wrgb' are",
+        ),
+        ({CONF_IS_RGBW: True}, "GRBW", "'rgb_order' and 'is_rgbw' are"),
+        ({CONF_IS_WRGB: True}, "WGRB", "'rgb_order' and 'is_wrgb' are"),
+    ],
+)
+def test_migrate_folds_deprecated_keys(
+    deprecated: ConfigType,
+    expected: str,
+    named: str,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    config = {CONF_RGB_ORDER: "GRB", "num_leds": 1, **deprecated}
+    with caplog.at_level(logging.WARNING):
+        result = _migrate(config)
+
+    assert result == {CONF_CHANNEL_COLORS: expected, "num_leds": 1}
+    assert f"[test_strip] {named} deprecated" in caplog.text
+    assert f"'{CONF_CHANNEL_COLORS}: {expected}'" in caplog.text
+    assert "2027.3.0" in caplog.text
+
+
+def test_migrate_does_not_mutate_input() -> None:
+    config = {CONF_RGB_ORDER: "GRB", CONF_IS_RGBW: True}
+    _migrate(config)
+    assert config == {CONF_RGB_ORDER: "GRB", CONF_IS_RGBW: True}
+
+
+@pytest.mark.parametrize("deprecated", [CONF_RGB_ORDER, CONF_IS_RGBW, CONF_IS_WRGB])
+def test_migrate_rejects_mixing_old_and_new(deprecated: str) -> None:
+    config = {CONF_CHANNEL_COLORS: "GRBW", deprecated: "GRB"}
+    with pytest.raises(cv.Invalid, match=f"cannot be combined with '{deprecated}'"):
+        _migrate(config)
+
+
+def test_migrate_reports_every_conflicting_key() -> None:
+    config = {
+        CONF_CHANNEL_COLORS: "GRBW",
+        CONF_RGB_ORDER: "GRB",
+        CONF_IS_RGBW: True,
+        CONF_IS_WRGB: False,
+    }
+    with pytest.raises(
+        cv.Invalid, match="cannot be combined with 'rgb_order', 'is_rgbw' and 'is_wrgb'"
+    ):
+        _migrate(config)
+
+
+def test_migrate_requires_channel_colors() -> None:
+    with pytest.raises(cv.Invalid, match=f"'{CONF_CHANNEL_COLORS}' is required"):
+        _migrate({"num_leds": 1})
+
+
+def test_migrate_rejects_is_rgbw_with_is_wrgb() -> None:
+    config = {CONF_RGB_ORDER: "GRB", CONF_IS_RGBW: True, CONF_IS_WRGB: True}
+    with pytest.raises(cv.Invalid, match="cannot both be enabled"):
+        _migrate(config)

tests/unit_tests/components/mqtt/test_object_id_conflicts.py

@@ -1,239 +0,0 @@
-"""Tests for the MQTT object_id conflict filter.
-
-MQTT still builds default topics and discovery topics from the sanitized
-object_id, so entity names that only differ in characters lost during
-sanitizing conflict there; _topics_conflict() exempts entities that never
-use an object_id-derived topic. See https://github.com/esphome/backlog/issues/85
-"""
-
-from pathlib import Path
-
-import pytest
-
-from esphome.components.mqtt import (
-    _COMMAND_TOPIC_PLATFORMS,
-    _SUB_TOPIC_PLATFORMS,
-    _topics_conflict,
-)
-from esphome.config_validation import Invalid
-from esphome.const import (
-    CONF_COMMAND_TOPIC,
-    CONF_DISCOVERY,
-    CONF_NAME,
-    CONF_STATE_TOPIC,
-    CONF_TOPIC_PREFIX,
-)
-from esphome.core import CORE
-from esphome.core.entity_helpers import (
-    entity_duplicate_validator,
-    validate_no_object_id_conflicts,
-)
-
-COMPONENTS_DIR = Path(__file__).parents[4] / "esphome" / "components"
-
-REASON = "mqtt builds default topics from the entity object_id"
-
-
-# MQTT infrastructure sources, not entity components
-_NON_ENTITY_MQTT_SOURCES = {"mqtt_client", "mqtt_component"}
-# The date, time and datetime MQTT components all belong to the datetime platform
-_DATETIME_STEMS = {"date", "time", "datetime"}
-
-
-def test_command_topic_platforms_in_sync() -> None:
-    """Verify _COMMAND_TOPIC_PLATFORMS matches the MQTT components that subscribe.
-
-    Drift silently reintroduces shared subscribe topics, so this derives the set
-    from the C++ components that actually call subscribe(); that also catches
-    platforms like text that subscribe a command topic without exposing a
-    command_topic key in their schema.
-    """
-    expected: set[str] = set()
-    for path in (COMPONENTS_DIR / "mqtt").glob("mqtt_*.cpp"):
-        if path.stem in _NON_ENTITY_MQTT_SOURCES:
-            continue
-        if "this->subscribe" not in path.read_text(encoding="utf-8"):
-            continue
-        stem = path.stem.removeprefix("mqtt_")
-        expected.add("datetime" if stem in _DATETIME_STEMS else stem)
-    assert expected == _COMMAND_TOPIC_PLATFORMS
-
-
-def test_sub_topic_platforms_in_sync() -> None:
-    """Verify _SUB_TOPIC_PLATFORMS matches the MQTT components with sub-topics.
-
-    Platforms whose MQTT headers use MQTT_COMPONENT_CUSTOM_TOPIC derive extra
-    topics such as position/command from the object_id.
-    """
-    expected = {
-        path.stem.removeprefix("mqtt_")
-        for path in (COMPONENTS_DIR / "mqtt").glob("mqtt_*.h")
-        if path.stem != "mqtt_component"
-        and "MQTT_COMPONENT_CUSTOM_TOPIC" in path.read_text(encoding="utf-8")
-    }
-    assert expected == _SUB_TOPIC_PLATFORMS
-
-
-def test_conflict_filter_exempts_custom_topics() -> None:
-    """Test that custom state topics with discovery off avoid the conflict."""
-    validator = entity_duplicate_validator("sensor")
-    # Both entities have custom state topics and discovery disabled per entity,
-    # so no object_id-derived MQTT topic is used
-    validator(
-        {
-            CONF_NAME: "Датчик открытия",
-            CONF_STATE_TOPIC: "custom/topic/a",
-            CONF_DISCOVERY: False,
-        }
-    )
-    validator(
-        {
-            CONF_NAME: "Датчик закрытия",
-            CONF_STATE_TOPIC: "custom/topic/b",
-            CONF_DISCOVERY: False,
-        }
-    )
-
-    component_validator = validate_no_object_id_conflicts(
-        REASON, conflict_filter=_topics_conflict
-    )
-    config: dict = {CONF_DISCOVERY: True, CONF_TOPIC_PREFIX: "test-device"}
-    assert component_validator(config) is config
-
-    # Without the filter the same conflicts are fatal
-    with pytest.raises(Invalid, match=r"mqtt builds default topics"):
-        validate_no_object_id_conflicts(REASON)({})
-
-
-def test_conflict_on_default_command_topic() -> None:
-    """Test that commandable platforms conflict through their default command topic.
-
-    Custom state topics with discovery off are not enough for platforms that also
-    subscribe to an object_id-derived command topic.
-    """
-    validator = entity_duplicate_validator("switch")
-    validator(
-        {
-            CONF_NAME: "Датчик открытия",
-            CONF_STATE_TOPIC: "custom/topic/a",
-            CONF_DISCOVERY: False,
-        }
-    )
-    validator(
-        {
-            CONF_NAME: "Датчик закрытия",
-            CONF_STATE_TOPIC: "custom/topic/b",
-            CONF_DISCOVERY: False,
-        }
-    )
-
-    component_validator = validate_no_object_id_conflicts(
-        REASON, conflict_filter=_topics_conflict
-    )
-    mqtt_config: dict = {CONF_DISCOVERY: True, CONF_TOPIC_PREFIX: "test-device"}
-    # Both switches share the default command topic: rejected
-    with pytest.raises(Invalid, match=r"mqtt builds default topics"):
-        component_validator(mqtt_config)
-
-    # With custom command topics as well, nothing derives from the object_id
-    CORE.reset()
-    validator = entity_duplicate_validator("switch")
-    validator(
-        {
-            CONF_NAME: "Датчик открытия",
-            CONF_STATE_TOPIC: "custom/topic/a",
-            CONF_COMMAND_TOPIC: "custom/cmd/a",
-            CONF_DISCOVERY: False,
-        }
-    )
-    validator(
-        {
-            CONF_NAME: "Датчик закрытия",
-            CONF_STATE_TOPIC: "custom/topic/b",
-            CONF_COMMAND_TOPIC: "custom/cmd/b",
-            CONF_DISCOVERY: False,
-        }
-    )
-    assert component_validator(mqtt_config) is mqtt_config
-
-
-def test_conflict_on_sub_topic_platforms() -> None:
-    """Test that platforms with extra object_id sub-topics always conflict.
-
-    Covers derive topics like position/command from the object_id through their
-    own config keys, so custom state and command topics cannot exempt them.
-    """
-    validator = entity_duplicate_validator("cover")
-    validator(
-        {
-            CONF_NAME: "Датчик открытия",
-            CONF_STATE_TOPIC: "custom/topic/a",
-            CONF_COMMAND_TOPIC: "custom/cmd/a",
-            CONF_DISCOVERY: False,
-        }
-    )
-    validator(
-        {
-            CONF_NAME: "Датчик закрытия",
-            CONF_STATE_TOPIC: "custom/topic/b",
-            CONF_COMMAND_TOPIC: "custom/cmd/b",
-            CONF_DISCOVERY: False,
-        }
-    )
-
-    component_validator = validate_no_object_id_conflicts(
-        REASON, conflict_filter=_topics_conflict
-    )
-    with pytest.raises(Invalid, match=r"mqtt builds default topics"):
-        component_validator({CONF_DISCOVERY: True, CONF_TOPIC_PREFIX: "test-device"})
-
-
-def test_no_conflict_on_disjoint_default_topics() -> None:
-    """Test that entities whose default topics are disjoint do not conflict.
-
-    One entity uses only the default command topic and the other only the default
-    state topic, so they never share a topic.
-    """
-    validator = entity_duplicate_validator("switch")
-    validator(
-        {
-            CONF_NAME: "Датчик открытия",
-            CONF_STATE_TOPIC: "custom/topic/a",
-            CONF_DISCOVERY: False,
-        }
-    )
-    validator(
-        {
-            CONF_NAME: "Датчик закрытия",
-            CONF_COMMAND_TOPIC: "custom/cmd/b",
-            CONF_DISCOVERY: False,
-        }
-    )
-
-    component_validator = validate_no_object_id_conflicts(
-        REASON, conflict_filter=_topics_conflict
-    )
-    config: dict = {CONF_DISCOVERY: True, CONF_TOPIC_PREFIX: "test-device"}
-    assert component_validator(config) is config
-
-
-def test_no_conflict_on_empty_topic_prefix() -> None:
-    """Test that an empty topic_prefix disables the default topic conflict.
-
-    With topic_prefix set to null no default topics exist at runtime, so entities
-    without custom state topics cannot conflict; only discovery still matters.
-    """
-    validator = entity_duplicate_validator("sensor")
-    validator({CONF_NAME: "Датчик открытия"})
-    validator({CONF_NAME: "Датчик закрытия"})
-
-    component_validator = validate_no_object_id_conflicts(
-        REASON, conflict_filter=_topics_conflict
-    )
-    # No default topics and no discovery: valid
-    config: dict = {CONF_DISCOVERY: False, CONF_TOPIC_PREFIX: ""}
-    assert component_validator(config) is config
-
-    # Discovery still uses object_id-derived config topics: rejected
-    with pytest.raises(Invalid, match=r"mqtt builds default topics"):
-        component_validator({CONF_DISCOVERY: True, CONF_TOPIC_PREFIX: ""})

tests/unit_tests/components/test_esp32_rmt_led_strip.py

@@ -1,57 +0,0 @@
-import pytest
-
-from esphome.components.esp32_rmt_led_strip.light import (
-    CONF_IS_WRGB,
-    CONF_RGBW_ORDER,
-    _split_rgbw_order,
-    _validate_rgbw_order,
-    _validate_rgbw_order_exclusivity,
-)
-import esphome.config_validation as cv
-from esphome.const import CONF_IS_RGBW
-
-
-def test_validate_rgbw_order() -> None:
-    assert _validate_rgbw_order("rwgb") == "RWGB"
-
-
-@pytest.mark.parametrize("rgbw_order", ["RGB", "RRGB", "RGBWW"])
-def test_validate_rgbw_order_rejects_invalid_order(rgbw_order: str) -> None:
-    with pytest.raises(cv.Invalid, match="permutation of RGBW"):
-        _validate_rgbw_order(rgbw_order)
-
-
-@pytest.mark.parametrize(
-    ("rgbw_order", "expected"),
-    [
-        ("WRGB", ("RGB", 0)),
-        ("RWGB", ("RGB", 1)),
-        ("GWRB", ("GRB", 1)),
-        ("RGBW", ("RGB", 3)),
-    ],
-)
-def test_split_rgbw_order(rgbw_order: str, expected: tuple[str, int]) -> None:
-    assert _split_rgbw_order(rgbw_order) == expected
-
-
-@pytest.mark.parametrize("conflict", [CONF_IS_RGBW, CONF_IS_WRGB])
-def test_rgbw_order_is_mutually_exclusive(conflict: str) -> None:
-    with pytest.raises(cv.Invalid, match="cannot be used with"):
-        _validate_rgbw_order_exclusivity(
-            {
-                CONF_RGBW_ORDER: "RGBW",
-                CONF_IS_RGBW: conflict == CONF_IS_RGBW,
-                CONF_IS_WRGB: conflict == CONF_IS_WRGB,
-            }
-        )
-
-
-@pytest.mark.parametrize("legacy_option", [CONF_IS_RGBW, CONF_IS_WRGB])
-def test_rgbw_order_allows_disabled_legacy_options(legacy_option: str) -> None:
-    config = {
-        CONF_RGBW_ORDER: "RGBW",
-        CONF_IS_RGBW: False,
-        CONF_IS_WRGB: False,
-    }
-    config[legacy_option] = False
-    assert _validate_rgbw_order_exclusivity(config) is config

tests/unit_tests/core/test_entity_helpers.py

@@ -1,4 +1,4 @@
-"""Tests for entity helpers: name selection, entity key hashing, duplicate checks."""
+"""Test get_base_entity_object_id function matches C++ behavior."""
 
 from collections.abc import Callable, Generator
 from pathlib import Path
@@ -25,17 +25,16 @@ from esphome.core.entity_helpers import (
     _setup_entity_impl,
     entity_duplicate_validator,
     finalize_entity_strings,
-    get_base_entity_name,
+    get_base_entity_object_id,
     register_device_class,
     register_icon,
     register_unit_of_measurement,
     setup_device_class,
     setup_entity,
     setup_unit_of_measurement,
-    validate_no_object_id_conflicts,
 )
 from esphome.cpp_generator import MockObj
-from esphome.helpers import fnv1_hash_name, sanitize, snake_case
+from esphome.helpers import fnv1_hash, sanitize, snake_case
 
 from .common import load_config_from_fixture
 
@@ -58,26 +57,206 @@ def restore_core_state() -> Generator[None, None, None]:
     CORE.friendly_name = original_friendly_name
 
 
-def test_get_base_entity_name_priority_order() -> None:
+def test_with_entity_name() -> None:
+    """Test when entity has its own name - should use entity name."""
+    # Simple name
+    assert get_base_entity_object_id("Temperature Sensor", None) == "temperature_sensor"
+    assert (
+        get_base_entity_object_id("Temperature Sensor", "Device Name")
+        == "temperature_sensor"
+    )
+    # Even with device name, entity name takes precedence
+    assert (
+        get_base_entity_object_id("Temperature Sensor", "Device Name", "Sub Device")
+        == "temperature_sensor"
+    )
+
+    # Name with special characters
+    assert (
+        get_base_entity_object_id("Temp!@#$%^&*()Sensor", None)
+        == "temp__________sensor"
+    )
+    assert get_base_entity_object_id("Temp-Sensor_123", None) == "temp-sensor_123"
+
+    # Already snake_case
+    assert get_base_entity_object_id("temperature_sensor", None) == "temperature_sensor"
+
+    # Mixed case
+    assert get_base_entity_object_id("TemperatureSensor", None) == "temperaturesensor"
+    assert get_base_entity_object_id("TEMPERATURE SENSOR", None) == "temperature_sensor"
+
+
+def test_empty_name_with_device_name() -> None:
+    """Test when entity has empty name and is on a sub-device - should use device name."""
+    # C++ behavior: when has_own_name is false and device is set, uses device->get_name()
+    assert (
+        get_base_entity_object_id("", "Friendly Device", "Sub Device 1")
+        == "sub_device_1"
+    )
+    assert (
+        get_base_entity_object_id("", "Kitchen Controller", "controller_1")
+        == "controller_1"
+    )
+    assert get_base_entity_object_id("", None, "Test-Device_123") == "test-device_123"
+
+
+def test_empty_name_with_friendly_name() -> None:
+    """Test when entity has empty name and no device - should use friendly name."""
+    # C++ behavior: when has_own_name is false, uses App.get_friendly_name()
+    assert get_base_entity_object_id("", "Friendly Device") == "friendly_device"
+    assert get_base_entity_object_id("", "Kitchen Controller") == "kitchen_controller"
+    assert get_base_entity_object_id("", "Test-Device_123") == "test-device_123"
+
+    # Special characters in friendly name
+    assert get_base_entity_object_id("", "Device!@#$%") == "device_____"
+
+
+def test_empty_name_no_friendly_name() -> None:
+    """Test when entity has empty name and no friendly name - should use device name."""
+    # Test with CORE.name set
+    CORE.name = "device-name"
+    assert get_base_entity_object_id("", None) == "device-name"
+
+    CORE.name = "Test Device"
+    assert get_base_entity_object_id("", None) == "test_device"
+
+
+def test_edge_cases() -> None:
+    """Test edge cases."""
+    # Only spaces
+    assert get_base_entity_object_id("   ", None) == "___"
+
+    # Unicode characters (should be replaced)
+    assert get_base_entity_object_id("Température", None) == "temp_rature"
+    assert get_base_entity_object_id("测试", None) == "__"
+
+    # Empty string with empty friendly name (empty friendly name is treated as None)
+    # Falls back to CORE.name
+    CORE.name = "device"
+    assert get_base_entity_object_id("", "") == "device"
+
+    # Very long name (should work fine)
+    long_name = "a" * 100 + " " + "b" * 100
+    expected = "a" * 100 + "_" + "b" * 100
+    assert get_base_entity_object_id(long_name, None) == expected
+
+
+@pytest.mark.parametrize(
+    ("name", "expected"),
+    [
+        ("Temperature Sensor", "temperature_sensor"),
+        ("Living Room Light", "living_room_light"),
+        ("Test-Device_123", "test-device_123"),
+        ("Special!@#Chars", "special___chars"),
+        ("UPPERCASE NAME", "uppercase_name"),
+        ("lowercase name", "lowercase_name"),
+        ("Mixed Case Name", "mixed_case_name"),
+        ("   Spaces   ", "___spaces___"),
+    ],
+)
+def test_matches_cpp_helpers(name: str, expected: str) -> None:
+    """Test that the logic matches using snake_case and sanitize directly."""
+    # For non-empty names, verify our function produces same result as direct snake_case + sanitize
+    assert get_base_entity_object_id(name, None) == sanitize(snake_case(name))
+    assert get_base_entity_object_id(name, None) == expected
+
+
+def test_empty_name_fallback() -> None:
+    """Test empty name handling which falls back to friendly_name or CORE.name."""
+    # Empty name is handled specially - it doesn't just use sanitize(snake_case(""))
+    # Instead it falls back to friendly_name or CORE.name
+    assert sanitize(snake_case("")) == ""  # Direct conversion gives empty string
+    # But our function returns a fallback
+    CORE.name = "device"
+    assert get_base_entity_object_id("", None) == "device"  # Uses device name
+
+
+def test_name_add_mac_suffix_behavior() -> None:
+    """Test behavior related to name_add_mac_suffix.
+
+    In C++, an entity's object_id is computed from its name_ via
+    write_object_id_to() (sanitized snake_case). When an entity has no name,
+    configure_entity_() sets name_ from the friendly name, with the MAC suffix
+    appended when name_add_mac_suffix is enabled. Our function always returns
+    the same result since we're calculating the base for duplicate tracking.
+    """
+    # The function should always return the same result regardless of
+    # name_add_mac_suffix setting, as we're calculating the base object_id
+    assert get_base_entity_object_id("", "Test Device") == "test_device"
+    assert get_base_entity_object_id("Entity Name", "Test Device") == "entity_name"
+
+
+def test_priority_order() -> None:
     """Test the priority order: entity name > device name > friendly name > CORE.name."""
     CORE.name = "core-device"
 
-    # 1. Entity name has highest priority and is used as-is, no transformations
+    # 1. Entity name has highest priority
     assert (
-        get_base_entity_name("Entity Name", "Friendly Name", "Device Name")
-        == "Entity Name"
+        get_base_entity_object_id("Entity Name", "Friendly Name", "Device Name")
+        == "entity_name"
     )
-    assert get_base_entity_name("Température", None) == "Température"
 
     # 2. Device name is next priority (when entity name is empty)
-    assert get_base_entity_name("", "Friendly Name", "Device Name") == "Device Name"
+    assert (
+        get_base_entity_object_id("", "Friendly Name", "Device Name") == "device_name"
+    )
 
     # 3. Friendly name is next (when entity and device names are empty)
-    assert get_base_entity_name("", "Friendly Name", None) == "Friendly Name"
+    assert get_base_entity_object_id("", "Friendly Name", None) == "friendly_name"
 
-    # 4. CORE.name is last resort; an empty friendly name falls through to it
-    assert get_base_entity_name("", None, None) == "core-device"
-    assert get_base_entity_name("", "") == "core-device"
+    # 4. CORE.name is last resort
+    assert get_base_entity_object_id("", None, None) == "core-device"
+
+
+@pytest.mark.parametrize(
+    ("name", "friendly_name", "device_name", "expected"),
+    [
+        # name, friendly_name, device_name, expected
+        ("Living Room Light", None, None, "living_room_light"),
+        ("", "Kitchen Controller", None, "kitchen_controller"),
+        (
+            "",
+            "ESP32 Device",
+            "controller_1",
+            "controller_1",
+        ),  # Device name takes precedence
+        ("GPIO2 Button", None, None, "gpio2_button"),
+        ("WiFi Signal", "My Device", None, "wifi_signal"),
+        ("", None, "esp32_node", "esp32_node"),
+        ("Front Door Sensor", "Home Assistant", "door_controller", "front_door_sensor"),
+    ],
+)
+def test_real_world_examples(
+    name: str, friendly_name: str | None, device_name: str | None, expected: str
+) -> None:
+    """Test real-world entity naming scenarios."""
+    result = get_base_entity_object_id(name, friendly_name, device_name)
+    assert result == expected
+
+
+def test_issue_6953_scenarios() -> None:
+    """Test specific scenarios from issue #6953."""
+    # Scenario 1: Multiple empty names on main device with name_add_mac_suffix
+    # The Python code calculates the base, C++ might append MAC suffix dynamically
+    CORE.name = "device-name"
+    CORE.friendly_name = "Friendly Device"
+
+    # All empty names should resolve to same base
+    assert get_base_entity_object_id("", CORE.friendly_name) == "friendly_device"
+    assert get_base_entity_object_id("", CORE.friendly_name) == "friendly_device"
+    assert get_base_entity_object_id("", CORE.friendly_name) == "friendly_device"
+
+    # Scenario 2: Empty names on sub-devices
+    assert (
+        get_base_entity_object_id("", "Main Device", "controller_1") == "controller_1"
+    )
+    assert (
+        get_base_entity_object_id("", "Main Device", "controller_2") == "controller_2"
+    )
+
+    # Scenario 3: xyz duplicates
+    assert get_base_entity_object_id("xyz", None) == "xyz"
+    assert get_base_entity_object_id("xyz", "Device") == "xyz"
 
 
 # Tests for setup_entity function
@@ -336,10 +515,9 @@ def test_entity_duplicate_validator() -> None:
     config1 = {CONF_NAME: "Temperature"}
     validated1 = validator(config1)
     assert validated1 == config1
-    temperature_key = ("", "sensor", fnv1_hash_name("Temperature"))
-    assert temperature_key in CORE.unique_ids
+    assert ("", "sensor", fnv1_hash("temperature")) in CORE.unique_ids
     # Check metadata was stored
-    metadata = CORE.unique_ids[temperature_key]
+    metadata = CORE.unique_ids[("", "sensor", fnv1_hash("temperature"))]
     assert metadata["name"] == "Temperature"
     assert metadata["platform"] == "sensor"
 
@@ -347,9 +525,8 @@ def test_entity_duplicate_validator() -> None:
     config2 = {CONF_NAME: "Humidity"}
     validated2 = validator(config2)
     assert validated2 == config2
-    humidity_key = ("", "sensor", fnv1_hash_name("Humidity"))
-    assert humidity_key in CORE.unique_ids
-    metadata2 = CORE.unique_ids[humidity_key]
+    assert ("", "sensor", fnv1_hash("humidity")) in CORE.unique_ids
+    metadata2 = CORE.unique_ids[("", "sensor", fnv1_hash("humidity"))]
     assert metadata2["name"] == "Humidity"
 
     # Duplicate entity should fail
@@ -360,6 +537,34 @@ def test_entity_duplicate_validator() -> None:
         validator(config3)
 
 
+def test_entity_duplicate_validator_hash_collision() -> None:
+    """Test that two different object_ids with the same FNV-1 hash are rejected."""
+    # Brute-forced FNV-1 32-bit collision pair; both object_ids hash to 0xe95747e4
+    name_a = "Sensor aooxzi"
+    name_b = "Sensor baraia"
+    object_id_a = sanitize(snake_case(name_a))
+    object_id_b = sanitize(snake_case(name_b))
+    assert object_id_a != object_id_b
+    assert fnv1_hash(object_id_a) == fnv1_hash(object_id_b)
+
+    validator = entity_duplicate_validator("sensor")
+
+    config1 = {CONF_NAME: name_a}
+    validated1 = validator(config1)
+    assert validated1 == config1
+
+    config2 = {CONF_NAME: name_b}
+    with pytest.raises(
+        Invalid,
+        match=re.compile(
+            r"Duplicate sensor entity with name 'Sensor baraia' found.*"
+            r"produce the same entity key hash \(0xe95747e4\)",
+            re.DOTALL,
+        ),
+    ):
+        validator(config2)
+
+
 def test_entity_duplicate_validator_with_devices() -> None:
     """Test entity_duplicate_validator with devices."""
     # Create validator for sensor platform
@@ -370,19 +575,18 @@ def test_entity_duplicate_validator_with_devices() -> None:
     device2 = ID("device2", type="Device")
 
     # Same name on different devices should pass
-    name_hash = fnv1_hash_name("Temperature")
     config1 = {CONF_NAME: "Temperature", CONF_DEVICE_ID: device1}
     validated1 = validator(config1)
     assert validated1 == config1
-    assert ("device1", "sensor", name_hash) in CORE.unique_ids
-    metadata1 = CORE.unique_ids[("device1", "sensor", name_hash)]
+    assert ("device1", "sensor", fnv1_hash("temperature")) in CORE.unique_ids
+    metadata1 = CORE.unique_ids[("device1", "sensor", fnv1_hash("temperature"))]
     assert metadata1["device_id"] == "device1"
 
     config2 = {CONF_NAME: "Temperature", CONF_DEVICE_ID: device2}
     validated2 = validator(config2)
     assert validated2 == config2
-    assert ("device2", "sensor", name_hash) in CORE.unique_ids
-    metadata2 = CORE.unique_ids[("device2", "sensor", name_hash)]
+    assert ("device2", "sensor", fnv1_hash("temperature")) in CORE.unique_ids
+    metadata2 = CORE.unique_ids[("device2", "sensor", fnv1_hash("temperature"))]
     assert metadata2["device_id"] == "device2"
 
     # Duplicate on same device should fail
@@ -434,33 +638,6 @@ def test_entity_different_platforms_yaml_validation(
     assert result is not None
 
 
-def test_object_id_conflict_mqtt_yaml_validation(
-    yaml_file: Callable[[str], str], capsys: pytest.CaptureFixture[str]
-) -> None:
-    """Test that names sanitizing to the same object_id fail when mqtt is configured."""
-    result = load_config_from_fixture(
-        yaml_file, "object_id_conflict_mqtt.yaml", FIXTURES_DIR
-    )
-    assert result is None
-
-    captured = capsys.readouterr()
-    assert (
-        "mqtt builds default topics and discovery topics from the entity object_id"
-        in captured.out
-    )
-
-
-def test_object_id_conflict_without_mqtt_yaml_validation(
-    yaml_file: Callable[[str], str],
-) -> None:
-    """Test that names sanitizing to the same object_id pass without mqtt/prometheus."""
-    result = load_config_from_fixture(
-        yaml_file, "object_id_conflict_no_mqtt.yaml", FIXTURES_DIR
-    )
-    # This should succeed
-    assert result is not None
-
-
 def test_entity_duplicate_validator_error_message() -> None:
     """Test that duplicate entity error messages include helpful metadata."""
     # Create validator for sensor platform
@@ -519,8 +696,7 @@ def test_entity_duplicate_validator_internal_entities() -> None:
     validated1 = validator(config1)
     assert validated1 == config1
     # New format includes device_id (empty string for main device)
-    temperature_key = ("", "sensor", fnv1_hash_name("Temperature"))
-    assert temperature_key in CORE.unique_ids
+    assert ("", "sensor", fnv1_hash("temperature")) in CORE.unique_ids
 
     # Internal entity with same name should pass (not added to unique_ids)
     config2 = {CONF_NAME: "Temperature", CONF_INTERNAL: True}
@@ -528,7 +704,9 @@ def test_entity_duplicate_validator_internal_entities() -> None:
     assert validated2 == config2
     # Internal entity should not be added to unique_ids
     # Count how many times the key appears (should still be 1)
-    count = sum(1 for k in CORE.unique_ids if k == temperature_key)
+    count = sum(
+        1 for k in CORE.unique_ids if k == ("", "sensor", fnv1_hash("temperature"))
+    )
     assert count == 1
 
     # Another internal entity with same name should also pass
@@ -536,7 +714,9 @@ def test_entity_duplicate_validator_internal_entities() -> None:
     validated3 = validator(config3)
     assert validated3 == config3
     # Still only one entry in unique_ids (from the non-internal entity)
-    count = sum(1 for k in CORE.unique_ids if k == temperature_key)
+    count = sum(
+        1 for k in CORE.unique_ids if k == ("", "sensor", fnv1_hash("temperature"))
+    )
     assert count == 1
 
     # Non-internal entity with same name should fail
@@ -564,148 +744,30 @@ def test_empty_or_null_device_id_on_entity() -> None:
 
 
 def test_entity_duplicate_validator_non_ascii_names() -> None:
-    """Test that distinct non-ASCII names no longer collide.
-
-    These names used to be rejected because both sanitize to only underscores;
-    the entity key now hashes the raw name so they stay distinct.
-    """
+    """Test that non-ASCII names show helpful error messages."""
     # Create validator for binary_sensor platform
     validator = entity_duplicate_validator("binary_sensor")
 
-    # Both Russian sensors should pass even though they sanitize identically
+    # First Russian sensor should pass
     config1 = {CONF_NAME: "Датчик открытия основного крана"}
     validated1 = validator(config1)
     assert validated1 == config1
 
+    # Second Russian sensor with different text but same ASCII conversion should fail
     config2 = {CONF_NAME: "Датчик закрытия основного крана"}
-    validated2 = validator(config2)
-    assert validated2 == config2
-
-    # An exact duplicate still fails
-    config3 = {CONF_NAME: "Датчик открытия основного крана"}
-    with pytest.raises(
-        Invalid,
-        match=r"Duplicate binary_sensor entity with name 'Датчик открытия основного крана' found",
-    ):
-        validator(config3)
-
-
-def test_entity_duplicate_validator_hash_collision() -> None:
-    """Test that two different names with the same FNV-1 hash are rejected."""
-    # Brute-forced FNV-1 32-bit collision pair; both hash to 0x0ee5ff7b
-    name_a = "Sensor m2CZ"
-    name_b = "Sensor qCaa"
-    assert name_a != name_b
-    assert fnv1_hash_name(name_a) == fnv1_hash_name(name_b)
-
-    validator = entity_duplicate_validator("sensor")
-
-    config1 = {CONF_NAME: name_a}
-    validated1 = validator(config1)
-    assert validated1 == config1
-
-    config2 = {CONF_NAME: name_b}
     with pytest.raises(
         Invalid,
         match=re.compile(
-            rf"Duplicate sensor entity with name '{name_b}' found.*"
-            rf"The names '{name_b}' and '{name_a}' produce the.*"
-            r"same entity key hash \(0x0ee5ff7b\).*"
-            r"To fix: Rename one of the entities",
+            r"Duplicate binary_sensor entity with name 'Датчик закрытия основного крана' found.*"
+            r"Original names: 'Датчик закрытия основного крана' and 'Датчик открытия основного крана'.*"
+            r"Both convert to ASCII ID: '_______________________________'.*"
+            r"To fix: Add unique ASCII characters \(e\.g\., '1', '2', or 'A', 'B'\)",
             re.DOTALL,
         ),
     ):
         validator(config2)
 
 
-def test_object_id_conflicts_rejected_by_component_validator() -> None:
-    """Test that object_id conflicts pass entity validation but fail for mqtt/prometheus."""
-    validator = entity_duplicate_validator("sensor")
-
-    # Both names validate fine in general (distinct raw names, distinct keys)
-    validator({CONF_NAME: "Датчик открытия"})
-    validator({CONF_NAME: "Датчик закрытия"})
-
-    # A component that addresses entities by object_id must reject the config
-    component_validator = validate_no_object_id_conflicts(
-        "mqtt builds default topics from the entity object_id"
-    )
-    with pytest.raises(
-        Invalid,
-        match=re.compile(
-            r"mqtt builds default topics from the entity object_id.*"
-            r"sensor entities 'Датчик открытия', 'Датчик закрытия' "
-            r"share the object_id '_______________'.*"
-            r"To fix: Add unique ASCII characters",
-            re.DOTALL,
-        ),
-    ):
-        component_validator({})
-
-
-def test_object_id_conflicts_skipped_in_testing_mode() -> None:
-    """Test that testing_mode skips the conflict check, as used for grouped testing."""
-    validator = entity_duplicate_validator("sensor")
-    validator({CONF_NAME: "Датчик открытия"})
-    validator({CONF_NAME: "Датчик закрытия"})
-
-    component_validator = validate_no_object_id_conflicts(
-        "mqtt builds default topics from the entity object_id"
-    )
-    CORE.testing_mode = True
-    try:
-        config: dict = {}
-        assert component_validator(config) is config
-    finally:
-        CORE.testing_mode = False
-
-
-def test_object_id_conflicts_none_recorded() -> None:
-    """Test that distinct object_ids produce no conflicts."""
-    validator = entity_duplicate_validator("sensor")
-    validator({CONF_NAME: "Temperature"})
-    validator({CONF_NAME: "Humidity"})
-
-    component_validator = validate_no_object_id_conflicts(
-        "mqtt builds default topics from the entity object_id"
-    )
-    config: dict = {}
-    assert component_validator(config) is config
-
-
-def test_object_id_conflicts_device_scoped() -> None:
-    """Test that the object_id conflict check is scoped per device.
-
-    Same-named entities on different sub-devices were accepted before entity keys
-    moved to raw names, so the check keeps that scope; conflicts within one device
-    are still reported with the device named in the message.
-    """
-    validator = entity_duplicate_validator("sensor")
-    validator({CONF_NAME: "Temperature", CONF_DEVICE_ID: ID("device1", type="Device")})
-    validator({CONF_NAME: "Temperature", CONF_DEVICE_ID: ID("device2", type="Device")})
-
-    component_validator = validate_no_object_id_conflicts(
-        "prometheus builds metric labels from the entity object_id"
-    )
-    config: dict = {}
-    assert component_validator(config) is config
-
-    # Two names sanitizing identically on the same sub-device still conflict
-    validator(
-        {CONF_NAME: "Датчик открытия", CONF_DEVICE_ID: ID("device1", type="Device")}
-    )
-    validator(
-        {CONF_NAME: "Датчик закрытия", CONF_DEVICE_ID: ID("device1", type="Device")}
-    )
-    with pytest.raises(
-        Invalid,
-        match=re.compile(
-            r"prometheus builds metric labels.*on device 'device1'", re.DOTALL
-        ),
-    ):
-        component_validator({})
-
-
 def test_entity_duplicate_validator_same_name_no_enhanced_message() -> None:
     """Test that identical names don't show the enhanced message."""
     # Create validator for sensor platform
@@ -763,7 +825,7 @@ async def test_setup_entity_empty_name_with_device(
 
     # For empty-name entities, Python stores hash 0 - C++ calculates hash at runtime
     assert config.get("_entity_name") == ""
-    assert config.get("_entity_key") == 0
+    assert config.get("_entity_object_id_hash") == 0
 
 
 @pytest.mark.asyncio
@@ -792,7 +854,7 @@ async def test_setup_entity_empty_name_with_mac_suffix(
 
     # For empty-name entities, Python stores hash 0 - C++ calculates hash at runtime
     assert config.get("_entity_name") == ""
-    assert config.get("_entity_key") == 0
+    assert config.get("_entity_object_id_hash") == 0
 
 
 @pytest.mark.asyncio
@@ -822,7 +884,7 @@ async def test_setup_entity_empty_name_with_mac_suffix_no_friendly_name(
 
     # For empty-name entities, Python stores hash 0 - C++ calculates hash at runtime
     assert config.get("_entity_name") == ""
-    assert config.get("_entity_key") == 0
+    assert config.get("_entity_object_id_hash") == 0
 
 
 @pytest.mark.asyncio
@@ -853,7 +915,7 @@ async def test_setup_entity_empty_name_no_mac_suffix_no_friendly_name(
 
     # For empty-name entities, Python stores hash 0 - C++ calculates hash at runtime
     assert config.get("_entity_name") == ""
-    assert config.get("_entity_key") == 0
+    assert config.get("_entity_object_id_hash") == 0
 
 
 def test_register_string_overflow() -> None:

tests/unit_tests/fixtures/core/entity_helpers/object_id_conflict_mqtt.yaml

@@ -1,22 +0,0 @@
-esphome:
-  name: test-object-id-conflict
-
-esp32:
-  board: esp32dev
-
-wifi:
-  ssid: MySSID
-  password: password1
-
-mqtt:
-  broker: test.mosquitto.org
-
-sensor:
-  # Distinct raw names are fine in general, but both sanitize to the same
-  # object_id, which MQTT still uses to build default topics - should fail
-  - platform: template
-    name: "Датчик открытия"
-    lambda: return 21.0;
-  - platform: template
-    name: "Датчик закрытия"
-    lambda: return 22.0;

tests/unit_tests/fixtures/core/entity_helpers/object_id_conflict_no_mqtt.yaml

@@ -1,15 +0,0 @@
-esphome:
-  name: test-object-id-ok
-
-esp32:
-  board: esp32dev
-
-sensor:
-  # Distinct raw names that sanitize to the same object_id are allowed when no
-  # component addresses entities by object_id (no mqtt or prometheus configured)
-  - platform: template
-    name: "Датчик открытия"
-    lambda: return 21.0;
-  - platform: template
-    name: "Датчик закрытия"
-    lambda: return 22.0;

tests/unit_tests/fixtures/lazy_imports/_storage.py

@@ -1,10 +1,15 @@
 """Shared storage-sidecar factory for the lazy-import fixture scripts."""
 
+from pathlib import Path
+
 from esphome.storage_json import StorageJSON
 
 
 def make_storage() -> StorageJSON:
-    """A minimal post-compile esp32 sidecar the upload/logs fast path accepts."""
+    """A minimal post-compile esp32 sidecar the upload/logs fast path accepts.
+
+    build_path must be set: the fast path rejects sidecars without one.
+    """
     return StorageJSON(
         storage_version=1,
         name="test",
@@ -15,8 +20,8 @@ def make_storage() -> StorageJSON:
         address="1.2.3.4",
         web_port=None,
         target_platform="ESP32S3",
-        build_path=None,
-        firmware_bin_path=None,
+        build_path=Path("/build/test"),
+        firmware_bin_path=Path("/build/test/firmware.bin"),
         loaded_integrations=set(),
         loaded_platforms=set(),
         no_mdns=False,

tests/unit_tests/test_api_client.py

@@ -56,7 +56,7 @@ async def test_async_run_logs_full_flow(caplog) -> None:
 
     with (
         patch.object(api_client, "async_run", mock_run),
-        patch.object(api_client, "APIClient") as mock_client,
+        patch.object(api_client, "APIClient", autospec=True) as mock_client,
         patch.object(api_client, "safe_print", printed.append),
     ):
         task = asyncio.get_running_loop().create_task(
@@ -163,3 +163,324 @@ async def test_async_run_logs_passes_deep_sleep(
         await api_client.async_run_logs(config, ["1.2.3.4"])
 
     assert mock_run.call_args.kwargs["deep_sleep"] is expected_deep_sleep
+
+
+@pytest.mark.asyncio
+async def test_async_run_logs_mqtt_resolver_feeds_addresses(caplog) -> None:
+    """Addresses discovered via MQTT are fed into the running client."""
+    caplog.set_level("INFO", logger="esphome.api_client")
+    CORE.data[KEY_CORE] = {KEY_TARGET_PLATFORM: "esp32"}
+    config = {"esphome": {"name": "test"}, "api": {CONF_PORT: 6053}}
+
+    stop = AsyncMock()
+    fed = asyncio.Event()
+
+    def resolver(stop_event):
+        return ["10.0.0.9", "10.0.0.10"]
+
+    with (
+        patch.object(api_client, "async_run", AsyncMock(return_value=stop)),
+        patch.object(api_client, "APIClient", autospec=True) as mock_client,
+    ):
+        mock_client.return_value.add_addresses.side_effect = lambda addrs: (
+            fed.set() or True
+        )
+        task = asyncio.get_running_loop().create_task(
+            api_client.async_run_logs(config, ["1.2.3.4"], mqtt_resolver=resolver)
+        )
+        async with asyncio.timeout(1):
+            await fed.wait()
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+
+    mock_client.return_value.add_addresses.assert_called_once_with(
+        ["10.0.0.9", "10.0.0.10"]
+    )
+    assert "Discovered address(es) via MQTT" in caplog.text
+    stop.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_async_run_logs_mqtt_resolver_no_addresses_keeps_running() -> None:
+    """A resolver returning nothing (failed lookup) leaves the session running."""
+    import threading
+
+    CORE.data[KEY_CORE] = {KEY_TARGET_PLATFORM: "esp32"}
+    config = {"esphome": {"name": "test"}, "api": {CONF_PORT: 6053}}
+
+    stop = AsyncMock()
+    resolver_ran = threading.Event()
+
+    def resolver(stop_event):
+        # The resolver owns failure handling; a failed lookup returns []
+        resolver_ran.set()
+        return []
+
+    with (
+        patch.object(api_client, "async_run", AsyncMock(return_value=stop)),
+        patch.object(api_client, "APIClient", autospec=True) as mock_client,
+    ):
+        task = asyncio.get_running_loop().create_task(
+            api_client.async_run_logs(config, ["1.2.3.4"], mqtt_resolver=resolver)
+        )
+        await asyncio.to_thread(resolver_ran.wait, 1)
+        await asyncio.sleep(0)
+        assert not task.done()
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+
+    mock_client.return_value.add_addresses.assert_not_called()
+    stop.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_async_run_logs_mqtt_resolver_stopped_on_teardown() -> None:
+    """Teardown sets the resolver's stop event so the thread exits promptly."""
+    import threading
+
+    CORE.data[KEY_CORE] = {KEY_TARGET_PLATFORM: "esp32"}
+    config = {"esphome": {"name": "test"}, "api": {CONF_PORT: 6053}}
+
+    stop = AsyncMock()
+    captured_event: threading.Event | None = None
+    resolver_started = threading.Event()
+
+    def resolver(stop_event):
+        nonlocal captured_event
+        captured_event = stop_event
+        resolver_started.set()
+        # Simulate a slow broker lookup that only ends via the stop event.
+        stop_event.wait(timeout=5)
+        return []
+
+    with (
+        patch.object(api_client, "async_run", AsyncMock(return_value=stop)),
+        patch.object(api_client, "APIClient", autospec=True),
+    ):
+        task = asyncio.get_running_loop().create_task(
+            api_client.async_run_logs(config, ["1.2.3.4"], mqtt_resolver=resolver)
+        )
+        await asyncio.to_thread(resolver_started.wait, 1)
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+
+    assert captured_event is not None
+    assert captured_event.is_set()
+    stop.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_async_run_logs_mqtt_resolver_crash_still_stops_cleanly(caplog) -> None:
+    """A resolver raising unexpectedly must not skip stop() at teardown."""
+    import threading
+
+    CORE.data[KEY_CORE] = {KEY_TARGET_PLATFORM: "esp32"}
+    config = {"esphome": {"name": "test"}, "api": {CONF_PORT: 6053}}
+
+    stop = AsyncMock()
+    resolver_ran = threading.Event()
+
+    def resolver(stop_event):
+        resolver_ran.set()
+        raise RuntimeError("resolver blew up")
+
+    with (
+        patch.object(api_client, "async_run", AsyncMock(return_value=stop)),
+        patch.object(api_client, "APIClient", autospec=True),
+    ):
+        task = asyncio.get_running_loop().create_task(
+            api_client.async_run_logs(config, ["1.2.3.4"], mqtt_resolver=resolver)
+        )
+        await asyncio.to_thread(resolver_ran.wait, 1)
+        await asyncio.sleep(0.05)
+        assert not task.done()
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+
+    assert "MQTT address discovery failed" in caplog.text
+    stop.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_async_run_logs_connect_cancels_mqtt_discovery() -> None:
+    """A successful connection stops the in-flight broker lookup."""
+    import threading
+
+    CORE.data[KEY_CORE] = {KEY_TARGET_PLATFORM: "esp32"}
+    config = {"esphome": {"name": "test"}, "api": {CONF_PORT: 6053}}
+
+    stop = AsyncMock()
+    captured_event: threading.Event | None = None
+    resolver_started = threading.Event()
+
+    def resolver(stop_event):
+        nonlocal captured_event
+        captured_event = stop_event
+        resolver_started.set()
+        stop_event.wait(timeout=5)
+        return []
+
+    with (
+        patch.object(api_client, "async_run", AsyncMock(return_value=stop)) as mock_run,
+        patch.object(api_client, "APIClient", autospec=True) as mock_client,
+    ):
+        task = asyncio.get_running_loop().create_task(
+            api_client.async_run_logs(config, ["1.2.3.4"], mqtt_resolver=resolver)
+        )
+        await asyncio.to_thread(resolver_started.wait, 1)
+
+        # The runner reports a successful connection
+        on_connect = mock_run.call_args.kwargs["on_connect"]
+        on_connect()
+        await asyncio.sleep(0.05)
+
+        assert captured_event is not None
+        assert captured_event.is_set()
+        assert not task.done()
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+
+    mock_client.return_value.add_addresses.assert_not_called()
+    stop.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_async_run_logs_connect_before_discovery_skips_lookup() -> None:
+    """A connection during async_run startup prevents the lookup from starting."""
+    CORE.data[KEY_CORE] = {KEY_TARGET_PLATFORM: "esp32"}
+    config = {"esphome": {"name": "test"}, "api": {CONF_PORT: 6053}}
+
+    stop = AsyncMock()
+    resolver = Mock(name="resolver")
+
+    async def fake_async_run(*args, **kwargs):
+        # Connection succeeds before async_run even returns
+        kwargs["on_connect"]()
+        return stop
+
+    with (
+        patch.object(api_client, "async_run", AsyncMock(side_effect=fake_async_run)),
+        patch.object(api_client, "APIClient", autospec=True),
+    ):
+        task = asyncio.get_running_loop().create_task(
+            api_client.async_run_logs(config, ["1.2.3.4"], mqtt_resolver=resolver)
+        )
+        await asyncio.sleep(0.05)
+        assert not task.done()
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+
+    resolver.assert_not_called()
+    stop.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_async_run_logs_mqtt_resolver_duplicate_addresses_logged(caplog) -> None:
+    """A discovery the client rejects as already known leaves a debug trace."""
+    import threading
+
+    caplog.set_level("DEBUG", logger="esphome.api_client")
+    CORE.data[KEY_CORE] = {KEY_TARGET_PLATFORM: "esp32"}
+    config = {"esphome": {"name": "test"}, "api": {CONF_PORT: 6053}}
+
+    stop = AsyncMock()
+    fed = threading.Event()
+
+    def resolver(stop_event):
+        return ["1.2.3.4"]
+
+    with (
+        patch.object(api_client, "async_run", AsyncMock(return_value=stop)),
+        patch.object(api_client, "APIClient", autospec=True) as mock_client,
+    ):
+        mock_client.return_value.add_addresses.side_effect = lambda addrs: (
+            fed.set() or False
+        )
+        task = asyncio.get_running_loop().create_task(
+            api_client.async_run_logs(config, ["1.2.3.4"], mqtt_resolver=resolver)
+        )
+        await asyncio.to_thread(fed.wait, 1)
+        await asyncio.sleep(0.05)
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+
+    mock_client.return_value.add_addresses.assert_called_once_with(["1.2.3.4"])
+    assert "MQTT-discovered address(es) already known: 1.2.3.4" in caplog.text
+    assert "Discovered address(es) via MQTT" not in caplog.text
+    stop.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_async_run_logs_base_exception_escape_logged_at_teardown(caplog) -> None:
+    """A BaseException escaping the worker is reported, and stop() still runs."""
+    import threading
+
+    CORE.data[KEY_CORE] = {KEY_TARGET_PLATFORM: "esp32"}
+    config = {"esphome": {"name": "test"}, "api": {CONF_PORT: 6053}}
+
+    stop = AsyncMock()
+    resolver_ran = threading.Event()
+
+    class WorkerEscape(BaseException):
+        """Not an Exception, so the task-level guard must not catch it."""
+
+    def resolver(stop_event):
+        resolver_ran.set()
+        raise WorkerEscape("worker bailed")
+
+    with (
+        patch.object(api_client, "async_run", AsyncMock(return_value=stop)),
+        patch.object(api_client, "APIClient", autospec=True),
+    ):
+        task = asyncio.get_running_loop().create_task(
+            api_client.async_run_logs(config, ["1.2.3.4"], mqtt_resolver=resolver)
+        )
+        await asyncio.to_thread(resolver_ran.wait, 1)
+        await asyncio.sleep(0.05)
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+
+    assert "MQTT address discovery failed" in caplog.text
+    stop.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_async_run_logs_stubborn_worker_cancelled_at_teardown() -> None:
+    """A worker that ignores the stop event is cancelled after the grace period."""
+    import threading
+
+    CORE.data[KEY_CORE] = {KEY_TARGET_PLATFORM: "esp32"}
+    config = {"esphome": {"name": "test"}, "api": {CONF_PORT: 6053}}
+
+    stop = AsyncMock()
+    resolver_ran = threading.Event()
+    release = threading.Event()
+
+    def resolver(stop_event):
+        resolver_ran.set()
+        # Ignore stop_event entirely; only the test releases us
+        release.wait(timeout=10)
+        return []
+
+    with (
+        patch.object(api_client, "async_run", AsyncMock(return_value=stop)),
+        patch.object(api_client, "APIClient", autospec=True),
+    ):
+        task = asyncio.get_running_loop().create_task(
+            api_client.async_run_logs(config, ["1.2.3.4"], mqtt_resolver=resolver)
+        )
+        await asyncio.to_thread(resolver_ran.wait, 1)
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+        release.set()
+
+    stop.assert_awaited_once()

tests/unit_tests/test_compiled_config.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from contextlib import contextmanager
 from ipaddress import IPv4Address, IPv4Network
 import json
 import os
@@ -19,6 +20,7 @@ from esphome.compiled_config import (
     compiled_config_path,
     load_compiled_config,
     save_compiled_config,
+    save_compiled_config_and_sidecar,
 )
 from esphome.const import (
     CONF_API,
@@ -31,7 +33,16 @@ from esphome.const import (
     KEY_VARIANT,
     Toolchain,
 )
-from esphome.core import CORE, ID, HexInt, Lambda, MACAddress, TimePeriodMilliseconds
+from esphome.core import (
+    CORE,
+    ID,
+    EsphomeError,
+    HexInt,
+    Lambda,
+    MACAddress,
+    TimePeriodMilliseconds,
+)
+from esphome.storage_json import StorageJSON
 from esphome.util import OrderedDict
 
 _VALIDATED_CONFIG = {
@@ -54,8 +65,9 @@ def _cache_body(config: dict | None = None) -> str:
 def _write_storage(
     storage_path: Path,
     *,
-    esp_platform: str = "ESP32",
+    esp_platform: str | None = "ESP32",
     core_platform: str | None = "esp32",
+    build_path: str | None = "/build/lite_test",
 ) -> None:
     """Write a vanilla StorageJSON sidecar for the cache tests."""
     storage_path.parent.mkdir(parents=True, exist_ok=True)
@@ -69,7 +81,7 @@ def _write_storage(
         "address": "192.168.1.42",
         "web_port": None,
         "esp_platform": esp_platform,
-        "build_path": "/build/lite_test",
+        "build_path": build_path,
         "firmware_bin_path": "/build/lite_test/firmware.bin",
         "loaded_integrations": ["api", "logger", "ota", "wifi"],
         "loaded_platforms": [],
@@ -359,31 +371,262 @@ def test_run_esphome_upload_and_logs_fall_back_when_no_cache(
     mock_read.assert_called_once()
 
 
-def test_run_esphome_upload_does_not_refresh_cache_without_sidecar(
-    tmp_path: Path,
-) -> None:
-    """Without a StorageJSON sidecar (no compile has run), the fallback
-    skips the cache write -- load_compiled_config requires the sidecar,
-    so writing the rendered (secret-resolved) config would be inert and
-    leak secrets to disk for nothing."""
+def _storage_fixture(tmp_path: Path) -> StorageJSON:
+    """A loaded StorageJSON instance matching _write_storage's contents."""
+    fixture = tmp_path / "fixture_storage.json"
+    _write_storage(fixture)
+    return StorageJSON.load(fixture)
+
+
+def _bare_yaml(tmp_path: Path) -> Path:
+    """A minimal YAML with CORE.config_path pointed at it."""
     yaml_path = tmp_path / "lite_test.yaml"
     yaml_path.write_text("esphome:\n  name: lite_test\n")
     CORE.config_path = yaml_path
+    return yaml_path
 
+
+@contextmanager
+def _fallback_run(command: str = "upload", **from_core_kwargs) -> Any:
+    """Patch the fallback path's collaborators for a run_esphome call.
+
+    Without kwargs, from_esphome_core stays real (yielded mock is None).
+    """
     with (
         patch(
             "esphome.config.read_config",
             return_value={"esphome": {"name": "lite_test"}},
-        ),
-        patch("esphome.compiled_config.save_compiled_config") as mock_save,
+        ) as mock_read,
         patch.dict(
             "esphome.__main__.POST_CONFIG_ACTIONS",
-            {"upload": lambda args, config: 0},
+            {command: lambda args, config: 0},
         ),
     ):
-        run_esphome(["esphome", "upload", str(yaml_path)])
+        if not from_core_kwargs:
+            yield mock_read, None
+            return
+        with patch.object(
+            StorageJSON, "from_esphome_core", **from_core_kwargs
+        ) as mock_from_core:
+            yield mock_read, mock_from_core
+
+
+@pytest.mark.parametrize("command", ["upload", "logs"])
+def test_run_esphome_fallback_writes_sidecar_and_cache_without_sidecar(
+    tmp_path: Path, command: str
+) -> None:
+    """A never-compiled config caches on its first upload/logs run: the
+    fallback writes the StorageJSON sidecar itself (load_compiled_config
+    needs it), so the second run hits the fast path."""
+    yaml_path = _bare_yaml(tmp_path)
+    storage_dir = tmp_path / ".esphome" / "storage"
+
+    with _fallback_run(command, return_value=_storage_fixture(tmp_path)) as (
+        mock_read,
+        mock_from_core,
+    ):
+        assert run_esphome(["esphome", command, str(yaml_path)]) == 0
+        mock_from_core.assert_called_once()
+        assert (storage_dir / "lite_test.yaml.validated.json").exists()
+        storage = StorageJSON.load(storage_dir / "lite_test.yaml.json")
+        assert storage is not None
+        # No compile happened, so the sidecar must not claim one.
+        assert mock_from_core.call_args.kwargs == {"claim_build": False}
+
+        # The second run loads the cache instead of re-validating.
+        assert run_esphome(["esphome", command, str(yaml_path)]) == 0
+        mock_read.assert_called_once()
+
+
+# as_dict serialized unset paths as str(None) until 2026.9; files
+# written by those wizards are still on disk.
+_WIZARD_SIDECAR_CASES = pytest.mark.parametrize(
+    "wizard_kwargs",
+    [
+        {"esp_platform": None, "core_platform": None, "build_path": None},
+        {"build_path": None},
+        {"build_path": "None"},
+    ],
+    ids=["legacy_wizard", "modern_wizard", "none_string_wizard"],
+)
+
+
+def _prime_core(tmp_path: Path) -> None:
+    """Set the post-validation CORE state from_esphome_core reads."""
+    CORE.name = "lite_test"
+    CORE.build_path = tmp_path / "build" / "lite_test"
+    CORE.data[KEY_CORE] = {
+        KEY_TARGET_PLATFORM: "esp8266",
+        KEY_TARGET_FRAMEWORK: "arduino",
+    }
+
+
+@_WIZARD_SIDECAR_CASES
+def test_run_esphome_fallback_completes_wizard_sidecar(
+    tmp_path: Path, wizard_kwargs: dict[str, Any]
+) -> None:
+    """A wizard-written sidecar can't drive the fast path (no build_path;
+    older wizards also no platform fields); the fallback rewrites it from
+    CORE so the cache loads on the next run."""
+    yaml_path = _bare_yaml(tmp_path)
+    storage_dir = tmp_path / ".esphome" / "storage"
+    _write_storage(storage_dir / "lite_test.yaml.json", **wizard_kwargs)
+
+    with _fallback_run(return_value=_storage_fixture(tmp_path)) as (_, mock_from_core):
+        assert run_esphome(["esphome", "upload", str(yaml_path)]) == 0
+
+    mock_from_core.assert_called_once()
+    storage = StorageJSON.load(storage_dir / "lite_test.yaml.json")
+    assert storage is not None and storage.core_platform == "esp32"
+    # What the wizard recorded about a build (nothing, or a real one)
+    # carries through instead of being stamped with this run's values.
+    assert storage.esphome_version == "2026.1.0"
+    assert load_compiled_config(yaml_path) is not None
+
+
+def test_run_esphome_fallback_skips_cache_when_sidecar_write_fails(
+    tmp_path: Path,
+) -> None:
+    """A failed sidecar write is non-fatal and skips the cache save too:
+    without the sidecar the cache could never be loaded back, so writing
+    it would only leave resolved secrets on disk."""
+    yaml_path = _bare_yaml(tmp_path)
+
+    with (
+        _fallback_run(side_effect=RuntimeError("boom")),
+        patch("esphome.compiled_config.save_compiled_config") as mock_save,
+    ):
+        assert run_esphome(["esphome", "upload", str(yaml_path)]) == 0
 
     mock_save.assert_not_called()
+    assert not (tmp_path / ".esphome" / "storage" / "lite_test.yaml.json").exists()
+
+
+def test_run_esphome_fallback_write_failure_takes_io_branch(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """StorageJSON.save raises EsphomeError (write_file wraps OSError into
+    it), which must land in the plain I/O warning, not the traceback
+    branch for structural bugs."""
+    yaml_path = _bare_yaml(tmp_path)
+
+    with (
+        _fallback_run(return_value=_storage_fixture(tmp_path)),
+        patch.object(StorageJSON, "save", side_effect=EsphomeError("boom")),
+        patch("esphome.compiled_config.save_compiled_config") as mock_save,
+        caplog.at_level("WARNING", logger="esphome.compiled_config"),
+    ):
+        assert run_esphome(["esphome", "upload", str(yaml_path)]) == 0
+
+    mock_save.assert_not_called()
+    assert "Could not refresh the storage sidecar" in caplog.text
+    assert "Unexpected error" not in caplog.text
+
+
+def test_run_esphome_fallback_leaves_unreadable_sidecar_alone(tmp_path: Path) -> None:
+    """A present-but-corrupt sidecar is not overwritten: it may hold a real
+    build's metadata, and replacing it would suppress the next compile's
+    clean of a possibly incoherent build tree. The cache save is skipped."""
+    yaml_path = _bare_yaml(tmp_path)
+    storage_dir = tmp_path / ".esphome" / "storage"
+    sidecar = storage_dir / "lite_test.yaml.json"
+    sidecar.parent.mkdir(parents=True, exist_ok=True)
+    sidecar.write_text("{truncated", encoding="utf-8")
+
+    with _fallback_run(return_value=None) as (_, mock_from_core):
+        assert run_esphome(["esphome", "upload", str(yaml_path)]) == 0
+
+    mock_from_core.assert_not_called()
+    assert sidecar.read_text(encoding="utf-8") == "{truncated"
+    assert not (storage_dir / "lite_test.yaml.validated.json").exists()
+
+
+def test_run_esphome_fallback_skips_cache_when_rebuilt_sidecar_incomplete(
+    tmp_path: Path,
+) -> None:
+    """If the rebuilt sidecar would still be incomplete, nothing is written:
+    the cache could never be loaded back, so saving it would only rewrite
+    resolved secrets on every run."""
+    yaml_path = _bare_yaml(tmp_path)
+    storage_dir = tmp_path / ".esphome" / "storage"
+
+    incomplete = tmp_path / "incomplete_storage.json"
+    _write_storage(incomplete, build_path=None)
+
+    with _fallback_run(return_value=StorageJSON.load(incomplete)):
+        assert run_esphome(["esphome", "upload", str(yaml_path)]) == 0
+
+    assert not (storage_dir / "lite_test.yaml.json").exists()
+    assert not (storage_dir / "lite_test.yaml.validated.json").exists()
+
+
+def test_run_esphome_fallback_sidecar_records_platformio_toolchain(
+    tmp_path: Path,
+) -> None:
+    """The toolchain fallback runs before the sidecar write, so platforms
+    whose validators leave CORE.toolchain unset record the same
+    "platformio" a compile writes, not null."""
+    yaml_path = _bare_yaml(tmp_path)
+    _prime_core(tmp_path)
+    assert CORE.toolchain is None
+
+    with _fallback_run():
+        assert run_esphome(["esphome", "upload", str(yaml_path)]) == 0
+
+    storage = StorageJSON.load(
+        tmp_path / ".esphome" / "storage" / "lite_test.yaml.json"
+    )
+    assert storage is not None
+    assert storage.toolchain == "platformio"
+
+
+@pytest.mark.parametrize("existing_sidecar", [None, "wizard"])
+def test_run_esphome_fallback_skips_sidecar_when_build_tree_exists(
+    tmp_path: Path, existing_sidecar: str | None
+) -> None:
+    """An existing build tree with a missing or wizard-only sidecar keeps
+    it that way: the mismatch is what makes the next compile wipe the
+    unknown tree, so the fallback writes nothing and skips the cache."""
+    yaml_path = _bare_yaml(tmp_path)
+    _prime_core(tmp_path)
+    CORE.build_path.mkdir(parents=True)
+    storage_dir = tmp_path / ".esphome" / "storage"
+    if existing_sidecar == "wizard":
+        _write_storage(storage_dir / "lite_test.yaml.json", build_path=None)
+        wizard_body = (storage_dir / "lite_test.yaml.json").read_text(encoding="utf-8")
+
+    with _fallback_run(return_value=_storage_fixture(tmp_path)) as (_, mock_from_core):
+        assert run_esphome(["esphome", "upload", str(yaml_path)]) == 0
+
+    mock_from_core.assert_not_called()
+    assert not (storage_dir / "lite_test.yaml.validated.json").exists()
+    if existing_sidecar == "wizard":
+        sidecar_body = (storage_dir / "lite_test.yaml.json").read_text(encoding="utf-8")
+        assert sidecar_body == wizard_body
+    else:
+        assert not (storage_dir / "lite_test.yaml.json").exists()
+
+
+def test_save_compiled_config_and_sidecar_builds_real_sidecar(tmp_path: Path) -> None:
+    """Drive the real from_esphome_core on the fallback path: the
+    post-validation CORE state yields a complete, loadable sidecar."""
+    yaml_path = _bare_yaml(tmp_path)
+    _prime_core(tmp_path)
+    CORE.config = {CONF_ESPHOME: {CONF_NAME: "lite_test"}}
+    CORE.toolchain = Toolchain.PLATFORMIO
+
+    save_compiled_config_and_sidecar(CORE.config)
+
+    storage = StorageJSON.load(
+        tmp_path / ".esphome" / "storage" / "lite_test.yaml.json"
+    )
+    assert storage is not None
+    assert storage.core_platform == "esp8266"
+    assert storage.build_path is not None
+    # No compile happened, so the sidecar must not claim one.
+    assert storage.esphome_version is None
+    assert storage.firmware_bin_path is None
+    assert load_compiled_config(yaml_path) is not None
 
 
 @pytest.mark.parametrize("command", ["upload", "logs"])
@@ -409,6 +652,7 @@ def test_run_esphome_upload_and_logs_refresh_cache_on_fallback(
         patch(
             "esphome.compiled_config.save_compiled_config", wraps=save_compiled_config
         ) as mock_save,
+        patch.object(StorageJSON, "from_esphome_core") as mock_from_core,
         patch.dict(
             "esphome.__main__.POST_CONFIG_ACTIONS",
             {command: lambda args, config: 0},
@@ -417,6 +661,8 @@ def test_run_esphome_upload_and_logs_refresh_cache_on_fallback(
         assert run_esphome(["esphome", command, str(yaml_path)]) == 0
 
     mock_save.assert_called_once_with(fresh_config)
+    # The compile-written sidecar is complete; the fallback leaves it alone.
+    mock_from_core.assert_not_called()
     # mtime is now newer than the source YAML, so a follow-up call hits
     # the fast path instead of repeating read_config.
     assert cache.stat().st_mtime >= yaml_path.stat().st_mtime
@@ -647,24 +893,15 @@ def test_int_keys_coerce_to_strings(primed_storage: Path) -> None:
     assert config["table"] == {"1": "a", "2": "b"}
 
 
-def test_load_compiled_config_rejects_wizard_only_sidecar(tmp_path: Path) -> None:
-    """A wizard-only sidecar (no compile -- no core_platform / target_platform)
-    can't drive upload/logs, so the fast path falls back."""
-    yaml_path = tmp_path / "lite_test.yaml"
-    yaml_path.write_text("esphome:\n  name: lite_test\n")
-    CORE.config_path = yaml_path
-
+@_WIZARD_SIDECAR_CASES
+def test_load_compiled_config_rejects_wizard_only_sidecar(
+    tmp_path: Path, wizard_kwargs: dict[str, Any]
+) -> None:
+    """A wizard-written sidecar (no build_path; older wizards also no
+    platform fields) can't drive upload/logs, so the fast path falls back."""
+    yaml_path = _bare_yaml(tmp_path)
     storage_dir = tmp_path / ".esphome" / "storage"
-    storage_dir.mkdir(parents=True, exist_ok=True)
-    # StorageJSON with both core_platform and target_platform unset.
-    (storage_dir / "lite_test.yaml.json").write_text(
-        '{"storage_version": 1, "name": "lite_test", "friendly_name": null, '
-        '"comment": null, "esphome_version": null, "src_version": 1, '
-        '"address": null, "web_port": null, "esp_platform": null, '
-        '"build_path": null, "firmware_bin_path": null, '
-        '"loaded_integrations": [], "loaded_platforms": [], "no_mdns": false, '
-        '"framework": null, "core_platform": null}'
-    )
+    _write_storage(storage_dir / "lite_test.yaml.json", **wizard_kwargs)
     cache_path = _write_cache(storage_dir / "lite_test.yaml.validated.json")
     _set_cache_mtime(cache_path, yaml_path, offset=5)
 

tests/unit_tests/test_config_normalization.py

@@ -7,7 +7,7 @@ from unittest.mock import MagicMock, Mock, patch
 
 import pytest
 
-from esphome import config, yaml_util
+from esphome import config, config_validation as cv, yaml_util
 from esphome.core import CORE, AutoLoad
 from esphome.types import ConfigType
 
@@ -127,12 +127,14 @@ def _run_load_step(
     domain: str,
     conf: object,
     migrate: Callable[[ConfigType], list | None] | None,
+    expand: Callable[[list], list] | None = None,
 ) -> config.Config:
-    """Run a LoadValidationStep for a platform component with a given migrate hook."""
+    """Run a LoadValidationStep for a platform component with given hooks."""
     component = Mock()
     component.is_platform_component = True
     component.multi_conf_no_default = False
     component.legacy_config_migrate = migrate
+    component.expand_platform_config = expand
 
     result = config.Config()
     with (
@@ -197,6 +199,124 @@ def test_legacy_migrate_skipped_for_autoload() -> None:
     assert result["image"] == [auto]
 
 
+# ---------------------------------------------------------------------------
+# EXPAND_PLATFORM_CONFIG hook on LoadValidationStep -- permanent counterpart
+# to legacy_config_migrate; runs after legacy migration/list normalization.
+# ---------------------------------------------------------------------------
+
+
+def test_expand_hook_rewrites_conf() -> None:
+    """A config the expand hook rewrites is replaced with the expanded list."""
+    expanded = [{"platform": "file", "id": "a"}, {"platform": "file", "id": "b"}]
+    expand = Mock(return_value=expanded)
+
+    result = _run_load_step("image", [{"platform": "file", "id": "a"}], None, expand)
+
+    expand.assert_called_once_with([{"platform": "file", "id": "a"}])
+    assert result["image"] == expanded
+
+
+def test_expand_hook_absent_is_noop() -> None:
+    """A platform component without the hook is left as normalized by the
+    existing list-wrapping logic."""
+    result = _run_load_step("image", [{"platform": "file", "id": "a"}], None, None)
+
+    assert result["image"] == [{"platform": "file", "id": "a"}]
+
+
+def test_expand_hook_runs_after_legacy_migrate() -> None:
+    """The expand hook sees the already-migrated list, not the raw legacy conf."""
+    migrated = [{"platform": "file", "id": "a"}]
+    migrate = Mock(return_value=migrated)
+    expand = Mock(side_effect=lambda conf: conf)
+
+    _run_load_step("image", [{"id": "a", "file": "x.png"}], migrate, expand)
+
+    expand.assert_called_once_with(migrated)
+
+
+def test_expand_hook_skipped_for_non_dict_entry() -> None:
+    """Malformed entries are left alone; the hook only sees `platform:`-tagged dicts."""
+    expand = Mock(side_effect=lambda conf: conf)
+
+    result = _run_load_step("image", ["not-a-dict"], None, expand)
+
+    expand.assert_not_called()
+    assert result["image"] == ["not-a-dict"]
+
+
+def test_expand_hook_skipped_for_entry_missing_platform_key() -> None:
+    """A dict entry missing the `platform:` key is left alone -- the normal
+    per-entry error reporting further down catches this case instead."""
+    expand = Mock(side_effect=lambda conf: conf)
+
+    result = _run_load_step("image", [{"id": "a"}], None, expand)
+
+    expand.assert_not_called()
+    assert result["image"] == [{"id": "a"}]
+
+
+def test_expand_hook_skipped_for_autoload() -> None:
+    """A non-empty AutoLoad reaching the hook stage is left alone."""
+    expand = Mock(side_effect=lambda conf: conf)
+    auto = AutoLoad()
+    auto["id"] = "a"
+
+    result = _run_load_step("image", auto, None, expand)
+
+    expand.assert_not_called()
+    assert result["image"] == [auto]
+
+
+def test_expand_hook_runs_when_all_entries_are_platform_tagged_dicts() -> None:
+    """The guard does not block the normal, well-formed case."""
+    expand = Mock(side_effect=lambda conf: conf)
+    conf = [{"platform": "file", "id": "a"}, {"platform": "animation", "id": "b"}]
+
+    result = _run_load_step("image", conf, None, expand)
+
+    expand.assert_called_once_with(conf)
+    assert result["image"] == conf
+
+
+def test_expand_hook_invalid_reports_single_error_at_domain_path() -> None:
+    """A `cv.Invalid` from the hook is reported once with the domain path prepended; no further validation runs."""
+    expand = Mock(side_effect=cv.Invalid("bad shape"))
+    pre_expand_conf = [{"platform": "file", "id": "a"}]
+
+    result = _run_load_step("image", pre_expand_conf, None, expand)
+
+    assert len(result.errors) == 1
+    assert result.errors[0].path == ["image"]
+    assert "bad shape" in str(result.errors[0])
+    assert result["image"] == pre_expand_conf
+
+
+def test_expand_hook_final_external_invalid_reports_without_path_prepend() -> None:
+    """`cv.FinalExternalInvalid` keeps its already-resolved path (no domain path prepended)."""
+    already_resolved_error = cv.FinalExternalInvalid(
+        "bad shape", path=["image", 3, "files"]
+    )
+    expand = Mock(side_effect=already_resolved_error)
+    pre_expand_conf = [{"platform": "file", "id": "a"}]
+
+    result = _run_load_step("image", pre_expand_conf, None, expand)
+
+    assert len(result.errors) == 1
+    assert result.errors[0] is already_resolved_error
+    assert result.errors[0].path == ["image", 3, "files"]
+    assert result["image"] == pre_expand_conf
+
+
+def test_expand_hook_non_list_return_raises_type_error() -> None:
+    """A non-list return is a component bug: it escapes as an uncaught TypeError
+    (explicit raise survives -O/-OO)."""
+    expand = Mock(return_value={"not": "a list"})
+
+    with pytest.raises(TypeError, match="must return a list"):
+        _run_load_step("image", [{"platform": "file", "id": "a"}], None, expand)
+
+
 def _write_merge_conflict_config(tmp_path: Path, *, suppress: bool) -> Path:
     """Create a config where two `<<` includes both define `logger:`.
 

tests/unit_tests/test_config_validation.py

@@ -2967,6 +2967,23 @@ def test_require_esphome_version_older_prerelease_fails() -> None:
         cv.require_esphome_version(2026, 8, 0)("test")
 
 
+def test_parse_esphome_version_deprecated_shim(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """The removed helper still works for external components and warns."""
+    from esphome import const, util
+
+    with (
+        patch.object(const, "__version__", "2026.9.0-dev"),
+        caplog.at_level(logging.WARNING),
+    ):
+        assert cv.parse_esphome_version() == (2026, 9, 0)
+        assert cv.parse_esphome_version() < (9999, 0, 0)
+    assert "parse_esphome_version() is deprecated" in caplog.text
+    # Both historical import paths resolve to the same function
+    assert cv.parse_esphome_version is util.parse_esphome_version
+
+
 # ---------------------------------------------------------------------------
 # suppress_invalid / validate_source_shorthand / rename_key
 # ---------------------------------------------------------------------------

tests/unit_tests/test_download_types.py

@@ -0,0 +1,52 @@
+"""Platform get_download_types contract for never-built configs.
+
+Wizard-written and upload/logs-fallback sidecars record no
+firmware_bin_path; the download panel must get an empty list for them,
+not entries pointing at files that were never built.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from esphome.storage_json import StorageJSON
+
+PLATFORMS = ["esp32", "esp8266", "rp2", "libretiny", "nrf52"]
+
+
+def _download_types(platform: str, storage: StorageJSON) -> list[dict[str, Any]]:
+    return import_module(f"esphome.components.{platform}").get_download_types(storage)
+
+
+def _wizard_storage() -> StorageJSON:
+    return StorageJSON.from_wizard(
+        name="test_device",
+        friendly_name="Test Device",
+        address="test_device.local",
+        platform="ESP32",
+    )
+
+
+@pytest.mark.parametrize("platform", PLATFORMS)
+def test_no_firmware_path_yields_no_downloads(platform: str) -> None:
+    """No recorded firmware path means nothing was built; no downloads."""
+    assert _download_types(platform, _wizard_storage()) == []
+
+
+@pytest.mark.parametrize("platform", PLATFORMS)
+def test_recorded_firmware_path_yields_downloads(platform: str, tmp_path: Path) -> None:
+    """With a firmware path recorded, every platform offers entries in
+    the documented title/description/file/download shape."""
+    storage = _wizard_storage()
+    storage.firmware_bin_path = tmp_path / "firmware.bin"
+
+    types = _download_types(platform, storage)
+
+    assert types
+    assert all(
+        {"title", "description", "file", "download"} <= entry.keys() for entry in types
+    )

tests/unit_tests/test_espidf_toolchain.py

@@ -265,6 +265,21 @@ def test_get_idf_env_sets_git_ceiling_directories(setup_core: Path) -> None:
     assert str(CORE.config_dir) in env["GIT_CEILING_DIRECTORIES"].split(os.pathsep)
 
 
+def test_get_idf_env_pops_inherited_pythonpath(setup_core: Path) -> None:
+    """A PYTHONPATH from the parent environment must not reach idf.py.
+
+    It would override the IDF venv's isolation, shadowing its pinned
+    packages and failing idf.py's dependency check.
+    """
+    toolchain._cache().env.clear()
+    with patch.dict(
+        os.environ,
+        {"IDF_PATH": str(setup_core), "PYTHONPATH": "/outside/site-packages"},
+    ):
+        env = toolchain._get_idf_env(version="5.5.4")
+    assert "PYTHONPATH" not in env
+
+
 def test_get_cmake_output_without_build_dir(setup_core: Path) -> None:
     """A build dir that was never created raises EsphomeError.
 

tests/unit_tests/test_espota2.py

@@ -44,13 +44,17 @@ def mock_file() -> io.BytesIO:
 
 
 @pytest.fixture
-def mock_time() -> Generator[None]:
+def mock_sleep() -> Generator[Mock]:
+    """Mock time.sleep so delays don't slow down tests."""
+    with patch("time.sleep") as mock:
+        yield mock
+
+
+@pytest.fixture
+def mock_time(mock_sleep: Mock) -> Generator[None]:
     """Mock time-related functions for consistent testing."""
     # Provide enough values for multiple calls (tests may call perform_ota multiple times)
-    with (
-        patch("time.sleep"),
-        patch("time.perf_counter", side_effect=[0, 1, 0, 1, 0, 1]),
-    ):
+    with patch("time.perf_counter", side_effect=[0, 1, 0, 1, 0, 1]):
         yield
 
 
@@ -79,6 +83,28 @@ def mock_resolve_ip() -> Generator[Mock]:
         yield mock
 
 
+DUAL_STACK_SA6 = ("2001:db8::1", 3232, 0, 0)
+DUAL_STACK_SA4 = ("192.168.1.100", 3232)
+
+
+@pytest.fixture
+def mock_resolve_ip_dual(mock_resolve_ip: Mock) -> Mock:
+    """Make resolve_ip_address return an IPv6 and an IPv4 address."""
+    mock_resolve_ip.return_value = [
+        (socket.AF_INET6, socket.SOCK_STREAM, 0, "", DUAL_STACK_SA6),
+        (socket.AF_INET, socket.SOCK_STREAM, 0, "", DUAL_STACK_SA4),
+    ]
+    return mock_resolve_ip
+
+
+@pytest.fixture
+def firmware_file(tmp_path: Path) -> Path:
+    """Create a firmware file on disk for run_ota_impl_ tests."""
+    firmware = tmp_path / "firmware.bin"
+    firmware.write_bytes(b"firmware content")
+    return firmware
+
+
 @pytest.fixture
 def mock_perform_ota() -> Generator[Mock]:
     """Mock perform_ota function for testing."""
@@ -137,9 +163,11 @@ def test_receive_exactly_with_error_response(mock_socket: Mock) -> None:
 
     with pytest.raises(
         espota2.OTAError, match="receiving auth:.*Authentication invalid"
-    ):
+    ) as exc_info:
         espota2.receive_exactly(mock_socket, 1, "auth", [espota2.RESPONSE_OK])
 
+    # Device-reported errors must stay plain OTAError, not the retryable kind
+    assert not isinstance(exc_info.value, espota2.OTANetworkError)
     mock_socket.close.assert_called_once()
 
 
@@ -147,10 +175,30 @@ def test_receive_exactly_socket_error(mock_socket: Mock) -> None:
     """Test receive_exactly handles socket errors."""
     mock_socket.recv.side_effect = OSError("Connection reset")
 
-    with pytest.raises(espota2.OTAError, match="receiving test response"):
+    with pytest.raises(espota2.OTANetworkError, match="receiving test response"):
         espota2.receive_exactly(mock_socket, 1, "test", espota2.RESPONSE_OK)
 
 
+def test_receive_exactly_mid_read_socket_error(mock_socket: Mock) -> None:
+    """Test receive_exactly handles socket errors after the first byte."""
+    mock_socket.recv.side_effect = [b"\x00", OSError("Connection reset")]
+
+    with pytest.raises(espota2.OTANetworkError, match="receiving test:"):
+        espota2.receive_exactly(mock_socket, 3, "test", espota2.RESPONSE_OK)
+
+
+def test_receive_exactly_closed_connection_is_network_error(mock_socket: Mock) -> None:
+    """Test receive_exactly raises OTANetworkError when the device closes the connection."""
+    mock_socket.recv.return_value = b""
+
+    with pytest.raises(
+        espota2.OTANetworkError, match="Device closed connection without responding"
+    ):
+        espota2.receive_exactly(mock_socket, 1, "test", espota2.RESPONSE_OK)
+
+    mock_socket.close.assert_called_once()
+
+
 @pytest.mark.parametrize(
     ("error_code", "expected_msg"),
     [
@@ -227,15 +275,15 @@ def test_check_error_unexpected_response() -> None:
 
 
 def test_check_error_empty_data() -> None:
-    """Test check_error raises error when device closes connection without responding."""
+    """Test check_error raises the retryable OTANetworkError when the device closes the connection."""
     with pytest.raises(
-        espota2.OTAError, match="Device closed connection without responding"
+        espota2.OTANetworkError, match="Device closed connection without responding"
     ):
         espota2.check_error([], [espota2.RESPONSE_OK])
 
     # Also test with empty bytes
     with pytest.raises(
-        espota2.OTAError, match="Device closed connection without responding"
+        espota2.OTANetworkError, match="Device closed connection without responding"
     ):
         espota2.check_error(b"", [espota2.RESPONSE_OK])
 
@@ -530,6 +578,144 @@ def test_perform_ota_upload_error(mock_socket: Mock, mock_file: io.BytesIO) -> N
         espota2.perform_ota(mock_socket, None, mock_file, "test.bin")
 
 
+def _no_auth_handshake(version: int) -> list[bytes]:
+    """Recv responses for a handshake without auth, up to the MD5 check."""
+    return [
+        bytes([espota2.RESPONSE_OK]),  # First byte of version response
+        bytes([version]),  # Version number
+        bytes([espota2.RESPONSE_HEADER_OK]),  # Features response
+        bytes([espota2.RESPONSE_AUTH_OK]),  # No auth required
+        bytes([espota2.RESPONSE_UPDATE_PREPARE_OK]),  # Binary size OK
+        bytes([espota2.RESPONSE_BIN_MD5_OK]),  # MD5 checksum OK
+    ]
+
+
+@pytest.mark.usefixtures("mock_time")
+def test_perform_ota_chunk_send_error(mock_socket: Mock, mock_file: io.BytesIO) -> None:
+    """Test OTA raises the retryable OTANetworkError when sending a chunk fails."""
+    mock_socket.recv.side_effect = [
+        *_no_auth_handshake(espota2.OTA_VERSION_2_0),
+        OSError("Connection reset"),  # Probe for a pending error byte fails too
+    ]
+    # Sends before the data phase: magic bytes, features, binary size, MD5;
+    # fail on the fifth sendall, the first firmware chunk
+    mock_socket.sendall.side_effect = [None] * 4 + [OSError("Broken pipe")]
+
+    with pytest.raises(espota2.OTANetworkError, match="sending data:"):
+        espota2.perform_ota(mock_socket, None, mock_file, "test.bin")
+
+
+@pytest.mark.usefixtures("mock_time")
+def test_perform_ota_chunk_send_error_surfaces_device_error(
+    mock_socket: Mock, mock_file: io.BytesIO
+) -> None:
+    """Test a device error byte pending behind a send failure becomes the cause."""
+    mock_socket.recv.side_effect = [
+        *_no_auth_handshake(espota2.OTA_VERSION_1_0),
+        bytes([espota2.RESPONSE_ERROR_WRITING_FLASH]),  # Reason the device closed
+    ]
+    mock_socket.sendall.side_effect = [None] * 4 + [OSError("Broken pipe")]
+
+    with pytest.raises(
+        espota2.OTAError, match="Writing OTA data to flash memory failed"
+    ) as exc:
+        espota2.perform_ota(mock_socket, None, mock_file, "test.bin")
+
+    # The device-reported error is not retryable
+    assert not isinstance(exc.value, espota2.OTANetworkError)
+
+
+@pytest.mark.usefixtures("mock_time")
+def test_perform_ota_final_chunk_ack_failure_not_retryable(
+    mock_socket: Mock, mock_file: io.BytesIO
+) -> None:
+    """Test a lost ack for the final chunk is not retried."""
+    mock_socket.recv.side_effect = [
+        *_no_auth_handshake(espota2.OTA_VERSION_2_0),
+        OSError("Connection reset"),  # Ack for the only (final) chunk is lost
+    ]
+
+    with pytest.raises(espota2.OTAError, match="receiving chunk result") as exc:
+        espota2.perform_ota(mock_socket, None, mock_file, "test.bin")
+
+    # The device already had the whole image, so it may be committing
+    assert not isinstance(exc.value, espota2.OTANetworkError)
+
+
+@pytest.mark.usefixtures("mock_time")
+def test_perform_ota_intermediate_chunk_ack_failure_retryable(
+    mock_socket: Mock,
+) -> None:
+    """Test a lost ack for a non-final chunk stays retryable."""
+    # Two chunks: the firmware is larger than one upload block
+    big_file = io.BytesIO(b"x" * (espota2.UPLOAD_BLOCK_SIZE + 1))
+    mock_socket.recv.side_effect = [
+        *_no_auth_handshake(espota2.OTA_VERSION_2_0),
+        OSError("Connection reset"),  # Ack for the first of two chunks is lost
+    ]
+
+    with pytest.raises(espota2.OTANetworkError, match="receiving chunk result"):
+        espota2.perform_ota(mock_socket, None, big_file, "test.bin")
+
+
+@pytest.mark.usefixtures("mock_time")
+def test_perform_ota_post_commit_failure_not_retryable(
+    mock_socket: Mock, mock_file: io.BytesIO
+) -> None:
+    """Test a network failure after the device committed is a plain OTAError."""
+    mock_socket.recv.side_effect = [
+        *_no_auth_handshake(espota2.OTA_VERSION_1_0),
+        bytes([espota2.RESPONSE_RECEIVE_OK]),  # Device received everything
+        OSError("Connection reset"),  # Connection lost waiting for end result
+    ]
+
+    with pytest.raises(espota2.OTAError, match="receiving update end result") as exc:
+        espota2.perform_ota(mock_socket, None, mock_file, "test.bin")
+
+    # Must not be the retryable kind; the device is already rebooting
+    assert not isinstance(exc.value, espota2.OTANetworkError)
+
+
+@pytest.mark.usefixtures("mock_time")
+def test_perform_ota_md5_mismatch_not_marked_committed(
+    mock_socket: Mock, mock_file: io.BytesIO
+) -> None:
+    """Test an MD5 mismatch keeps its own message and stays non-retryable."""
+    mock_socket.recv.side_effect = [
+        *_no_auth_handshake(espota2.OTA_VERSION_1_0),
+        bytes([espota2.RESPONSE_RECEIVE_OK]),  # Device received everything
+        bytes([espota2.RESPONSE_ERROR_MD5_MISMATCH]),  # Device aborted the update
+    ]
+
+    with pytest.raises(espota2.OTAError, match="MD5 code mismatch") as exc:
+        espota2.perform_ota(mock_socket, None, mock_file, "test.bin")
+
+    # The device aborted without committing, so the message must not claim
+    # the update may have been installed, and the error must not be retried
+    assert not isinstance(exc.value, espota2.OTANetworkError)
+    assert "committed" not in str(exc.value)
+
+
+@pytest.mark.usefixtures("mock_time")
+def test_perform_ota_end_ack_send_failure_is_success(
+    mock_socket: Mock, mock_file: io.BytesIO
+) -> None:
+    """Test a send failure on the final acknowledgement does not fail the OTA."""
+    mock_socket.recv.side_effect = [
+        *_no_auth_handshake(espota2.OTA_VERSION_1_0),
+        bytes([espota2.RESPONSE_RECEIVE_OK]),  # Device received everything
+        bytes([espota2.RESPONSE_UPDATE_END_OK]),  # Update committed
+    ]
+    # Sends: magic bytes, features, binary size, MD5, one firmware chunk;
+    # fail on the sixth sendall, the end acknowledgement
+    mock_socket.sendall.side_effect = [None] * 5 + [OSError("Broken pipe")]
+
+    # Must not raise; the device treats a missing acknowledgement as non-fatal
+    espota2.perform_ota(mock_socket, None, mock_file, "test.bin")
+
+    assert mock_socket.sendall.call_count == 6
+
+
 @pytest.mark.usefixtures("mock_socket_constructor", "mock_resolve_ip")
 def test_run_ota_impl_successful(
     mock_socket: Mock, tmp_path: Path, mock_perform_ota: Mock
@@ -564,21 +750,183 @@ def test_run_ota_impl_successful(
 
 
 @pytest.mark.usefixtures("mock_socket_constructor", "mock_resolve_ip")
-def test_run_ota_impl_connection_failed(mock_socket: Mock, tmp_path: Path) -> None:
-    """Test run_ota_impl_ when connection fails."""
+def test_run_ota_impl_connection_failed(
+    mock_socket: Mock, firmware_file: Path, mock_sleep: Mock
+) -> None:
+    """Test run_ota_impl_ retries when connection fails and eventually gives up."""
     mock_socket.connect.side_effect = OSError("Connection refused")
 
-    # Create a real firmware file
-    firmware_file = tmp_path / "firmware.bin"
-    firmware_file.write_bytes(b"firmware content")
-
     result_code, result_host = espota2.run_ota_impl_(
         "test.local", 3232, "password", str(firmware_file)
     )
 
     assert result_code == 1
     assert result_host is None
-    mock_socket.close.assert_called_once()
+    # A single address gets the whole attempt budget, with a delay before
+    # each revisit
+    assert mock_socket.connect.call_count == espota2.EXTRA_UPLOAD_ATTEMPTS + 1
+    assert mock_socket.close.call_count == espota2.EXTRA_UPLOAD_ATTEMPTS + 1
+    assert mock_sleep.call_count == espota2.EXTRA_UPLOAD_ATTEMPTS
+    mock_sleep.assert_called_with(espota2.UPLOAD_RETRY_DELAY)
+
+
+@pytest.mark.usefixtures("mock_socket_constructor", "mock_resolve_ip")
+def test_run_ota_impl_connect_retry_succeeds(
+    mock_socket: Mock, firmware_file: Path, mock_perform_ota: Mock, mock_sleep: Mock
+) -> None:
+    """Test run_ota_impl_ succeeds when a retry connects after a failed attempt."""
+    mock_socket.connect.side_effect = [OSError("Connection timed out"), None]
+
+    result_code, result_host = espota2.run_ota_impl_(
+        "test.local", 3232, "password", str(firmware_file)
+    )
+
+    assert result_code == 0
+    assert result_host == "192.168.1.100"
+    assert mock_socket.connect.call_count == 2
+    mock_sleep.assert_called_once_with(espota2.UPLOAD_RETRY_DELAY)
+    mock_perform_ota.assert_called_once()
+
+
+@pytest.mark.usefixtures("mock_socket_constructor", "mock_resolve_ip")
+def test_run_ota_impl_network_error_retry_succeeds(
+    mock_socket: Mock, firmware_file: Path, mock_perform_ota: Mock, mock_sleep: Mock
+) -> None:
+    """Test run_ota_impl_ retries after a network error during the upload."""
+    mock_perform_ota.side_effect = [
+        espota2.OTANetworkError("receiving features: Device closed connection"),
+        None,
+    ]
+
+    result_code, result_host = espota2.run_ota_impl_(
+        "test.local", 3232, "password", str(firmware_file)
+    )
+
+    assert result_code == 0
+    assert result_host == "192.168.1.100"
+    assert mock_perform_ota.call_count == 2
+    mock_sleep.assert_called_once_with(espota2.UPLOAD_RETRY_DELAY)
+
+
+@pytest.mark.usefixtures("mock_socket_constructor", "mock_resolve_ip")
+def test_run_ota_impl_network_error_exhausts_attempts(
+    mock_socket: Mock, firmware_file: Path, mock_perform_ota: Mock, mock_sleep: Mock
+) -> None:
+    """Test run_ota_impl_ gives up after all attempts hit network errors."""
+    mock_perform_ota.side_effect = espota2.OTANetworkError("sending data: broken pipe")
+
+    result_code, result_host = espota2.run_ota_impl_(
+        "test.local", 3232, "password", str(firmware_file)
+    )
+
+    assert result_code == 1
+    assert result_host is None
+    assert mock_perform_ota.call_count == espota2.EXTRA_UPLOAD_ATTEMPTS + 1
+    assert mock_sleep.call_count == espota2.EXTRA_UPLOAD_ATTEMPTS
+
+
+@pytest.mark.usefixtures("mock_socket_constructor", "mock_resolve_ip_dual")
+def test_run_ota_impl_multiple_addresses_cycle(
+    mock_socket: Mock, firmware_file: Path, mock_sleep: Mock
+) -> None:
+    """Test run_ota_impl_ visits every address and cycles for the retries."""
+    mock_socket.connect.side_effect = OSError("No route to host")
+
+    result_code, result_host = espota2.run_ota_impl_(
+        "test.local", 3232, "password", str(firmware_file)
+    )
+
+    assert result_code == 1
+    assert result_host is None
+    # Each address is visited once, then the EXTRA_UPLOAD_ATTEMPTS spare
+    # attempts cycle back through them; the budget is shared, not per address
+    assert mock_socket.connect.call_args_list == [
+        call(DUAL_STACK_SA6),
+        call(DUAL_STACK_SA4),
+        call(DUAL_STACK_SA6),
+        call(DUAL_STACK_SA4),
+    ]
+    # No connect ever reached the device, so the delay only applies before
+    # the revisits
+    assert mock_sleep.call_count == 2
+
+
+@pytest.mark.usefixtures("mock_socket_constructor", "mock_resolve_ip_dual")
+def test_run_ota_impl_second_address_succeeds_without_delay(
+    mock_socket: Mock,
+    firmware_file: Path,
+    mock_perform_ota: Mock,
+    mock_sleep: Mock,
+) -> None:
+    """Test run_ota_impl_ falls through to the next address with no pause."""
+    mock_socket.connect.side_effect = [OSError("No route to host"), None]
+
+    result_code, result_host = espota2.run_ota_impl_(
+        "test.local", 3232, "password", str(firmware_file)
+    )
+
+    assert result_code == 0
+    assert result_host == "192.168.1.100"
+    mock_sleep.assert_not_called()
+    mock_perform_ota.assert_called_once()
+
+
+@pytest.mark.usefixtures("mock_socket_constructor", "mock_resolve_ip_dual")
+def test_run_ota_impl_pauses_after_reaching_device(
+    mock_socket: Mock,
+    firmware_file: Path,
+    mock_perform_ota: Mock,
+    mock_sleep: Mock,
+) -> None:
+    """Test run_ota_impl_ pauses before the next address once the device was reached."""
+    mock_perform_ota.side_effect = [
+        espota2.OTANetworkError("sending data: connection reset"),
+        None,
+    ]
+
+    result_code, result_host = espota2.run_ota_impl_(
+        "test.local", 3232, "password", str(firmware_file)
+    )
+
+    assert result_code == 0
+    assert result_host == "192.168.1.100"
+    # The first attempt reached the device, so the next one waits first even
+    # though it targets a fresh address
+    mock_sleep.assert_called_once_with(espota2.UPLOAD_RETRY_DELAY)
+
+
+@pytest.mark.usefixtures("mock_socket_constructor", "mock_resolve_ip")
+def test_run_ota_impl_device_error_not_retried(
+    mock_socket: Mock, firmware_file: Path, mock_perform_ota: Mock, mock_sleep: Mock
+) -> None:
+    """Test run_ota_impl_ fails immediately on a device-reported error."""
+    mock_perform_ota.side_effect = espota2.OTAError(
+        "Authentication invalid. Is the password correct?"
+    )
+
+    result_code, result_host = espota2.run_ota_impl_(
+        "test.local", 3232, "password", str(firmware_file)
+    )
+
+    assert result_code == 1
+    assert result_host is None
+    mock_perform_ota.assert_called_once()
+    mock_sleep.assert_not_called()
+
+
+def test_run_ota_impl_no_addresses(
+    firmware_file: Path, mock_resolve_ip: Mock, mock_sleep: Mock
+) -> None:
+    """Test run_ota_impl_ fails cleanly when resolution yields no addresses."""
+    mock_resolve_ip.return_value = []
+
+    result_code, result_host = espota2.run_ota_impl_(
+        "test.local", 3232, "password", str(firmware_file)
+    )
+
+    assert result_code == 1
+    assert result_host is None
+    mock_sleep.assert_not_called()
 
 
 def test_run_ota_impl_resolve_failed(tmp_path: Path, mock_resolve_ip: Mock) -> None:

tests/unit_tests/test_framework_helpers.py

@@ -12,7 +12,7 @@ from pathlib import Path
 import subprocess
 import sys
 import tarfile
-from unittest.mock import MagicMock, Mock, patch
+from unittest.mock import MagicMock, Mock, call, patch
 import zipfile
 
 import pytest
@@ -23,6 +23,7 @@ from esphome.core import EsphomeError
 from esphome.framework_helpers import (
     _7z_extract_all,
     _detect_archive_root,
+    _is_transient_download_error,
     _rename_with_retry,
     _tar_extract_all,
     _zip_extract_all,
@@ -187,6 +188,24 @@ def test_run_command_passes_env(mock_subprocess_run: Mock) -> None:
     assert mock_subprocess_run.call_args[1]["env"]["MY_VAR"] == "42"
 
 
+def test_run_command_pops_inherited_pythonpath(mock_subprocess_run: Mock) -> None:
+    """A PYTHONPATH from the parent environment must not leak into subprocesses."""
+    mock_subprocess_run.return_value = Mock(returncode=0, stdout="", stderr="")
+    with patch.dict(os.environ, {"PYTHONPATH": "/outside/site-packages"}):
+        run_command(["cmd"])
+    assert "PYTHONPATH" not in mock_subprocess_run.call_args[1]["env"]
+
+
+def test_run_command_env_pythonpath_preferred_over_pop(
+    mock_subprocess_run: Mock,
+) -> None:
+    """A PYTHONPATH set explicitly via ``env`` is passed through."""
+    mock_subprocess_run.return_value = Mock(returncode=0, stdout="", stderr="")
+    with patch.dict(os.environ, {"PYTHONPATH": "/outside/site-packages"}):
+        run_command(["cmd"], env={"PYTHONPATH": "/idf/tools"})
+    assert mock_subprocess_run.call_args[1]["env"]["PYTHONPATH"] == "/idf/tools"
+
+
 def test_run_command_passes_cwd(mock_subprocess_run: Mock, tmp_path: Path) -> None:
     mock_subprocess_run.return_value = Mock(returncode=0, stdout="", stderr="")
     run_command(["cmd"], cwd=str(tmp_path))
@@ -515,16 +534,23 @@ class TestArchiveExtractAll:
 # ---------------------------------------------------------------------------
 
 
-def _mock_response(content: bytes, ok: bool = True) -> MagicMock:
+def _mock_response(
+    content: bytes, ok: bool = True, status: int | None = None
+) -> MagicMock:
+    """A fake requests response. The HTTPError carries the response (as
+    ``raise_for_status`` on a real response) so the transient classifier
+    can see its ``status``; failures default to a permanent 404."""
+    if status is None:
+        status = 200 if ok else 404
     r = MagicMock()
     r.__enter__.return_value = r
     r.__exit__.return_value = False
-    r.status_code = 200
+    r.status_code = status
     r.ok = ok
     if ok:
         r.raise_for_status.return_value = None
     else:
-        r.raise_for_status.side_effect = req.HTTPError("503")
+        r.raise_for_status.side_effect = req.HTTPError(str(status), response=r)
     r.headers = {"content-length": "0"}  # suppress ProgressBar
     r.iter_content.return_value = [content] if content else []
     return r
@@ -1419,6 +1445,191 @@ class TestDownloadFromMirrors:
         assert target.exists()
         assert target.read_bytes() == b""
 
+    @pytest.mark.parametrize("target_kind", ["path", "file-like"])
+    def test_transient_failure_retries_mirror_sweep(
+        self, tmp_path: Path, target_kind: str
+    ) -> None:
+        """A transient connect error on the only applicable mirror retries the
+        whole mirror list with backoff instead of failing the build."""
+        target = tmp_path / "idf.tar.xz" if target_kind == "path" else io.BytesIO()
+        with (
+            patch(
+                "requests.get",
+                side_effect=[
+                    req.ConnectionError("Remote end closed connection"),
+                    _mock_response(b"data"),
+                ],
+            ) as mock_get,
+            patch("esphome.framework_helpers.time.sleep") as mock_sleep,
+        ):
+            url = download_from_mirrors(["https://mirror1.com/f"], {}, target)
+        assert url == "https://mirror1.com/f"
+        data = target.read_bytes() if target_kind == "path" else target.getvalue()
+        assert data == b"data"
+        assert mock_get.call_count == 2
+        mock_sleep.assert_called_once_with(2)
+
+    def test_permanent_failure_does_not_retry_sweep(self, tmp_path: Path) -> None:
+        """An HTTP 404 will not heal on its own; fail after a single pass."""
+        with (
+            patch(
+                "requests.get", return_value=_mock_response(b"", ok=False, status=404)
+            ) as mock_get,
+            patch("esphome.framework_helpers.time.sleep") as mock_sleep,
+            pytest.raises(EsphomeError, match="all mirrors"),
+        ):
+            download_from_mirrors(["https://mirror1.com/f"], {}, tmp_path / "out.bin")
+        assert mock_get.call_count == 1
+        mock_sleep.assert_not_called()
+
+    def test_transient_failure_exhausts_sweeps(self, tmp_path: Path) -> None:
+        """A persistent transient error gives up after the configured number
+        of passes, with 2s/4s backoff, and still lists the attempted URL."""
+        with (
+            patch("requests.get", side_effect=req.ConnectionError("down")) as mock_get,
+            patch("esphome.framework_helpers.time.sleep") as mock_sleep,
+            pytest.raises(EsphomeError, match="all mirrors") as ei,
+        ):
+            download_from_mirrors(["https://mirror1.com/f"], {}, tmp_path / "out.bin")
+        assert mock_get.call_count == 3
+        assert mock_sleep.call_args_list == [call(2), call(4)]
+        assert "https://mirror1.com/f" in str(ei.value)
+
+    def test_mixed_permanent_and_transient_retries_sweep(self, tmp_path: Path) -> None:
+        """One mirror 404s permanently while another hits a transient error;
+        the transient failure makes the whole list worth another pass."""
+        dest = tmp_path / "out.bin"
+        with (
+            patch(
+                "requests.get",
+                side_effect=[
+                    _mock_response(b"", ok=False, status=404),
+                    req.ConnectionError("down"),
+                    _mock_response(b"", ok=False, status=404),
+                    _mock_response(b"data"),
+                ],
+            ),
+            patch("esphome.framework_helpers.time.sleep") as mock_sleep,
+        ):
+            url = download_from_mirrors(
+                ["https://mirror1.com/f", "https://mirror2.com/f"], {}, dest
+            )
+        assert url == "https://mirror2.com/f"
+        assert dest.read_bytes() == b"data"
+        mock_sleep.assert_called_once_with(2)
+
+    def test_http_5xx_retries_sweep(self, tmp_path: Path) -> None:
+        """A real 5xx (response attached to the HTTPError) is transient."""
+        dest = tmp_path / "out.bin"
+        with (
+            patch(
+                "requests.get",
+                side_effect=[
+                    _mock_response(b"", ok=False, status=503),
+                    _mock_response(b"data"),
+                ],
+            ),
+            patch("esphome.framework_helpers.time.sleep") as mock_sleep,
+        ):
+            url = download_from_mirrors(["https://mirror1.com/f"], {}, dest)
+        assert url == "https://mirror1.com/f"
+        assert dest.read_bytes() == b"data"
+        mock_sleep.assert_called_once_with(2)
+
+    def test_error_reports_failure_modes_from_all_sweeps(self, tmp_path: Path) -> None:
+        """A failure mode that changes between sweeps stays in the final
+        error; the first failure (the one that started the retries) is
+        chained as the cause."""
+        with (
+            patch(
+                "requests.get",
+                side_effect=[
+                    req.ConnectionError("dropped by middlebox"),
+                    _mock_response(b"", ok=False, status=404),
+                ],
+            ),
+            patch("esphome.framework_helpers.time.sleep") as mock_sleep,
+            pytest.raises(EsphomeError, match="all mirrors") as ei,
+        ):
+            download_from_mirrors(["https://mirror1.com/f"], {}, tmp_path / "out.bin")
+        assert "dropped by middlebox" in str(ei.value)
+        assert "404" in str(ei.value)
+        assert isinstance(ei.value.__cause__, req.ConnectionError)
+        mock_sleep.assert_called_once_with(2)
+
+    def test_exhausted_mid_stream_attempts_not_swept(self) -> None:
+        """A file-like mirror that spent all its mid-stream attempts is not
+        retried again at the sweep level (unlike a path target, it has no
+        part file to resume from on a later sweep)."""
+        buf = io.BytesIO()
+        with (
+            patch(
+                "requests.get",
+                side_effect=[_interrupted_response(b"1234") for _ in range(3)],
+            ) as mock_get,
+            patch("esphome.framework_helpers.time.sleep") as mock_sleep,
+            pytest.raises(EsphomeError, match="failed after 3 attempts"),
+        ):
+            download_from_mirrors(["https://mirror1.com/f"], {}, buf)
+        assert mock_get.call_count == 3
+        mock_sleep.assert_not_called()
+
+    def test_mid_stream_drop_then_connect_error_not_swept(self) -> None:
+        """A connect error on a later attempt (after a mid-stream drop spent
+        one) also counts as spent budget and does not re-arm the sweep."""
+        buf = io.BytesIO()
+        with (
+            patch(
+                "requests.get",
+                side_effect=[
+                    _interrupted_response(b"1234"),
+                    req.ConnectionError("down"),
+                ],
+            ) as mock_get,
+            patch("esphome.framework_helpers.time.sleep") as mock_sleep,
+            pytest.raises(EsphomeError, match="failed after 2 attempts"),
+        ):
+            download_from_mirrors(["https://mirror1.com/f"], {}, buf)
+        assert mock_get.call_count == 2
+        mock_sleep.assert_not_called()
+
+
+def _http_error(status: int) -> req.HTTPError:
+    """An HTTPError carrying a response with the given status, as raised by
+    ``raise_for_status`` on a real response."""
+    resp = MagicMock()
+    resp.status_code = status
+    return req.HTTPError(str(status), response=resp)
+
+
+class TestIsTransientDownloadError:
+    def test_connection_errors_are_transient(self) -> None:
+        assert _is_transient_download_error(req.ConnectionError("reset"))
+        assert _is_transient_download_error(req.Timeout("timed out"))
+        assert _is_transient_download_error(
+            req.exceptions.ChunkedEncodingError("dropped")
+        )
+
+    def test_http_statuses(self) -> None:
+        assert not _is_transient_download_error(_http_error(404))
+        assert not _is_transient_download_error(_http_error(403))
+        assert _is_transient_download_error(_http_error(429))
+        assert _is_transient_download_error(_http_error(503))
+
+    def test_http_error_without_response_is_permanent(self) -> None:
+        assert not _is_transient_download_error(req.HTTPError("boom"))
+
+    def test_exhausted_resume_attempts_are_permanent(self) -> None:
+        """download_with_resume already spent its own resume attempts; its
+        EsphomeError wrapper is not retried again at the sweep level."""
+        wrapped = EsphomeError("Failed to download after 3 attempts")
+        wrapped.__cause__ = req.ConnectionError("down")
+        assert not _is_transient_download_error(wrapped)
+
+    def test_unrelated_errors_are_permanent(self) -> None:
+        assert not _is_transient_download_error(OSError("disk full"))
+        assert not _is_transient_download_error(EsphomeError("size mismatch"))
+
 
 def test_importing_framework_helpers_does_not_import_requests() -> None:
     """Importing framework_helpers must not drag in requests.

tests/unit_tests/test_loader.py

@@ -8,6 +8,7 @@ from unittest.mock import MagicMock, patch
 
 import pytest
 
+from esphome.component_aliases import COMPONENT_ALIASES
 from esphome.loader import (
     AliasMeta,
     ComponentManifest,
@@ -481,6 +482,33 @@ def test_real_alias_map_includes_rp2040() -> None:
     assert meta["rp2040"].removal_version == "2027.7.0"
 
 
+def test_alias_registry_matches_component_tree() -> None:
+    """The checked-in registry must match a live scan of the component tree."""
+    _, meta_map = _build_alias_map()
+    expected = {
+        alias: (meta.canonical, meta.removal_version)
+        for alias, meta in meta_map.items()
+    }
+    assert expected == COMPONENT_ALIASES, (
+        "esphome/component_aliases.py is out of date; "
+        "run script/build_alias_registry.py"
+    )
+
+
+def test_alias_map_built_from_registry() -> None:
+    """The runtime alias map comes from the generated registry, not a scan."""
+    with (
+        patch(
+            "esphome.component_aliases.COMPONENT_ALIASES",
+            {"legacy": ("modern", "2099.1.0")},
+        ),
+        patch("esphome.loader._ALIAS_META_CACHE", None),
+    ):
+        assert get_alias_metadata() == {
+            "legacy": AliasMeta(canonical="modern", removal_version="2099.1.0")
+        }
+
+
 def test_get_component_resolves_alias() -> None:
     """``get_component('rp2040')`` should return the rp2 manifest — every
     caller of the loader (dep checker, schema validator, codegen) hits

tests/unit_tests/test_main.py

@@ -25,6 +25,7 @@ from esphome.__main__ import (
     _make_crystal_freq_callback,
     _redact_with_legacy_fallback,
     _resolve_network_devices,
+    _split_network_devices,
     _unresolved_default_error,
     _validate_bootloader_binary,
     _validate_partition_table_binary,
@@ -2879,7 +2880,9 @@ def test_upload_program_ota_with_mqtt_resolution(
 
     assert exit_code == 0
     assert host == "192.168.1.100"
-    mock_mqtt_get_ip.assert_called_once_with(config, "user", "pass", "client")
+    mock_mqtt_get_ip.assert_called_once_with(
+        config, "user", "pass", "client", stop_event=None
+    )
     expected_firmware = (
         tmp_path / ".esphome" / "build" / "test" / ".pioenvs" / "test" / "firmware.bin"
     )
@@ -2926,7 +2929,9 @@ def test_upload_program_ota_with_mqtt_empty_broker(
     assert exit_code == 0
     assert host == "192.168.1.50"
     # Verify MQTT was attempted but failed gracefully
-    mock_mqtt_get_ip.assert_called_once_with(config, "user", "pass", "client")
+    mock_mqtt_get_ip.assert_called_once_with(
+        config, "user", "pass", "client", stop_event=None
+    )
     # Verify we fell back to the IP address
     expected_firmware = (
         tmp_path / ".esphome" / "build" / "test" / ".pioenvs" / "test" / "firmware.bin"
@@ -3015,7 +3020,10 @@ def test_show_logs_api(
 
     assert result == 0
     mock_run_logs.assert_called_once_with(
-        CORE.config, ["192.168.1.100", "192.168.1.101"], subscribe_states=True
+        CORE.config,
+        ["192.168.1.100", "192.168.1.101"],
+        subscribe_states=True,
+        mqtt_resolver=None,
     )
 
 
@@ -3042,7 +3050,7 @@ def test_show_logs_api_no_states(
 
     assert result == 0
     mock_run_logs.assert_called_once_with(
-        CORE.config, ["192.168.1.100"], subscribe_states=False
+        CORE.config, ["192.168.1.100"], subscribe_states=False, mqtt_resolver=None
     )
 
 
@@ -3069,7 +3077,7 @@ def test_show_logs_api_with_fqdn_mdns_disabled(
     assert result == 0
     # Should use the FQDN directly, not try MQTT lookup
     mock_run_logs.assert_called_once_with(
-        CORE.config, ["device.example.com"], subscribe_states=True
+        CORE.config, ["device.example.com"], subscribe_states=True, mqtt_resolver=None
     )
 
 
@@ -3097,9 +3105,44 @@ def test_show_logs_api_with_mqtt_fallback(
     result = show_logs(CORE.config, args, devices)
 
     assert result == 0
-    mock_mqtt_get_ip.assert_called_once_with(CORE.config, "user", "pass", "client")
+    mock_mqtt_get_ip.assert_called_once_with(
+        CORE.config, "user", "pass", "client", stop_event=None
+    )
     mock_run_logs.assert_called_once_with(
-        CORE.config, ["192.168.1.200"], subscribe_states=True
+        CORE.config, ["192.168.1.200"], subscribe_states=True, mqtt_resolver=None
+    )
+
+
+@patch("esphome.mqtt.show_logs")
+def test_show_logs_api_mqtt_only_resolve_failure_falls_back_to_mqtt_logs(
+    mock_mqtt_show_logs: Mock,
+    mock_mqtt_get_ip: Mock,
+) -> None:
+    """With no addresses at all after a failed MQTT lookup, MQTT logging is used."""
+    setup_core(
+        config={
+            "logger": {},
+            CONF_API: {},
+            CONF_MQTT: {CONF_BROKER: "mqtt.local"},
+        },
+        platform=PLATFORM_ESP32,
+    )
+    mock_mqtt_show_logs.return_value = 0
+    mock_mqtt_get_ip.side_effect = EsphomeError("Failed to find IP via MQTT")
+
+    args = MockArgs(
+        topic="esphome/logs", username="user", password="pass", client_id="client"
+    )
+    devices = ["MQTT", "MQTTIP"]
+
+    result = show_logs(CORE.config, args, devices)
+
+    assert result == 0
+    mock_mqtt_get_ip.assert_called_once_with(
+        CORE.config, "user", "pass", "client", stop_event=None
+    )
+    mock_mqtt_show_logs.assert_called_once_with(
+        CORE.config, "esphome/logs", "user", "pass", "client"
     )
 
 
@@ -3466,7 +3509,9 @@ def test_mqtt_get_ip() -> None:
         result = mqtt_get_ip(config, "user", "pass", "client-id")
 
         assert result == ["192.168.1.100", "192.168.1.101"]
-        mock_get_ip.assert_called_once_with(config, "user", "pass", "client-id")
+        mock_get_ip.assert_called_once_with(
+            config, "user", "pass", "client-id", stop_event=None
+        )
 
 
 def test_has_resolvable_address() -> None:
@@ -3847,6 +3892,37 @@ def test_resolve_network_devices_keeps_uncached_hosts(tmp_path: Path) -> None:
     assert result == ["unknown.local", "192.168.1.50"]
 
 
+def test_split_network_devices_direct_only(tmp_path: Path) -> None:
+    """Direct addresses pass through deduped, with no MQTT flag."""
+    setup_core(tmp_path=tmp_path)
+
+    assert _split_network_devices(["192.168.1.50", "device.local", "192.168.1.50"]) == (
+        ["192.168.1.50", "device.local"],
+        False,
+    )
+
+
+def test_split_network_devices_mqtt_only(tmp_path: Path) -> None:
+    """MQTT magic strings produce no direct addresses, only the flag."""
+    setup_core(tmp_path=tmp_path)
+
+    assert _split_network_devices(["MQTTIP", "MQTT"]) == ([], True)
+
+
+def test_split_network_devices_expands_cached_mdns_hosts(tmp_path: Path) -> None:
+    """Hostnames in ``CORE.address_cache`` are expanded like _resolve_network_devices."""
+    setup_core(tmp_path=tmp_path)
+    CORE.address_cache = AddressCache(
+        mdns_cache={
+            "device-abc123.local": ["10.0.0.1", "10.0.0.2"],
+        }
+    )
+
+    assert _split_network_devices(
+        ["device-abc123.local", "MQTTIP", "192.168.1.50", "device-abc123.local"]
+    ) == (["10.0.0.1", "10.0.0.2", "192.168.1.50"], True)
+
+
 def test_await_discovery_timeout_returns_empty(
     caplog: pytest.LogCaptureFixture,
 ) -> None:
@@ -5022,7 +5098,9 @@ def test_upload_program_ota_static_ip_with_mqttip(
     assert host == "192.168.1.100"
 
     # Verify MQTT was resolved
-    mock_mqtt_get_ip.assert_called_once_with(config, "user", "pass", "client")
+    mock_mqtt_get_ip.assert_called_once_with(
+        config, "user", "pass", "client", stop_event=None
+    )
 
     # Verify espota2.run_ota was called with both IPs
     expected_firmware = (
@@ -5069,7 +5147,9 @@ def test_upload_program_ota_multiple_mqttip_resolves_once(
     assert host == "192.168.2.50"
 
     # Verify MQTT was only resolved once despite multiple MQTT magic strings
-    mock_mqtt_get_ip.assert_called_once_with(config, "user", "pass", "client")
+    mock_mqtt_get_ip.assert_called_once_with(
+        config, "user", "pass", "client", stop_event=None
+    )
 
     # Verify espota2.run_ota was called with all unique IPs
     expected_firmware = (
@@ -5116,7 +5196,9 @@ def test_upload_program_ota_mqttip_deduplication(
     assert host == "192.168.1.100"
 
     # Verify MQTT was resolved
-    mock_mqtt_get_ip.assert_called_once_with(config, "user", "pass", "client")
+    mock_mqtt_get_ip.assert_called_once_with(
+        config, "user", "pass", "client", stop_event=None
+    )
 
     # Verify espota2.run_ota was called with deduplicated IPs (only one instance of 192.168.1.100)
     # Note: Current implementation doesn't dedupe, so we'll get the IP twice
@@ -5136,7 +5218,9 @@ def test_show_logs_api_static_ip_with_mqttip(
 
     This tests the scenario where a device has manual_ip (static IP) configured
     and MQTT is also configured. The devices list contains both the static IP
-    and "MQTTIP" magic string.
+    and "MQTTIP" magic string. The MQTT lookup must not block startup; it is
+    handed to run_logs as a deferred resolver instead (issue #18311), while
+    still being reachable as a fallback for a stale static IP.
     """
     setup_core(
         config={
@@ -5157,12 +5241,19 @@ def test_show_logs_api_static_ip_with_mqttip(
 
     assert result == 0
 
-    # Verify MQTT was resolved
-    mock_mqtt_get_ip.assert_called_once_with(CORE.config, "user", "pass", "client")
+    # The broker must not be contacted before run_logs starts
+    mock_mqtt_get_ip.assert_not_called()
 
-    # Verify run_logs was called with both IPs
-    mock_run_logs.assert_called_once_with(
-        CORE.config, ["192.168.1.100", "192.168.2.50"], subscribe_states=True
+    # run_logs gets the static IP immediately plus a deferred MQTT resolver
+    mock_run_logs.assert_called_once()
+    assert mock_run_logs.call_args.args == (CORE.config, ["192.168.1.100"])
+    assert mock_run_logs.call_args.kwargs["subscribe_states"] is True
+    resolver = mock_run_logs.call_args.kwargs["mqtt_resolver"]
+
+    # Invoking the resolver performs the MQTT lookup (the #11260 fallback)
+    assert resolver(None) == ["192.168.2.50"]
+    mock_mqtt_get_ip.assert_called_once_with(
+        CORE.config, "user", "pass", "client", stop_event=None
     )
 
 
@@ -5171,7 +5262,7 @@ def test_show_logs_api_multiple_mqttip_resolves_once(
     mock_run_logs: Mock,
     mock_mqtt_get_ip: Mock,
 ) -> None:
-    """Test that MQTT resolution only happens once for show_logs with multiple MQTT magic strings."""
+    """Test that multiple MQTT magic strings collapse into one deferred resolver."""
     setup_core(
         config={
             "logger": {},
@@ -5191,16 +5282,16 @@ def test_show_logs_api_multiple_mqttip_resolves_once(
 
     assert result == 0
 
-    # Verify MQTT was only resolved once despite multiple MQTT magic strings
-    mock_mqtt_get_ip.assert_called_once_with(CORE.config, "user", "pass", "client")
+    # Note: "MQTT" is a different magic string from "MQTTIP", but both defer
+    # to the same single resolver; the broker is not contacted eagerly
+    mock_mqtt_get_ip.assert_not_called()
+    mock_run_logs.assert_called_once()
+    assert mock_run_logs.call_args.args == (CORE.config, ["192.168.1.100"])
 
-    # Verify run_logs was called with all unique IPs (MQTT strings replaced with IPs)
-    # Note: "MQTT" is a different magic string from "MQTTIP", but both trigger MQTT resolution
-    # The _resolve_network_devices helper filters out both after first resolution
-    mock_run_logs.assert_called_once_with(
-        CORE.config,
-        ["192.168.2.50", "192.168.2.51", "192.168.1.100"],
-        subscribe_states=True,
+    resolver = mock_run_logs.call_args.kwargs["mqtt_resolver"]
+    assert resolver(None) == ["192.168.2.50", "192.168.2.51"]
+    mock_mqtt_get_ip.assert_called_once_with(
+        CORE.config, "user", "pass", "client", stop_event=None
     )
 
 
@@ -5238,7 +5329,9 @@ def test_upload_program_ota_mqtt_timeout_fallback(
     assert host == "192.168.1.100"
 
     # Verify MQTT was attempted
-    mock_mqtt_get_ip.assert_called_once_with(config, "user", "pass", "client")
+    mock_mqtt_get_ip.assert_called_once_with(
+        config, "user", "pass", "client", stop_event=None
+    )
 
     # Verify espota2.run_ota was called with only the static IP (MQTT failed)
     expected_firmware = (
@@ -5254,7 +5347,7 @@ def test_show_logs_api_mqtt_timeout_fallback(
     mock_run_logs: Mock,
     mock_mqtt_get_ip: Mock,
 ) -> None:
-    """Test show_logs falls back to other devices when MQTT times out."""
+    """Test show_logs proceeds with the static IP when MQTT times out."""
     setup_core(
         config={
             "logger": {},
@@ -5273,15 +5366,17 @@ def test_show_logs_api_mqtt_timeout_fallback(
 
     result = show_logs(CORE.config, args, devices)
 
-    # Should succeed using the static IP even though MQTT failed
+    # Logs start on the static IP without waiting for the broker
     assert result == 0
+    mock_run_logs.assert_called_once()
+    assert mock_run_logs.call_args.args == (CORE.config, ["192.168.1.100"])
 
-    # Verify MQTT was attempted
-    mock_mqtt_get_ip.assert_called_once_with(CORE.config, "user", "pass", "client")
-
-    # Verify run_logs was called with only the static IP (MQTT failed)
-    mock_run_logs.assert_called_once_with(
-        CORE.config, ["192.168.1.100"], subscribe_states=True
+    # The deferred resolver owns the failure policy: it logs a warning and
+    # returns no addresses so the session keeps running on the known ones
+    resolver = mock_run_logs.call_args.kwargs["mqtt_resolver"]
+    assert resolver(None) == []
+    mock_mqtt_get_ip.assert_called_once_with(
+        CORE.config, "user", "pass", "client", stop_event=None
     )
 
 
@@ -6764,7 +6859,7 @@ def test_command_run_passes_no_states_to_show_logs(
 
     assert result == 0
     mock_run_logs.assert_called_once_with(
-        CORE.config, ["192.168.1.100"], subscribe_states=False
+        CORE.config, ["192.168.1.100"], subscribe_states=False, mqtt_resolver=None
     )
 
 
@@ -6805,7 +6900,7 @@ def test_command_run_defaults_subscribe_states_true(
 
     assert result == 0
     mock_run_logs.assert_called_once_with(
-        CORE.config, ["192.168.1.100"], subscribe_states=True
+        CORE.config, ["192.168.1.100"], subscribe_states=True, mqtt_resolver=None
     )
 
 

tests/unit_tests/test_mqtt.py

@@ -2,6 +2,11 @@
 
 from __future__ import annotations
 
+import json
+import threading
+import time
+from unittest.mock import MagicMock, patch
+
 import pytest
 
 from esphome.const import CONF_BROKER, CONF_ESPHOME, CONF_MQTT, CONF_NAME
@@ -89,3 +94,260 @@ def test_get_esphome_device_ip_missing_name() -> None:
         match="Cannot discover IP via MQTT as the config does not include the device name:",
     ):
         get_esphome_device_ip(config)
+
+
+def _discovery_config() -> dict:
+    return {
+        CONF_MQTT: {
+            CONF_BROKER: "mqtt.local",
+        },
+        CONF_ESPHOME: {
+            CONF_NAME: "test-device",
+        },
+    }
+
+
+def _deliver_on_loop_start(mock_prepare, client, payload: bytes) -> None:
+    """Deliver a discovery answer as soon as the network loop starts."""
+
+    def deliver(*args, **kwargs):
+        msg = MagicMock()
+        msg.payload = payload
+        mock_prepare.call_args.args[2](client, None, msg)
+
+    client.loop_start.side_effect = deliver
+
+
+def test_get_esphome_device_ip_success() -> None:
+    """A device answer on the discovery topic returns its IPs."""
+    client = MagicMock()
+
+    with patch("esphome.mqtt.prepare", return_value=client) as mock_prepare:
+        _deliver_on_loop_start(
+            mock_prepare,
+            client,
+            json.dumps(
+                {"name": "test-device", "ip": "10.0.0.5", "ip1": "10.0.0.6"}
+            ).encode(),
+        )
+
+        result = get_esphome_device_ip(_discovery_config())
+
+    assert result == ["10.0.0.5", "10.0.0.6"]
+    client.loop_stop.assert_called_once_with()
+    # Once from on_message on receiving the answer, once from the finally
+    assert client.disconnect.call_count == 2
+
+
+def test_get_esphome_device_ip_preset_stop_event_skips_lookup() -> None:
+    """A stop event set before the call returns [] without touching the broker."""
+    stop_event = threading.Event()
+    stop_event.set()
+
+    with patch("esphome.mqtt.prepare") as mock_prepare:
+        result = get_esphome_device_ip(_discovery_config(), stop_event=stop_event)
+
+    assert result == []
+    mock_prepare.assert_not_called()
+
+
+def test_get_esphome_device_ip_stop_event_aborts_wait() -> None:
+    """A stop event set mid-wait exits quietly with no addresses."""
+    stop_event = threading.Event()
+    client = MagicMock()
+    # Simulate teardown starting right after the network loop spins up
+    client.loop_start.side_effect = stop_event.set
+
+    start = time.monotonic()
+    with patch("esphome.mqtt.prepare", return_value=client):
+        result = get_esphome_device_ip(_discovery_config(), stop_event=stop_event)
+
+    # An abort is not a failure and must be nowhere near the 25s timeout
+    assert result == []
+    assert time.monotonic() - start < 5
+    client.disconnect.assert_called_once_with()
+    client.loop_stop.assert_called_once_with()
+
+
+def test_get_esphome_device_ip_timeout_raises() -> None:
+    """No answer within the timeout raises EsphomeError (default stop event path)."""
+    client = MagicMock()
+    with (
+        patch("esphome.mqtt.prepare", return_value=client),
+        pytest.raises(EsphomeError, match="Failed to find IP via MQTT"),
+    ):
+        get_esphome_device_ip(_discovery_config(), timeout=0.25)
+
+    client.disconnect.assert_called_once_with()
+    client.loop_stop.assert_called_once_with()
+
+
+def test_get_esphome_device_ip_stop_during_connect_skips_wait() -> None:
+    """A stop event set while the broker connect is in flight still cleans up."""
+    stop_event = threading.Event()
+    client = MagicMock()
+
+    def prepare_and_stop(*args):
+        stop_event.set()
+        return client
+
+    with patch("esphome.mqtt.prepare", side_effect=prepare_and_stop):
+        result = get_esphome_device_ip(_discovery_config(), stop_event=stop_event)
+
+    assert result == []
+    client.loop_start.assert_not_called()
+    client.disconnect.assert_called_once_with()
+    client.loop_stop.assert_called_once_with()
+
+
+def test_get_esphome_device_ip_replaces_reconnect_handler(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """The one-shot discovery client must not inherit the reconnect-forever
+    handler, which would make loop_stop() join the network thread forever;
+    its replacement still reports a broker-initiated disconnect."""
+    client = MagicMock()
+    prepare_handler = MagicMock()
+    client.on_disconnect = prepare_handler
+
+    with (
+        patch("esphome.mqtt.prepare", return_value=client),
+        pytest.raises(EsphomeError, match="Failed to find IP via MQTT"),
+    ):
+        get_esphome_device_ip(_discovery_config(), timeout=0.25)
+
+    assert client.on_disconnect is not prepare_handler
+    client.on_disconnect(client, None, 0)
+    assert "Disconnected from MQTT broker" not in caplog.text
+    client.on_disconnect(client, None, 5)
+    assert "Disconnected from MQTT broker (5)" in caplog.text
+
+
+def test_get_esphome_device_ip_answer_without_ip_fails_fast(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A device answer with no IP fields fails promptly, not at the timeout."""
+    client = MagicMock()
+
+    with patch("esphome.mqtt.prepare", return_value=client) as mock_prepare:
+        _deliver_on_loop_start(
+            mock_prepare, client, json.dumps({"name": "test-device"}).encode()
+        )
+
+        start = time.monotonic()
+        with pytest.raises(EsphomeError, match="Failed to find IP via MQTT"):
+            get_esphome_device_ip(_discovery_config(), timeout=5)
+
+    assert time.monotonic() - start < 1
+    assert "Device answer did not include an IP address" in caplog.text
+
+
+@pytest.mark.parametrize("payload", [b"not json {", b"123", b"null"])
+def test_get_esphome_device_ip_unparsable_payload_ignored(
+    caplog: pytest.LogCaptureFixture,
+    payload: bytes,
+) -> None:
+    """Garbage on the discovery topic must not kill paho's network thread."""
+    client = MagicMock()
+
+    with patch("esphome.mqtt.prepare", return_value=client) as mock_prepare:
+        _deliver_on_loop_start(mock_prepare, client, payload)
+
+        with pytest.raises(EsphomeError, match="Failed to find IP via MQTT"):
+            get_esphome_device_ip(_discovery_config(), timeout=0)
+
+    assert "Ignoring unparsable discovery payload" in caplog.text
+
+
+def test_get_esphome_device_ip_broker_disconnect_fails_fast(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A broker-initiated disconnect aborts the wait instead of timing out."""
+    client = MagicMock()
+
+    with patch("esphome.mqtt.prepare", return_value=client):
+
+        def drop_connection(*args, **kwargs):
+            client.on_disconnect(client, None, 5)
+
+        client.loop_start.side_effect = drop_connection
+
+        start = time.monotonic()
+        with pytest.raises(EsphomeError, match="Failed to find IP via MQTT"):
+            get_esphome_device_ip(_discovery_config(), timeout=5)
+
+    assert time.monotonic() - start < 1
+    assert "Disconnected from MQTT broker (5)" in caplog.text
+
+
+def test_get_esphome_device_ip_sends_discovery_ping() -> None:
+    """Connecting publishes the discovery ping for the device."""
+    client = MagicMock()
+
+    with patch("esphome.mqtt.prepare", return_value=client) as mock_prepare:
+
+        def connect_then_answer(*args, **kwargs):
+            on_connect = mock_prepare.call_args.args[3]
+            on_connect(client, None, None, 0)
+            msg = MagicMock()
+            msg.payload = json.dumps({"name": "test-device", "ip": "10.0.0.5"}).encode()
+            mock_prepare.call_args.args[2](client, None, msg)
+
+        client.loop_start.side_effect = connect_then_answer
+
+        result = get_esphome_device_ip(_discovery_config())
+
+    assert result == ["10.0.0.5"]
+    client.publish.assert_called_once_with(
+        "esphome/ping/test-device", None, retain=False
+    )
+
+
+def test_get_esphome_device_ip_disconnect_error_does_not_mask_result(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A cleanup failure must not replace the discovery result."""
+    client = MagicMock()
+    # First disconnect (from on_message) succeeds; the finally's fails
+    client.disconnect.side_effect = [None, OSError("socket already closed")]
+
+    with patch("esphome.mqtt.prepare", return_value=client) as mock_prepare:
+        _deliver_on_loop_start(
+            mock_prepare,
+            client,
+            json.dumps({"name": "test-device", "ip": "10.0.0.5"}).encode(),
+        )
+
+        result = get_esphome_device_ip(_discovery_config())
+
+    assert result == ["10.0.0.5"]
+    client.loop_stop.assert_called_once_with()
+
+
+def test_get_esphome_device_ip_invalid_address_values_skipped(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Non-string or non-printable ip values are skipped, valid ones kept."""
+    client = MagicMock()
+
+    with patch("esphome.mqtt.prepare", return_value=client) as mock_prepare:
+        _deliver_on_loop_start(
+            mock_prepare,
+            client,
+            json.dumps(
+                {
+                    "name": "test-device",
+                    "ip": 1234,
+                    "ip1": "x\n[00:00:00][I][forged] fake line",
+                    "ip2": "  10.0.0.5  ",
+                }
+            ).encode(),
+        )
+
+        result = get_esphome_device_ip(_discovery_config())
+
+    assert result == ["10.0.0.5"]
+    assert caplog.text.count("Ignoring invalid address in discovery answer") == 2
+    assert "forged" not in "".join(
+        r.getMessage() for r in caplog.records if "Found IP" in r.getMessage()
+    )

tests/unit_tests/test_platformio_toolchain.py

@@ -2,13 +2,14 @@
 
 # pylint: disable=protected-access
 
-from collections.abc import Generator
+from collections.abc import Callable, Generator
 from contextlib import contextmanager
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 import json
 import os
 from pathlib import Path
 import shutil
+import subprocess
 import sys
 import threading
 from types import SimpleNamespace
@@ -431,10 +432,12 @@ def test_ccache_env_enabled_by_default(setup_core: Path) -> None:
     with (
         patch.dict(os.environ, {}, clear=True),
         patch.object(toolchain.shutil, "which", return_value="/usr/bin/ccache"),
+        patch.object(toolchain.subprocess, "run"),
     ):
         env = toolchain._ccache_env()
 
     assert env["ESPHOME_CCACHE_ENABLE"] == "1"
+    assert env["ESPHOME_CCACHE_PATH"] == "/usr/bin/ccache"
     assert env["CCACHE_BASEDIR"] == str((setup_core / "build" / "test").resolve())
     assert env["CCACHE_DIR"].endswith("platformio-ccache")
     assert env["CCACHE_NOHASHDIR"] == "true"
@@ -444,17 +447,106 @@ def test_ccache_env_enabled_by_default(setup_core: Path) -> None:
     assert "ESPHOME_CCACHE_ENABLE" not in os.environ
 
 
-def test_ccache_env_disabled_without_binary(setup_core: Path) -> None:
-    """Ccache stays off when the binary is not on PATH."""
+@pytest.mark.parametrize(
+    ("env_vars", "expect_warning"),
+    [
+        pytest.param({}, False, id="default"),
+        pytest.param({"ESPHOME_CCACHE_ENABLE": "1"}, True, id="forced-on"),
+    ],
+)
+def test_ccache_env_disabled_without_binary(
+    setup_core: Path,
+    caplog: pytest.LogCaptureFixture,
+    env_vars: dict[str, str],
+    expect_warning: bool,
+) -> None:
+    """Ccache stays off when the binary is not on PATH, even when forced on.
+
+    A deliberate opt-in that finds no binary is downgraded with a warning so
+    the user can tell why it had no effect; the default path stays quiet.
+    """
     CORE.build_path = setup_core / "build" / "test"
 
     with (
-        patch.dict(os.environ, {}, clear=True),
+        patch.dict(os.environ, env_vars, clear=True),
         patch.object(toolchain.shutil, "which", return_value=None),
+        caplog.at_level("WARNING"),
     ):
         env = toolchain._ccache_env()
 
     assert env == {"ESPHOME_CCACHE_ENABLE": "0"}
+    assert ("no ccache binary is on PATH" in caplog.text) is expect_warning
+
+
+@pytest.mark.parametrize(
+    "probe_error",
+    [
+        pytest.param(OSError("not runnable"), id="oserror"),
+        pytest.param(subprocess.CalledProcessError(1, "ccache"), id="nonzero-exit"),
+        pytest.param(subprocess.TimeoutExpired("ccache", 15), id="timeout"),
+    ],
+)
+def test_ccache_env_disabled_when_probe_fails(
+    setup_core: Path, probe_error: Exception
+) -> None:
+    """A ccache that resolves on PATH but fails to run stays disabled."""
+    CORE.build_path = setup_core / "build" / "test"
+
+    with (
+        patch.dict(os.environ, {}, clear=True),
+        patch.object(toolchain.shutil, "which", return_value="/usr/bin/ccache"),
+        patch.object(toolchain.subprocess, "run", side_effect=probe_error),
+    ):
+        env = toolchain._ccache_env()
+
+    assert env == {"ESPHOME_CCACHE_ENABLE": "0"}
+
+
+def test_ccache_env_forced_on_skips_probe(setup_core: Path) -> None:
+    """An explicit ESPHOME_CCACHE_ENABLE=1 does not probe the binary."""
+    CORE.build_path = setup_core / "build" / "test"
+
+    with (
+        patch.dict(os.environ, {"ESPHOME_CCACHE_ENABLE": "1"}, clear=True),
+        patch.object(toolchain.shutil, "which", return_value="/usr/bin/ccache"),
+        patch.object(toolchain.subprocess, "run") as mock_probe,
+    ):
+        env = toolchain._ccache_env()
+
+    assert env["ESPHOME_CCACHE_ENABLE"] == "1"
+    # The binary's location is still handed to the build script.
+    assert env["ESPHOME_CCACHE_PATH"] == "/usr/bin/ccache"
+    mock_probe.assert_not_called()
+
+
+def test_ccache_env_strips_win_long_path_prefix(setup_core: Path) -> None:
+    r"""A ``\\?\`` ccache path from PATH is exported without the prefix.
+
+    That is the shape ESPHome Desktop puts on PATH (#18399); see ``_ccache_env``.
+    """
+    CORE.build_path = setup_core / "build" / "test"
+    prefixed = (
+        "\\\\?\\C:\\Users\\jesse\\AppData\\Local\\ESPHome Device Builder"
+        "\\ccache\\ccache.exe"
+    )
+    stripped = (
+        "C:\\Users\\jesse\\AppData\\Local\\ESPHome Device Builder\\ccache\\ccache.exe"
+    )
+
+    with (
+        patch.dict(os.environ, {}, clear=True),
+        # shutil.which is patched, so the win32 code path of the real
+        # implementation (which crashes on a POSIX host) is never reached.
+        patch("esphome.platformio.toolchain.sys.platform", "win32"),
+        patch.object(toolchain.shutil, "which", return_value=prefixed),
+        patch.object(toolchain.subprocess, "run") as mock_probe,
+    ):
+        env = toolchain._ccache_env()
+
+    assert env["ESPHOME_CCACHE_ENABLE"] == "1"
+    assert env["ESPHOME_CCACHE_PATH"] == stripped
+    # The probe validates the exact string the build will execute.
+    assert mock_probe.call_args[0][0] == [stripped, "--version"]
 
 
 def test_ccache_env_opt_out(setup_core: Path) -> None:
@@ -476,7 +568,7 @@ def test_ccache_env_normalizes_enable_value(setup_core: Path) -> None:
 
     with (
         patch.dict(os.environ, {"ESPHOME_CCACHE_ENABLE": "yes"}, clear=True),
-        patch.object(toolchain.shutil, "which", return_value=None),
+        patch.object(toolchain.shutil, "which", return_value="/usr/bin/ccache"),
     ):
         env = toolchain._ccache_env()
 
@@ -496,6 +588,7 @@ def test_ccache_env_respects_user_values_and_refreshes_basedir(
     with (
         patch.dict(os.environ, user_env, clear=True),
         patch.object(toolchain.shutil, "which", return_value="/usr/bin/ccache"),
+        patch.object(toolchain.subprocess, "run"),
     ):
         env = toolchain._ccache_env()
 
@@ -514,6 +607,7 @@ def test_run_platformio_cli_passes_ccache_env_to_subprocess_only(
     with (
         patch.dict(os.environ, {}, clear=False),
         patch.object(toolchain.shutil, "which", return_value="/usr/bin/ccache"),
+        patch.object(toolchain.subprocess, "run"),
     ):
         os.environ.pop("ESPHOME_CCACHE_ENABLE", None)
         mock_run_external_process.return_value = 0
@@ -521,8 +615,10 @@ def test_run_platformio_cli_passes_ccache_env_to_subprocess_only(
 
         env = mock_run_external_process.call_args[1]["env"]
         assert env["ESPHOME_CCACHE_ENABLE"] == "1"
+        assert env["ESPHOME_CCACHE_PATH"] == "/usr/bin/ccache"
         assert env["CCACHE_BASEDIR"] == str((setup_core / "build" / "test").resolve())
         assert "ESPHOME_CCACHE_ENABLE" not in os.environ
+        assert "ESPHOME_CCACHE_PATH" not in os.environ
         assert "CCACHE_BASEDIR" not in os.environ
 
 
@@ -533,6 +629,7 @@ def test_ccache_env_requires_build_path(setup_core: Path) -> None:
     with (
         patch.dict(os.environ, {}, clear=True),
         patch.object(toolchain.shutil, "which", return_value="/usr/bin/ccache"),
+        patch.object(toolchain.subprocess, "run"),
         pytest.raises(ValueError, match="CORE.build_path must be set"),
     ):
         toolchain._ccache_env()
@@ -544,7 +641,10 @@ def test_run_platformio_cli_merges_caller_env(
     """A caller-supplied env is the base and gains the ccache settings."""
     CORE.build_path = str(setup_core / "build" / "test")
 
-    with patch.object(toolchain.shutil, "which", return_value="/usr/bin/ccache"):
+    with (
+        patch.object(toolchain.shutil, "which", return_value="/usr/bin/ccache"),
+        patch.object(toolchain.subprocess, "run"),
+    ):
         mock_run_external_process.return_value = 0
         toolchain.run_platformio_cli(
             "test", env={"CUSTOM_VAR": "1", "ESPHOME_CCACHE_ENABLE": "0"}
@@ -567,6 +667,182 @@ def test_copy_ccache_script(setup_core: Path) -> None:
     assert dest.read_text() == source.read_text()
 
 
+class _FakeSConsEnv(dict):
+    """Just enough of a SCons construction environment for ccache.py."""
+
+    def Replace(self, **kwargs: object) -> None:  # noqa: N802
+        self.update(kwargs)
+
+
+def _load_ccache_script(
+    env_vars: dict[str, str], original_spawn: Callable[..., int] | None = None
+) -> tuple[_FakeSConsEnv, Callable[..., int]]:
+    """Run ccache.py.script against a fake SCons env and return (env, original SPAWN)."""
+    if original_spawn is None:
+        original_spawn = Mock(name="original_spawn", return_value=0)
+    scons_env = _FakeSConsEnv(SPAWN=original_spawn)
+    source = (Path(toolchain.__file__).parent / "ccache.py.script").read_text()
+    with patch.dict(os.environ, env_vars, clear=True):
+        exec(  # noqa: S102
+            compile(source, "ccache.py", "exec"),
+            {"Import": lambda *_names: None, "env": scons_env},
+        )
+    return scons_env, original_spawn
+
+
+def _scons_win32_escape(x: str) -> str:
+    """Copy of ``SCons.Platform.win32.escape``: quote, guarding a trailing backslash."""
+    if x[-1] == "\\":
+        x = x + "\\"
+    return '"' + x + '"'
+
+
+def test_ccache_script_wraps_compiles_with_exported_path() -> None:
+    """The SCons script uses ESPHOME_CCACHE_PATH as given, without a PATH lookup."""
+    ccache_path = "C:\\Users\\jesse\\ESPHome Device Builder\\ccache\\ccache.exe"
+    scons_env, original_spawn = _load_ccache_script(
+        {"ESPHOME_CCACHE_ENABLE": "1", "ESPHOME_CCACHE_PATH": ccache_path}
+    )
+    spawn = scons_env["SPAWN"]
+    assert spawn is not original_spawn
+
+    # A compile step is routed through ccache, with the same path used for
+    # the program and (escaped) as the first argument.
+    compile_args = ["xtensa-lx106-elf-g++", "-o", "main.o", "-c", "main.cpp"]
+    spawn("cmd.exe", _scons_win32_escape, "xtensa-lx106-elf-g++", compile_args, {})
+    original_spawn.assert_called_once_with(
+        "cmd.exe",
+        _scons_win32_escape,
+        ccache_path,
+        [_scons_win32_escape(ccache_path), *compile_args],
+        {},
+    )
+
+    # Link steps pass through untouched.
+    original_spawn.reset_mock()
+    link_args = ["xtensa-lx106-elf-g++", "-o", "firmware.elf", "main.o"]
+    spawn("cmd.exe", _scons_win32_escape, "xtensa-lx106-elf-g++", link_args, {})
+    original_spawn.assert_called_once_with(
+        "cmd.exe", _scons_win32_escape, "xtensa-lx106-elf-g++", link_args, {}
+    )
+
+
+@pytest.mark.parametrize(
+    "env_vars",
+    [
+        pytest.param({"ESPHOME_CCACHE_ENABLE": "0"}, id="disabled"),
+        pytest.param({"ESPHOME_CCACHE_ENABLE": "1"}, id="enabled-without-path"),
+        pytest.param({}, id="unset"),
+    ],
+)
+def test_ccache_script_leaves_spawn_alone_without_path(
+    env_vars: dict[str, str],
+) -> None:
+    """Without both the enable flag and a path, SPAWN is not replaced."""
+    scons_env, original_spawn = _load_ccache_script(env_vars)
+    assert scons_env["SPAWN"] is original_spawn
+
+
+def _scons_win32_spawn(
+    sh: str, escape: Callable[[str], str], cmd: str, args: list[str], env: dict
+) -> int:
+    r"""Mirror of ``SCons.Platform.win32.spawn``: every command runs via ``cmd.exe /C``.
+
+    SCons is not importable in the test environment (PlatformIO fetches it at
+    build time), so the lines that matter are mirrored here. The command line
+    SCons hands ``os.spawnve`` goes to ``CreateProcess`` via ``subprocess``
+    instead (identical on Windows, where a string passes through untouched);
+    ``spawnve`` itself crashes inside pytest.
+    """
+    return subprocess.run(
+        " ".join([sh, "/C", escape(" ".join(args))]), env=env, check=False
+    ).returncode
+
+
+_MARKER_ENV = "ESPHOME_TEST_CCACHE_MARKER"
+# Stands in for a compile: the "ccache" is really the Python interpreter, and
+# the compile "flags" make it write a marker file so the test can tell whether
+# the wrapped command actually ran to completion.
+_FAKE_COMPILE_ARGS = [
+    "-c",
+    f"import os, pathlib; pathlib.Path(os.environ['{_MARKER_ENV}']).write_text('compiled')",
+]
+
+
+def _spawn_fake_compile_via_cmd_exe(scons_env: _FakeSConsEnv, marker: Path) -> int:
+    """Run one wrapped compile step the way SCons does on Windows."""
+    child_env = {**os.environ, _MARKER_ENV: str(marker)}
+    return scons_env["SPAWN"](
+        os.environ.get("COMSPEC", "cmd.exe"),
+        _scons_win32_escape,
+        "xtensa-lx106-elf-gcc",
+        [_scons_win32_escape(arg) if " " in arg else arg for arg in _FAKE_COMPILE_ARGS],
+        child_env,
+    )
+
+
+_WINDOWS_ONLY = pytest.mark.skipif(
+    sys.platform != "win32", reason="drives cmd.exe, which SCons uses only on Windows"
+)
+
+
+@_WINDOWS_ONLY
+def test_ccache_env_real_probe_runs_stripped_path(setup_core: Path) -> None:
+    r"""With a ``\\?\`` which result, the real probe runs the stripped binary.
+
+    The probe therefore validates the exact string the build will execute
+    through ``cmd.exe``; probing the verbatim path instead would pass even
+    when the stripped path is unusable (``CreateProcess`` accepts
+    extended-length paths, ``cmd.exe`` does not).
+    """
+    CORE.build_path = setup_core / "build" / "test"
+    assert not sys.executable.startswith("\\\\?\\")
+
+    with (
+        patch.dict(os.environ, {}, clear=False),
+        patch.object(
+            toolchain.shutil, "which", return_value="\\\\?\\" + sys.executable
+        ),
+    ):
+        os.environ.pop("ESPHOME_CCACHE_ENABLE", None)
+        env = toolchain._ccache_env()
+
+    assert env["ESPHOME_CCACHE_ENABLE"] == "1"
+    assert env["ESPHOME_CCACHE_PATH"] == sys.executable
+
+
+@_WINDOWS_ONLY
+@pytest.mark.parametrize(
+    ("prefix", "expect_ok"),
+    [
+        pytest.param("", True, id="stripped-path-compiles"),
+        pytest.param("\\\\?\\", False, id="verbatim-path-fails"),
+    ],
+)
+def test_ccache_wrapper_through_cmd_exe(
+    tmp_path: Path, prefix: str, expect_ok: bool
+) -> None:
+    r"""End to end through ``cmd.exe``: the exported path works, a ``\\?\`` one does not.
+
+    The interpreter stands in for ccache; the spawn mirrors SCons on Windows.
+    The failing case is the mechanism behind #18399 ("The system cannot find
+    the path specified." on every compile step); should it ever start passing,
+    ``cmd.exe`` learned extended-length paths and the strip is no longer needed.
+    """
+    marker = tmp_path / "compiled.txt"
+    scons_env, _ = _load_ccache_script(
+        {"ESPHOME_CCACHE_ENABLE": "1", "ESPHOME_CCACHE_PATH": prefix + sys.executable},
+        original_spawn=_scons_win32_spawn,
+    )
+    assert scons_env["SPAWN"] is not _scons_win32_spawn
+
+    rc = _spawn_fake_compile_via_cmd_exe(scons_env, marker)
+    assert (rc == 0) is expect_ok
+    assert marker.exists() is expect_ok
+    if expect_ok:
+        assert marker.read_text() == "compiled"
+
+
 @pytest.mark.parametrize(
     ("platform", "input_path", "expected"),
     [

tests/unit_tests/test_preference_hash_stability.py

@@ -5,11 +5,11 @@ users to lose stored preferences (calibration values, restore states, etc.) on
 firmware upgrades, or break entity state routing to API clients.
 
 Two algorithms are locked here (see https://github.com/esphome/backlog/issues/85):
-1. `fnv1_hash_object_id(name)` - the LEGACY hash (snake_case + sanitize, then FNV-1).
-   Existing devices have preferences stored under keys derived from it; slot-based
-   backends (ESP8266, RP2040) keep using it, and key-lookup backends migrate FROM it.
-2. `fnv1_hash_name(name)` - the entity key (FNV-1 over the raw UTF-8 name bytes).
-   Sent to API clients and used as the preference key base on key-lookup backends.
+1. `fnv1_hash_object_id(name)` - the object_id hash (snake_case + sanitize, then FNV-1).
+   The entity key sent to API clients and the base of every stored preference key.
+2. `fnv1_hash_name(name)` - FNV-1 over the raw UTF-8 name bytes. 2026.8 beta
+   firmware stored preferences under keys derived from it; a future key migration
+   must reconstruct those keys to recover that data.
 
 DO NOT CHANGE THE EXPECTED VALUES - if tests fail after modifying a hash algorithm,
 the change breaks backward compatibility and will cause data loss.
@@ -124,8 +124,9 @@ def test_entity_object_id_hash_stability(
     """Verify fnv1_hash_object_id produces stable hashes for entity names.
 
     CRITICAL: These expected values MUST NOT CHANGE. Existing devices have
-    preferences stored under keys derived from this legacy hash; changing it
-    breaks the old-to-new key migration and loses stored preferences.
+    preferences stored under keys derived from this hash, and it is the entity
+    key sent to API clients; changing it loses stored preferences and breaks
+    entity state routing.
     """
     actual = fnv1_hash_object_id(entity_name)
     assert actual == expected_object_id_hash, (
@@ -144,9 +145,8 @@ def compute_legacy_preference_key(
 ) -> int:
     """Compute the legacy preference key: (object_id_hash ^ device_id) ^ version.
 
-    This is the key existing devices have data stored under. Slot-based backends
-    (ESP8266, RP2040) still use it directly; key-lookup backends compute it as the
-    migration source in EntityBase::make_entity_preference_() (entity_base.cpp).
+    This is the key EntityBase::make_entity_preference_() (entity_base.cpp)
+    stores every entity preference under.
     """
     object_id_hash = fnv1_hash_object_id(entity_name)
     preference_hash = object_id_hash ^ device_id
@@ -179,8 +179,8 @@ def test_legacy_preference_key_computation(
 ) -> None:
     """Verify legacy preference key computation matches expected values.
 
-    This test ensures the formula doesn't change, which would break both slot-based
-    preference storage and the migration source keys on key-lookup backends.
+    This test ensures the formula doesn't change, which would lose stored
+    preferences on every platform.
     """
     actual_key = compute_legacy_preference_key(entity_name, version, device_id)
 
@@ -215,12 +215,12 @@ def test_legacy_preference_key_computation(
     ],
 )
 def test_entity_key_hash_stability(entity_name: str, expected_key: int) -> None:
-    """Verify fnv1_hash_name produces stable entity keys.
+    """Verify fnv1_hash_name produces stable raw-name hashes.
 
-    CRITICAL: These expected values MUST NOT CHANGE. The entity key is sent to
-    API clients and is the new preference key base; changing the algorithm
-    would break state routing and lose stored preferences.
-    Must match C++ fnv1_hash_bytes() in esphome/core/helpers.h.
+    CRITICAL: These expected values MUST NOT CHANGE. 2026.8 beta firmware stored
+    preferences under keys derived from this hash; a future key migration must
+    reconstruct those keys, and changing the algorithm would strand that data.
+    Matched C++ fnv1_hash_bytes() (2026.8 beta), which the unrevert restores.
     """
     actual = fnv1_hash_name(entity_name)
     assert actual == expected_key, (

tests/unit_tests/test_storage_json.py

@@ -915,3 +915,102 @@ def test_storage_json_load_area(tmp_path: Path) -> None:
     legacy = storage_json.StorageJSON.load(legacy_path)
     assert legacy is not None
     assert legacy.area is None
+
+
+def test_from_esphome_core_without_claiming_a_build(setup_core: Path) -> None:
+    """claim_build=False carries the build artifact fields from the old
+    sidecar while validation-derived fields still stamp from CORE."""
+    mock_core = MagicMock()
+    mock_core.name = "my_device"
+    mock_core.friendly_name = "My Device"
+    mock_core.comment = None
+    mock_core.address = "my_device.local"
+    mock_core.web_port = None
+    mock_core.target_platform = "esp8266"
+    mock_core.is_esp32 = False
+    mock_core.is_nrf52 = False
+    mock_core.build_path = "/build/my_device"
+    mock_core.loaded_integrations = set()
+    mock_core.loaded_platforms = set()
+    mock_core.config = {}
+    mock_core.target_framework = "arduino"
+    mock_core.toolchain = Toolchain.PLATFORMIO
+    mock_core.area = None
+
+    old = storage_json.StorageJSON.from_wizard(
+        name="my_device",
+        friendly_name="My Device",
+        address="my_device.local",
+        platform="ESP8266",
+    )
+    old.esphome_version = "2025.1.0"
+    old.firmware_bin_path = Path("/old/firmware.bin")
+
+    result = storage_json.StorageJSON.from_esphome_core(
+        mock_core, old, claim_build=False
+    )
+
+    # Build artifact fields carry from the old sidecar, not this run.
+    assert result.esphome_version == "2025.1.0"
+    assert result.firmware_bin_path == Path("/old/firmware.bin")
+    # Validation-derived fields stamp from CORE.
+    assert result.build_path == "/build/my_device"
+    assert result.toolchain == "platformio"
+    assert result.core_platform == "esp8266"
+
+    # With no old sidecar, no build is claimed at all.
+    bare = storage_json.StorageJSON.from_esphome_core(
+        mock_core, None, claim_build=False
+    )
+    assert bare.esphome_version is None
+    assert bare.firmware_bin_path is None
+
+
+def test_load_strict_distinguishes_missing_from_unreadable(tmp_path: Path) -> None:
+    """load_strict returns None only for a missing file; corrupt raises."""
+    assert storage_json.StorageJSON.load_strict(tmp_path / "missing.json") is None
+
+    corrupt = tmp_path / "corrupt.json"
+    corrupt.write_text("{truncated")
+    with pytest.raises(ValueError):
+        storage_json.StorageJSON.load_strict(corrupt)
+
+
+def test_as_dict_serializes_unset_paths_as_null(setup_core: Path) -> None:
+    """Unset build/firmware paths serialize as JSON null, not str(None)."""
+    storage = storage_json.StorageJSON.from_wizard(
+        name="wiz",
+        friendly_name="Wiz",
+        address="wiz.local",
+        platform="ESP32",
+    )
+
+    result = storage.as_dict()
+
+    assert result["build_path"] is None
+    assert result["firmware_bin_path"] is None
+
+
+def test_load_treats_legacy_none_string_paths_as_unset(tmp_path: Path) -> None:
+    """Sidecars written before as_dict emitted null hold str(None); those
+    must load as unset, not as Path("None")."""
+    file_path = tmp_path / "legacy_none.json"
+    file_path.write_text(
+        json.dumps(
+            {
+                "storage_version": 1,
+                "name": "wiz",
+                "friendly_name": "Wiz",
+                "esp_platform": "ESP32",
+                "core_platform": "esp32",
+                "build_path": "None",
+                "firmware_bin_path": "None",
+            }
+        )
+    )
+
+    result = storage_json.StorageJSON.load(file_path)
+
+    assert result is not None
+    assert result.build_path is None
+    assert result.firmware_bin_path is None

tests/unit_tests/test_vscode.py

@@ -3,6 +3,8 @@ from pathlib import Path
 from unittest.mock import Mock, patch
 
 from esphome import vscode
+import esphome.config_validation as cv
+from esphome.core import EsphomeError
 
 
 def _run_repl_test(input_data):
@@ -126,3 +128,67 @@ packages:
     assert range["start_col"] == 2
     assert range["end_line"] == 1
     assert range["end_col"] == 7
+
+
+def _explode(*_args: object, **_kwargs: object) -> None:
+    raise AttributeError("'NoneType' object has no attribute 'get'")
+
+
+def test_unexpected_error_reports_origin() -> None:
+    source_path = str(Path("dir_path", "x.yaml"))
+    with patch("esphome.vscode.validate_config", _explode):
+        output_lines = _run_repl_test(
+            [
+                _validate(source_path),
+                _file_response("""esphome:
+  name: test1
+"""),
+            ]
+        )
+
+    result = json.loads(output_lines[-1])
+    assert result["validation_errors"] == []
+    (error,) = result["yaml_errors"]
+    assert error["message"].startswith(
+        "Unexpected error while validating: AttributeError: "
+        "'NoneType' object has no attribute 'get' ("
+    )
+    assert "test_vscode.py" in error["message"]
+    assert error["message"].endswith(" in _explode)")
+
+
+def test_esphome_error_stays_plain() -> None:
+    source_path = str(Path("dir_path", "x.yaml"))
+    with patch("esphome.vscode.validate_config", side_effect=EsphomeError("boom")):
+        output_lines = _run_repl_test(
+            [
+                _validate(source_path),
+                _file_response("""esphome:
+  name: test1
+"""),
+            ]
+        )
+
+    result = json.loads(output_lines[-1])
+    assert result["yaml_errors"] == [{"message": "boom"}]
+
+
+def test_invalid_stays_plain() -> None:
+    source_path = str(Path("dir_path", "x.yaml"))
+    with patch("esphome.vscode.validate_config", side_effect=cv.Invalid("bad value")):
+        output_lines = _run_repl_test(
+            [
+                _validate(source_path),
+                _file_response("""esphome:
+  name: test1
+"""),
+            ]
+        )
+
+    result = json.loads(output_lines[-1])
+    assert result["yaml_errors"] == [{"message": "bad value"}]
+
+
+def test_format_unexpected_error_without_traceback() -> None:
+    message = vscode._format_unexpected_error(ValueError("boom"))
+    assert message == "Unexpected error while validating: ValueError: boom"