[espidf] Install native ESP-IDF into a machine-global cache dir (#17306)

tests/unit_tests/test_espidf_framework.py

@@ -36,6 +36,19 @@ from esphome.espidf.framework import (
 from esphome.framework_helpers import _tar_extract_all, get_python_env_executable_path
 
 
+@pytest.fixture(autouse=True)
+def _isolate_idf_install_path(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Pin the ESP-IDF install root to a tmp dir for every test.
+
+    The default location is the OS user cache dir, so without this any test
+    that builds framework paths or pre-creates the framework dir would touch
+    the real ``~/.cache/esphome`` on the developer's machine. Tests that need
+    to exercise the override or default-resolution logic clear/override the env
+    themselves.
+    """
+    monkeypatch.setenv("ESPHOME_ESP_IDF_PREFIX", str(tmp_path / "idf_install"))
+
+
 @pytest.mark.parametrize(
     ("source", "expected"),
     [
@@ -791,6 +804,38 @@ def test_get_idf_tools_path_env_override(tmp_path: Path) -> None:
         assert _get_idf_tools_path() == Path(override)
 
 
+@pytest.mark.parametrize("value", ["", "   "])
+def test_get_idf_tools_path_blank_env_falls_back_to_default(
+    value: str, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A blank ESPHOME_ESP_IDF_PREFIX is treated as unset, not as CWD.
+
+    Path("") would resolve to the working directory, which clean-all could then
+    delete by accident.
+    """
+    import platformdirs
+
+    monkeypatch.setenv("ESPHOME_ESP_IDF_PREFIX", value)
+    expected = (
+        Path(platformdirs.user_cache_dir("esphome", appauthor=False)) / "idf"
+    ).resolve()
+    assert _get_idf_tools_path() == expected
+
+
+def test_get_idf_tools_path_default_uses_user_cache(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Without the env override the install root is the machine-global OS user
+    cache dir, not the per-config ``<data_dir>/idf``."""
+    import platformdirs
+
+    monkeypatch.delenv("ESPHOME_ESP_IDF_PREFIX", raising=False)
+    expected = (
+        Path(platformdirs.user_cache_dir("esphome", appauthor=False)) / "idf"
+    ).resolve()
+    assert _get_idf_tools_path() == expected
+
+
 def test_write_idf_version_txt_warns_on_write_error(tmp_path: Path) -> None:
     with patch("pathlib.Path.write_text", side_effect=OSError("denied")):
         # write failure is caught and warned, not raised
@@ -908,3 +953,5 @@ def test_check_windows_path_length_long_path_warns(
     message = caplog.records[0].getMessage()
     assert _LONG_IDF_PATH in message
     assert "long path support" in message
+    # The install is global now; the remedy is the prefix env, not moving the project.
+    assert "ESPHOME_ESP_IDF_PREFIX" in message

tests/unit_tests/test_writer.py

@@ -67,15 +67,23 @@ def _isolate_platformio_paths(tmp_path_factory: pytest.TempPathFactory) -> Any:
     want to verify the PIO-cleanup branch (e.g. test_clean_all,
     test_clean_all_partial_exists) install their own inner patch which
     stacks on top of this one and wins for the duration of their block.
+
+    Also pin ``ESPHOME_ESP_IDF_PREFIX`` to a nonexistent tmp dir for the
+    same reason: ``clean_all`` removes the now machine-global ESP-IDF
+    install, which otherwise defaults to the real ``~/.cache/esphome``.
     """
     pio_root = tmp_path_factory.mktemp("isolated_pio") / "nonexistent"
+    idf_root = tmp_path_factory.mktemp("isolated_idf") / "nonexistent"
     mock_cfg = MagicMock()
     mock_cfg.get.side_effect = lambda section, option: (
         str(pio_root / option) if section == "platformio" else ""
     )
-    with patch(
-        "platformio.project.config.ProjectConfig.get_instance",
-        return_value=mock_cfg,
+    with (
+        patch(
+            "platformio.project.config.ProjectConfig.get_instance",
+            return_value=mock_cfg,
+        ),
+        patch.dict("os.environ", {"ESPHOME_ESP_IDF_PREFIX": str(idf_root)}),
     ):
         yield
 
@@ -990,6 +998,30 @@ def test_clean_all_with_yaml_file(
     assert str(build_dir) in caplog.text
 
 
+@patch("esphome.writer.CORE")
+def test_clean_all_removes_global_idf_install(
+    mock_core: MagicMock,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """clean_all removes the machine-global native ESP-IDF install dir."""
+    idf_install = tmp_path / "idf_install"
+    (idf_install / "frameworks").mkdir(parents=True)
+    monkeypatch.setenv("ESPHOME_ESP_IDF_PREFIX", str(idf_install))
+
+    config_dir = tmp_path / "config"
+    config_dir.mkdir()
+
+    from esphome.writer import clean_all
+
+    with caplog.at_level("INFO"):
+        clean_all([str(config_dir)])
+
+    assert not idf_install.exists()
+    assert str(idf_install.resolve()) in caplog.text
+
+
 @patch("esphome.writer.CORE")
 def test_clean_all_with_yaml_build_path(
     mock_core: MagicMock,