[platformio] Fix ccache path for non-root containers (#19807)

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

tests/unit_tests/test_platformio_toolchain.py

@@ -447,6 +447,47 @@ def test_ccache_env_enabled_by_default(setup_core: Path) -> None:
     assert "ESPHOME_CCACHE_ENABLE" not in os.environ
 
 
+def test_ccache_env_uses_cache_dir_override(setup_core: Path, tmp_path: Path) -> None:
+    """The containers point ccache at their writable cache mount."""
+    CORE.build_path = setup_core / "build" / "test"
+    ccache_dir = tmp_path / "cache" / "platformio-ccache"
+
+    with (
+        patch.dict(
+            os.environ,
+            {"HOME": "/", "ESPHOME_PLATFORMIO_CCACHE_DIR": str(ccache_dir)},
+            clear=True,
+        ),
+        patch("shutil.which", return_value="/usr/bin/ccache"),
+        patch("esphome.framework_helpers.subprocess.run"),
+    ):
+        env = toolchain._ccache_env()
+
+    assert env["CCACHE_DIR"] == str(ccache_dir.resolve())
+
+
+def test_ccache_env_ignores_platformio_cache_dir(
+    setup_core: Path, tmp_path: Path
+) -> None:
+    """PLATFORMIO_CACHE_DIR does not move ccache; only the override does."""
+    CORE.build_path = setup_core / "build" / "test"
+    cache_root = tmp_path / "user-cache"
+
+    with (
+        patch.dict(
+            os.environ,
+            {"PLATFORMIO_CACHE_DIR": str(tmp_path / "platformio" / "cache")},
+            clear=True,
+        ),
+        patch("platformdirs.user_cache_dir", return_value=str(cache_root)),
+        patch("shutil.which", return_value="/usr/bin/ccache"),
+        patch("esphome.framework_helpers.subprocess.run"),
+    ):
+        env = toolchain._ccache_env()
+
+    assert env["CCACHE_DIR"] == str((cache_root / "platformio-ccache").resolve())
+
+
 @pytest.mark.parametrize(
     ("env_vars", "expect_warning"),
     [
@@ -582,6 +623,7 @@ def test_ccache_env_respects_user_values_and_refreshes_basedir(
     user_env = {
         "CCACHE_DIR": "/custom/cache",
         "CCACHE_BASEDIR": "/stale/other-device",
+        "ESPHOME_PLATFORMIO_CCACHE_DIR": "/mounted/platformio-ccache",
     }
     CORE.build_path = setup_core / "build" / "test"
 

tests/unit_tests/test_writer.py

@@ -1085,6 +1085,28 @@ def test_clean_all_removes_global_arduino8266_install(
     assert str(arduino8266_install.resolve()) in caplog.text
 
 
+@patch("esphome.writer.CORE")
+def test_clean_all_removes_platformio_ccache(
+    mock_core: MagicMock,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """clean_all removes the PlatformIO ccache dir the containers relocate."""
+    ccache_dir = tmp_path / "platformio-ccache"
+    (ccache_dir / "0").mkdir(parents=True)
+    monkeypatch.setenv("ESPHOME_PLATFORMIO_CCACHE_DIR", str(ccache_dir))
+
+    config_dir = tmp_path / "config"
+    config_dir.mkdir()
+
+    with caplog.at_level("INFO"):
+        clean_all([str(config_dir)])
+
+    assert not ccache_dir.exists()
+    assert str(ccache_dir.resolve()) in caplog.text
+
+
 @patch("esphome.writer.CORE")
 def test_clean_all_removes_default_cache_root(
     mock_core: MagicMock,