[esp8266] Add native toolchain that builds the Arduino core without PlatformIO (#18539)

tests/unit_tests/components/esp8266/test_toolchain_validation.py

@@ -0,0 +1,197 @@
+"""Tests for the native (non-PlatformIO) toolchain config validation."""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+from esphome.components import esp8266
+from esphome.components.esp8266 import (
+    ARDUINO_FRAMEWORK_SCHEMA,
+    _resolve_toolchain,
+    _validate_native_toolchain,
+)
+import esphome.config_validation as cv
+from esphome.const import (
+    CONF_BOARD,
+    CONF_FRAMEWORK,
+    CONF_PLATFORM_VERSION,
+    CONF_SOURCE,
+    CONF_TOOLCHAIN,
+    CONF_VERSION,
+    KEY_CORE,
+    KEY_TARGET_PLATFORM,
+    PLATFORM_ESP8266,
+    Toolchain,
+)
+from esphome.core import CORE, EsphomeError
+from esphome.types import ConfigType
+
+
+@pytest.fixture(autouse=True)
+def _arduino_toolchain() -> Generator[None]:
+    # The suite-wide reset_core fixture clears both after each test; the
+    # shared backend resolver reads the platform as well as the toolchain,
+    # and the decode-tool cache lives in CORE.data
+    CORE.toolchain = Toolchain.ARDUINO
+    CORE.data.setdefault(KEY_CORE, {})[KEY_TARGET_PLATFORM] = PLATFORM_ESP8266
+    yield
+
+
+def _config(
+    board: str = "nodemcuv2",
+    version: str = "3.1.2",
+    source: str | None = None,
+    platform_version: str | None = None,
+) -> ConfigType:
+    framework: dict[str, str] = {CONF_VERSION: version}
+    if source is not None:
+        framework[CONF_SOURCE] = source
+    if platform_version is not None:
+        framework[CONF_PLATFORM_VERSION] = platform_version
+    # The real schema fills the source/platform_version defaults, so these
+    # tests validate against what config validation actually emits
+    return {
+        CONF_FRAMEWORK: ARDUINO_FRAMEWORK_SCHEMA(framework),
+        CONF_BOARD: board,
+    }
+
+
+def test_valid_config_passes() -> None:
+    config = _config()
+    assert _validate_native_toolchain(config) is config
+
+
+def test_platformio_toolchain_skips_checks() -> None:
+    # 3.0.2 is pio-legal (>= the global 3.0.0 floor) but below the native
+    # toolchain's own 3.1.1 floor; the bogus board only the native path checks
+    CORE.toolchain = Toolchain.PLATFORMIO
+    config = _config(board="not_a_board", version="3.0.2")
+    assert _validate_native_toolchain(config) is config
+
+
+def test_version_below_floor_rejected() -> None:
+    # 3.1.0 has no registry package, so the native floor is 3.1.1
+    with pytest.raises(cv.Invalid, match="3.1.1 or newer"):
+        _validate_native_toolchain(_config(version="3.1.0"))
+
+
+def test_version_at_floor_accepted() -> None:
+    _validate_native_toolchain(_config(version="3.1.1"))
+
+
+def test_custom_platform_version_warns_and_is_dropped(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    config = _config(platform_version="platformio/espressif8266@4.0.1")
+    _validate_native_toolchain(config)
+    assert "'platform_version' is ignored" in caplog.text
+    assert CONF_PLATFORM_VERSION not in config[CONF_FRAMEWORK]
+
+
+def test_default_platform_version_does_not_warn(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    config = _config()
+    _validate_native_toolchain(config)
+    assert "'platform_version' is ignored" not in caplog.text
+    assert CONF_PLATFORM_VERSION not in config[CONF_FRAMEWORK]
+
+
+def test_custom_source_rejected() -> None:
+    with pytest.raises(cv.Invalid, match="custom framework source"):
+        _validate_native_toolchain(
+            _config(source="https://github.com/esp8266/Arduino.git")
+        )
+
+
+def test_unsupported_board_rejected() -> None:
+    with pytest.raises(cv.Invalid, match="not supported by"):
+        _validate_native_toolchain(_config(board="not_a_board"))
+
+
+def test_yaml_toolchain_key_resolves() -> None:
+    """The documented `toolchain: arduino` YAML key selects the native path."""
+    CORE.toolchain = None
+    _resolve_toolchain({CONF_TOOLCHAIN: Toolchain.ARDUINO})
+    assert CORE.toolchain == Toolchain.ARDUINO
+    assert CORE.using_toolchain_arduino
+
+
+def test_yaml_toolchain_key_defaults_to_platformio() -> None:
+    CORE.toolchain = None
+    _resolve_toolchain({})
+    assert CORE.toolchain == Toolchain.PLATFORMIO
+
+
+def test_decode_pc_native_missing_tools_warns_once(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A stack dump of many addresses produces one missing-tool warning."""
+
+    with (
+        patch(
+            "esphome.arduino8266.toolchain.get_addr2line_path",
+            return_value=tmp_path / "missing-addr2line",
+        ),
+        patch(
+            "esphome.arduino8266.toolchain.get_elf_path",
+            return_value=tmp_path / "missing.elf",
+        ),
+    ):
+        esp8266._decode_pc({}, "40201234")
+        esp8266._decode_pc({}, "40201238")
+    assert caplog.text.count("Cannot decode crash addresses") == 1
+
+
+def test_decode_pc_platformio_missing_tools_warns_once(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """The PlatformIO branch reports a missing addr2line/ELF at the same
+    warning level as the native one; raw undecoded addresses with no
+    stated reason are undiagnosable at default log level."""
+
+    CORE.toolchain = Toolchain.PLATFORMIO
+    idedata = SimpleNamespace(addr2line_path=None, firmware_elf_path=None)
+    with patch("esphome.platformio.toolchain.get_idedata", return_value=idedata):
+        esp8266._decode_pc({}, "40201234")
+        esp8266._decode_pc({}, "40201238")
+    assert caplog.text.count("Cannot decode crash addresses") == 1
+
+
+def test_resolve_toolchain_rejects_unsupported() -> None:
+    """ESP8266 rejects a CLI toolchain it cannot serve, like every platform."""
+
+    CORE.toolchain = Toolchain.SDK_NRF
+    with pytest.raises(cv.Invalid, match="Unsupported toolchain 'sdk-nrf'"):
+        _resolve_toolchain({})
+
+
+def test_run_compile_platformio_falls_through() -> None:
+    """Under toolchain: platformio the hook returns False without touching
+    the native backend; this is what keeps existing users on PlatformIO."""
+    CORE.toolchain = Toolchain.PLATFORMIO
+    with patch("esphome.arduino8266.toolchain.run_compile") as mock_native:
+        assert esp8266.run_compile(SimpleNamespace(), {}) is False
+    mock_native.assert_not_called()
+
+
+def test_run_compile_arduino_failure_raises() -> None:
+    """A non-zero native build fails by name instead of returning success."""
+    CORE.verbose = False
+    with (
+        patch("esphome.arduino8266.toolchain.run_compile", return_value=1),
+        pytest.raises(EsphomeError, match="native build failed"),
+    ):
+        esp8266.run_compile(SimpleNamespace(), {})
+
+
+def test_copy_files_native_skips_platformio_scripts(tmp_path: Path) -> None:
+    """The native build writes no PlatformIO extra scripts."""
+    CORE.build_path = tmp_path
+    esp8266.copy_files()
+    assert list(tmp_path.iterdir()) == []

tests/unit_tests/core/test_config.py

@@ -1480,12 +1480,3 @@ async def test_add_platformio_options_native_arduino(
     assert "board_build.ldscript is ignored" in caplog.text
     assert "'arduino' toolchain" in caplog.text
     assert "upload_speed" not in caplog.text
-
-
-def test_esp8266_rejects_unsupported_cli_toolchain() -> None:
-    """Until the native backend lands, ESP8266 serves only PlatformIO."""
-    from esphome.components.esp8266 import CONFIG_SCHEMA
-
-    CORE.toolchain = Toolchain.ARDUINO
-    with pytest.raises(cv.Invalid, match="Unsupported toolchain 'arduino'"):
-        CONFIG_SCHEMA({"board": "nodemcuv2"})

tests/unit_tests/fixtures/lazy_imports/native_upload_fast_path.py

@@ -0,0 +1,65 @@
+"""Run the native-toolchain serial-upload path and report heavy modules.
+
+Executed as a subprocess by test_lazy_imports.py: heavy module names come
+in on argv, the ones found in sys.modules afterwards go out on stdout.
+``upload_using_esptool`` dispatches native toolchains through a
+toolchain-keyed table; if someone routes it back through the platform
+component packages (esp32 or esp8266), this reports the leak.
+"""
+
+import os
+from pathlib import Path
+import sys
+import tempfile
+from unittest.mock import patch
+
+from _leak_report import print_leaked_modules
+
+from esphome.__main__ import upload_using_esptool
+from esphome.const import (
+    CONF_ESPHOME,
+    KEY_CORE,
+    KEY_ESP32,
+    KEY_TARGET_PLATFORM,
+    KEY_VARIANT,
+    Toolchain,
+)
+from esphome.core import CORE
+
+# An ambient ESPHOME_USE_SUBPROCESS would route past the patched
+# run_external_command into run_external_process and confuse the checks.
+os.environ.pop("ESPHOME_USE_SUBPROCESS", None)
+
+config = {CONF_ESPHOME: {"platformio_options": {}}}
+
+with tempfile.TemporaryDirectory() as build_dir:
+    CORE.name = "leaktest"
+    CORE.build_path = build_dir
+
+    for platform, toolchain, backend in (
+        ("esp8266", Toolchain.ARDUINO, "esphome.arduino8266.toolchain"),
+        ("esp32", Toolchain.ESP_IDF, "esphome.espidf.toolchain"),
+    ):
+        CORE.data[KEY_CORE] = {KEY_TARGET_PLATFORM: platform}
+        if platform == "esp32":
+            CORE.data[KEY_ESP32] = {KEY_VARIANT: "ESP32S3"}
+        CORE.toolchain = toolchain
+
+        import importlib
+
+        image = importlib.import_module(backend).get_factory_firmware_path()
+        image.parent.mkdir(parents=True, exist_ok=True)
+        image.write_bytes(b"\x00")
+
+        with patch("esphome.__main__.run_external_command", return_value=0) as mock_run:
+            rc = upload_using_esptool(config, "/dev/ttyUSB0", None, None)
+
+        # Fail loudly if the upload path stopped doing its work; otherwise
+        # an empty leak list could just mean nothing ran.
+        if rc != 0:
+            sys.exit(f"upload_using_esptool({platform}) returned {rc}")
+        cmd = list(mock_run.call_args[0][1:])
+        if str(image) not in [str(Path(c)) for c in cmd]:
+            sys.exit(f"native factory image did not reach esptool: {cmd}")
+
+print_leaked_modules()

tests/unit_tests/test_arduino8266_toolchain.py

@@ -0,0 +1,548 @@
+"""Tests for esphome.arduino8266.toolchain (the ninja build driver)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import subprocess
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from esphome.arduino8266 import framework, toolchain
+import esphome.config_validation as cv
+from esphome.const import (
+    CONF_COMPILE_PROCESS_LIMIT,
+    CONF_ESPHOME,
+    KEY_CORE,
+    KEY_FRAMEWORK_VERSION,
+)
+from esphome.core import CORE, EsphomeError
+
+_SIZE_OUTPUT = """\
+firmware.elf  :
+section       size    addr
+.data         1924    1073643520
+.noinit       56      1073645444
+.text         496     1074790400
+.irom0.text   342804  1075843088
+.text1        27489   1074790896
+.rodata       2588    1073645504
+.bss          26504   1073648096
+Total         401861
+"""
+
+
+@pytest.fixture(autouse=True)
+def _setup_core(tmp_path: Path) -> None:
+    CORE.name = "test8266"
+    CORE.config_path = tmp_path / "test8266.yaml"
+    CORE.build_path = tmp_path
+    CORE.data[KEY_CORE] = {KEY_FRAMEWORK_VERSION: cv.Version(3, 1, 2)}
+    # run_compile verifies the produced artifacts; give every test a build
+    # that "produced" them (tests for the guard delete them again). The
+    # manifest comes first: artifacts must not be older than build.ninja.
+    build_dir = CORE.relative_pioenvs_path("test8266")
+    build_dir.mkdir(parents=True, exist_ok=True)
+    (build_dir / "build.ninja").write_text("# manifest")
+    for artifact in (
+        "firmware.elf",
+        "firmware.bin",
+        "firmware.factory.bin",
+        "firmware.ota.bin",
+    ):
+        (build_dir / artifact).write_bytes(b"")
+
+
+def _paths(tmp_path: Path) -> framework.InstalledPaths:
+    return framework.InstalledPaths(
+        framework=tmp_path / "framework",
+        toolchain=tmp_path / "toolchain",
+        ninja=tmp_path / "ninja",
+    )
+
+
+def test_path_getters(tmp_path: Path) -> None:
+    assert toolchain.get_build_dir() == CORE.relative_pioenvs_path("test8266")
+    assert toolchain.get_elf_path().name == "firmware.elf"
+    # The framework accessor owns the layout and the Windows suffix
+    suffix = ".exe" if os.name == "nt" else ""
+    assert toolchain.get_addr2line_path().name == f"xtensa-lx106-elf-addr2line{suffix}"
+    assert toolchain.get_objdump_path().name == f"xtensa-lx106-elf-objdump{suffix}"
+    assert toolchain.get_readelf_path().name == f"xtensa-lx106-elf-readelf{suffix}"
+
+
+def test_run_compile_build_failure(tmp_path: Path) -> None:
+    with (
+        patch.object(framework, "check_and_install", return_value=_paths(tmp_path)),
+        patch.object(framework, "get_build_env", return_value={}),
+        patch("esphome.build_gen.arduino8266.write_project"),
+        patch.object(
+            toolchain.subprocess, "run", return_value=MagicMock(returncode=2)
+        ) as mock_run,
+        patch.object(toolchain, "_write_compile_commands") as mock_compdb,
+    ):
+        assert toolchain.run_compile({CONF_ESPHOME: {}}, verbose=True) == 2
+    cmd = mock_run.call_args[0][0]
+    assert "-v" in cmd
+    # The compile database is generated before the build runs, so a failed
+    # build cannot leave a stale database behind.
+    mock_compdb.assert_called_once()
+
+
+def test_run_compile_success(tmp_path: Path) -> None:
+    with (
+        patch.object(framework, "check_and_install", return_value=_paths(tmp_path)),
+        patch.object(framework, "get_build_env", return_value={}),
+        patch("esphome.build_gen.arduino8266.write_project", return_value=False),
+        patch.object(
+            toolchain.subprocess,
+            "run",
+            return_value=MagicMock(returncode=0, stdout="", stderr=""),
+        ) as mock_run,
+        patch.object(toolchain, "_write_compile_commands") as mock_compdb,
+        patch.object(toolchain, "_print_size_summary") as mock_size,
+        patch.object(toolchain, "get_idedata") as mock_idedata,
+    ):
+        rc = toolchain.run_compile(
+            {CONF_ESPHOME: {CONF_COMPILE_PROCESS_LIMIT: 4}}, verbose=False
+        )
+    assert rc == 0
+    call = next(c for c in mock_run.call_args_list if "ninja" in str(c[0][0][0]))
+    cmd = call[0][0]
+    # Explicit targets: a manifest missing them fails as "unknown target"
+    assert {"firmware.factory.bin", "firmware.ota.bin"} <= set(cmd)
+    assert cmd[cmd.index("-j") + 1] == "4"
+    # cwd, not -C, so ninja prints no "Entering directory" banner
+    assert "-C" not in cmd
+    assert call[1]["cwd"] is not None
+    mock_compdb.assert_called_once()
+    mock_size.assert_called_once()
+    mock_idedata.assert_called_once()
+
+
+def test_run_compile_regenerates_stale_compdb(tmp_path: Path) -> None:
+    """An interrupted run can leave build.ninja newer than the compile DB;
+    mere existence must not skip regeneration."""
+    build_dir = toolchain.get_build_dir()
+    build_dir.mkdir(parents=True, exist_ok=True)
+    (build_dir / "build.ninja").write_text("")
+    compdb = build_dir / "compile_commands.json"
+    compdb.write_text("[]")
+    os.utime(compdb, ((build_dir / "build.ninja").stat().st_mtime - 5,) * 2)
+    with (
+        patch.object(framework, "check_and_install", return_value=_paths(tmp_path)),
+        patch.object(framework, "get_build_env", return_value={}),
+        patch("esphome.build_gen.arduino8266.write_project", return_value=False),
+        patch.object(
+            toolchain.subprocess,
+            "run",
+            return_value=MagicMock(
+                returncode=0, stdout="ninja: no work to do.\n", stderr=""
+            ),
+        ),
+        patch.object(toolchain, "_write_compile_commands") as mock_compdb,
+        patch.object(toolchain, "_print_size_summary"),
+        patch.object(toolchain, "get_idedata"),
+    ):
+        assert toolchain.run_compile({CONF_ESPHOME: {}}, verbose=False) == 0
+    mock_compdb.assert_called_once()
+
+
+def test_run_compile_missing_artifact_fails(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A zero ninja exit that produced no firmware must not be a green
+    build (size summary and idedata only warn)."""
+    (toolchain.get_build_dir() / "firmware.elf").unlink()
+    with (
+        patch.object(framework, "check_and_install", return_value=_paths(tmp_path)),
+        patch.object(framework, "get_build_env", return_value={}),
+        patch("esphome.build_gen.arduino8266.write_project"),
+        patch.object(
+            toolchain.subprocess,
+            "run",
+            return_value=MagicMock(returncode=0, stdout="", stderr=""),
+        ),
+        patch.object(toolchain, "_write_compile_commands"),
+        patch.object(toolchain, "_print_size_summary") as mock_size,
+        patch.object(toolchain, "get_idedata"),
+    ):
+        rc = toolchain.run_compile({CONF_ESPHOME: {}}, verbose=False)
+    assert rc == 1
+    assert "Build produced no" in caplog.text
+    mock_size.assert_not_called()
+
+
+def test_run_compile_warns_when_idedata_fails(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A failed idedata generation right after a successful build is visible,
+    not deferred to a misleading error in a later command."""
+    with (
+        patch.object(framework, "check_and_install", return_value=_paths(tmp_path)),
+        patch.object(framework, "get_build_env", return_value={}),
+        patch("esphome.build_gen.arduino8266.write_project"),
+        patch.object(
+            toolchain.subprocess,
+            "run",
+            return_value=MagicMock(returncode=0, stdout="", stderr=""),
+        ),
+        patch.object(toolchain, "_write_compile_commands"),
+        patch.object(toolchain, "_print_size_summary"),
+        patch.object(toolchain, "get_idedata", return_value=None),
+    ):
+        assert toolchain.run_compile({CONF_ESPHOME: {}}, verbose=False) == 0
+    assert "No idedata was generated for this build" in caplog.text
+
+
+def test_write_compile_commands(tmp_path: Path) -> None:
+    build_dir = tmp_path / "build"
+    build_dir.mkdir()
+    entries = '[{"file": "a.cpp", "command": "cc"}]\n'
+    with patch.object(
+        toolchain.subprocess,
+        "run",
+        return_value=MagicMock(returncode=0, stdout=entries),
+    ):
+        toolchain._write_compile_commands(tmp_path / "ninja", build_dir, {})
+    assert (build_dir / "compile_commands.json").read_text() == entries
+
+
+@pytest.mark.parametrize(
+    ("stdout", "match"),
+    [
+        ("[]\n", "empty compile database"),
+        # A parse failure names its cause, not the rule-name story
+        ("not json", "unparsable compile database.*not json"),
+    ],
+)
+def test_write_compile_commands_bad_db_raises(
+    tmp_path: Path, stdout: str, match: str
+) -> None:
+    """An empty or unparsable compile database fails the build with its
+    actual cause and drops any stale database."""
+    build_dir = tmp_path / "build"
+    build_dir.mkdir()
+    (build_dir / "compile_commands.json").write_text("[stale]")
+    with (
+        patch.object(
+            toolchain.subprocess,
+            "run",
+            return_value=MagicMock(returncode=0, stdout=stdout),
+        ),
+        pytest.raises(EsphomeError, match=match),
+    ):
+        toolchain._write_compile_commands(tmp_path / "ninja", build_dir, {})
+    assert not (build_dir / "compile_commands.json").exists()
+
+
+def test_write_compile_commands_failure_removes_stale_db(tmp_path: Path) -> None:
+    """A failed compdb run must not leave a stale database behind."""
+    stale = tmp_path / "compile_commands.json"
+    stale.write_text("[]")
+    with (
+        patch.object(
+            toolchain.subprocess,
+            "run",
+            return_value=MagicMock(returncode=1, stderr="boom"),
+        ),
+        pytest.raises(EsphomeError, match="compile_commands"),
+    ):
+        toolchain._write_compile_commands(tmp_path / "ninja", tmp_path, {})
+    assert not stale.exists()
+
+
+def test_parse_app_size(tmp_path: Path) -> None:
+    ld = tmp_path / "eagle.flash.4m.ld"
+    ld.write_text("MEMORY\n{\n  irom0_0_seg :  org = 0x40201010, len = 0xfeff0\n}\n")
+    with patch("esphome.build_gen.arduino8266.get_flash_ld_path", return_value=ld):
+        assert toolchain._parse_app_size(tmp_path, _paths(tmp_path)) == 0xFEFF0
+
+    ld.write_text("MEMORY { }\n")
+    with patch("esphome.build_gen.arduino8266.get_flash_ld_path", return_value=ld):
+        assert toolchain._parse_app_size(tmp_path, _paths(tmp_path)) is None
+
+    # A zero-length segment is bad data, not a budget; warn and drop it
+    ld.write_text("MEMORY\n{\n  irom0_0_seg :  org = 0x40201010, len = 0x0\n}\n")
+    with patch("esphome.build_gen.arduino8266.get_flash_ld_path", return_value=ld):
+        assert toolchain._parse_app_size(tmp_path, _paths(tmp_path)) is None
+
+    with patch(
+        "esphome.build_gen.arduino8266.get_flash_ld_path",
+        return_value=tmp_path / "missing.ld",
+    ):
+        assert toolchain._parse_app_size(tmp_path, _paths(tmp_path)) is None
+
+
+def test_print_size_summary(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    with (
+        patch.object(
+            toolchain.subprocess,
+            "run",
+            return_value=MagicMock(returncode=0, stdout=_SIZE_OUTPUT),
+        ),
+        patch.object(toolchain, "_parse_app_size", return_value=1044464),
+    ):
+        toolchain._print_size_summary(tmp_path, _paths(tmp_path))
+    out = capsys.readouterr().out
+    # Exact PlatformIO shape so script/ci_memory_impact_extract.py can parse it
+    assert "RAM:   [====      ]  37.9% (used 31016 bytes from 81920 bytes)" in out
+    assert "Flash: [====      ]  35.9% (used 375301 bytes from 1044464 bytes)" in out
+
+
+def test_print_size_summary_missing_size_tool_warns(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A missing size binary degrades to a warning; the firmware already
+    linked and must not be discarded."""
+    with patch.object(
+        toolchain.subprocess, "run", side_effect=FileNotFoundError("no size")
+    ):
+        toolchain._print_size_summary(tmp_path, _paths(tmp_path))
+    assert "Could not summarize firmware size" in caplog.text
+
+
+def test_print_size_summary_no_app_size(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    with (
+        patch.object(
+            toolchain.subprocess,
+            "run",
+            return_value=MagicMock(returncode=0, stdout=_SIZE_OUTPUT),
+        ),
+        patch.object(toolchain, "_parse_app_size", return_value=None),
+    ):
+        toolchain._print_size_summary(tmp_path, _paths(tmp_path))
+    out = capsys.readouterr().out
+    # Both lines are skipped together: a RAM line without Flash would skew
+    # CI's memory-impact sums across builds
+    assert out == ""
+
+
+def test_print_size_summary_size_tool_failure(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    with patch.object(
+        toolchain.subprocess,
+        "run",
+        side_effect=subprocess.CalledProcessError(1, "size", stderr="bad elf"),
+    ):
+        toolchain._print_size_summary(tmp_path, _paths(tmp_path))
+    assert capsys.readouterr().out == ""
+    assert "Could not summarize firmware size" in caplog.text
+
+
+def test_get_idedata_delegates(tmp_path: Path) -> None:
+    with (
+        patch(
+            "esphome.build_helpers.idedata.load_or_build_idedata",
+            return_value={"cc_path": "x"},
+        ) as mock_load,
+        patch.object(toolchain, "resolve_ccache_path", return_value="/cc/ccache"),
+    ):
+        assert toolchain.get_idedata() == {"cc_path": "x"}
+    compile_commands, elf, cache = mock_load.call_args[0]
+    assert compile_commands.name == "compile_commands.json"
+    assert elf.name == "firmware.elf"
+    assert cache.name == "test8266.arduino.json"
+    # The exact configured launcher string is passed for compile DB parsing
+    # (resolve_ccache_path returns a str, untouched on every platform)
+    assert mock_load.call_args.kwargs["launcher"] == "/cc/ccache"
+
+
+def test_get_idedata_no_ccache(tmp_path: Path) -> None:
+    with (
+        patch(
+            "esphome.build_helpers.idedata.load_or_build_idedata", return_value={}
+        ) as mock_load,
+        patch.object(toolchain, "resolve_ccache_path", return_value=None),
+    ):
+        toolchain.get_idedata()
+    assert mock_load.call_args.kwargs["launcher"] is None
+
+
+def test_run_compile_skips_compdb_when_ninja_unchanged(tmp_path: Path) -> None:
+    """An unchanged build.ninja means the compile DB is already current."""
+    build_dir = toolchain.get_build_dir()
+    build_dir.mkdir(parents=True, exist_ok=True)
+    # write_project (stubbed below) always leaves a build.ninja behind
+    (build_dir / "build.ninja").write_text("# manifest")
+
+    def run(regenerate_expected: bool) -> None:
+        with (
+            patch.object(framework, "check_and_install", return_value=_paths(tmp_path)),
+            patch.object(framework, "get_build_env", return_value={}),
+            patch("esphome.build_gen.arduino8266.write_project", return_value=False),
+            patch.object(
+                toolchain.subprocess,
+                "run",
+                return_value=MagicMock(returncode=0, stdout="", stderr=""),
+            ),
+            patch.object(toolchain, "_write_compile_commands") as mock_compdb,
+            patch.object(toolchain, "_print_size_summary"),
+            patch.object(toolchain, "get_idedata"),
+        ):
+            assert toolchain.run_compile({CONF_ESPHOME: {}}, verbose=False) == 0
+        assert mock_compdb.called == regenerate_expected
+
+    # Missing compile DB: regenerated even though build.ninja is unchanged
+    run(regenerate_expected=True)
+    # Present compile DB + unchanged build.ninja: skipped
+    (build_dir / "compile_commands.json").write_text("[]")
+    run(regenerate_expected=False)
+
+
+def test_print_size_summary_unparsable_section(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A totals-relevant section that fails to parse must not produce a
+    confident wrong number; an irrelevant one is ignored."""
+    bad = _SIZE_OUTPUT.replace(".bss          26504", ".bss          abc")
+    with patch.object(
+        toolchain.subprocess,
+        "run",
+        return_value=MagicMock(returncode=0, stdout=bad),
+    ):
+        toolchain._print_size_summary(tmp_path, _paths(tmp_path))
+    assert capsys.readouterr().out == ""
+    assert "missing section(s) .bss" in caplog.text
+
+    caplog.clear()
+    harmless = _SIZE_OUTPUT + ".broken   abc   0\n"
+    with (
+        patch.object(
+            toolchain.subprocess,
+            "run",
+            return_value=MagicMock(returncode=0, stdout=harmless),
+        ),
+        patch.object(toolchain, "_parse_app_size", return_value=1044464),
+    ):
+        toolchain._print_size_summary(tmp_path, _paths(tmp_path))
+    assert "RAM:" in capsys.readouterr().out
+    assert not caplog.text
+
+
+def test_print_size_summary_missing_section_skips_summary(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A totals section absent from the output must not default to zero."""
+    without_bss = "\n".join(
+        line for line in _SIZE_OUTPUT.splitlines() if ".bss" not in line
+    )
+    with patch.object(
+        toolchain.subprocess,
+        "run",
+        return_value=MagicMock(returncode=0, stdout=without_bss),
+    ):
+        toolchain._print_size_summary(tmp_path, _paths(tmp_path))
+    assert capsys.readouterr().out == ""
+    assert "missing section(s) .bss" in caplog.text
+
+
+def test_warn_ignored_platformio_options(caplog: pytest.LogCaptureFixture) -> None:
+    """Component-added options the native build drops are warned by name;
+    the honored ones (lib_ignore, f_cpu, ldscript, build_src_flags,
+    flash_mode) stay quiet."""
+    CORE.platformio_options = {
+        "board_build.ldscript": "eagle.flash.4m2m.ld",
+        "board_build.f_cpu": "160000000L",
+        "board_build.filesystem": "littlefs",
+        "board_build.flash_mode": "dio",
+        "build_src_flags": "-include throw_stubs.h",
+        "lib_ignore": ["Updater"],
+        "upload_speed": "460800",
+    }
+    toolchain._warn_ignored_platformio_options()
+    assert "platformio_options->board_build.filesystem is ignored" in caplog.text
+    assert "native 'arduino' toolchain" in caplog.text
+    assert "board_build.ldscript is ignored" not in caplog.text
+    assert "board_build.f_cpu is ignored" not in caplog.text
+    assert "lib_ignore" not in caplog.text
+    assert "build_src_flags" not in caplog.text
+    assert "flash_mode" not in caplog.text
+    # Component-added upload_speed never gets read under the native
+    # toolchain, so it must warn
+    assert "upload_speed" in caplog.text
+
+
+def test_run_compile_idedata_error_does_not_fail_build(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """An unusable compile DB after a successful build warns, never fails."""
+    with (
+        patch.object(framework, "check_and_install", return_value=_paths(tmp_path)),
+        patch.object(framework, "get_build_env", return_value={}),
+        patch("esphome.build_gen.arduino8266.write_project"),
+        patch.object(
+            toolchain.subprocess,
+            "run",
+            return_value=MagicMock(returncode=0, stdout="", stderr=""),
+        ),
+        patch.object(toolchain, "_write_compile_commands"),
+        patch.object(toolchain, "_print_size_summary"),
+        patch.object(
+            toolchain,
+            "get_idedata",
+            side_effect=EsphomeError("compile database is unusable"),
+        ),
+    ):
+        assert toolchain.run_compile({CONF_ESPHOME: {}}, verbose=False) == 0
+    assert "Could not generate idedata: compile database is unusable" in caplog.text
+
+
+def test_run_compile_skipped_size_summary_names_consequence(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A skipped RAM/Flash summary warns about the missing metric; the
+    per-cause warnings alone are invisible to CI harnesses."""
+    with (
+        patch.object(framework, "check_and_install", return_value=_paths(tmp_path)),
+        patch.object(framework, "get_build_env", return_value={}),
+        patch("esphome.build_gen.arduino8266.write_project"),
+        patch.object(
+            toolchain.subprocess,
+            "run",
+            return_value=MagicMock(returncode=0, stdout="", stderr=""),
+        ),
+        patch.object(toolchain, "_write_compile_commands"),
+        patch.object(toolchain, "_print_size_summary", return_value=False),
+        patch.object(toolchain, "get_idedata", return_value=None),
+    ):
+        assert toolchain.run_compile({CONF_ESPHOME: {}}, verbose=False) == 0
+    assert "Firmware size summary unavailable for this build" in caplog.text
+
+
+def test_parse_app_size_non_utf8_ld_warns(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A corrupt (non-UTF-8) linker script degrades to the same warning as
+    an unreadable one, never a traceback after a successful link."""
+    paths = _paths(tmp_path)
+    ld = tmp_path / "corrupt.ld"
+    ld.write_bytes(b"\xff\xfe not utf8")
+    with patch("esphome.build_gen.arduino8266.get_flash_ld_path", return_value=ld):
+        assert toolchain._parse_app_size(tmp_path, paths) is None
+    assert "Cannot read linker script" in caplog.text
+
+
+def test_get_idedata_accepts_preresolved_ccache() -> None:
+    """run_compile threads its resolved ccache through; the probe must not
+    run again."""
+    with (
+        patch(
+            "esphome.build_helpers.idedata.load_or_build_idedata",
+            return_value={"ok": True},
+        ) as mock_build,
+        patch.object(toolchain, "resolve_ccache_path") as mock_resolve,
+    ):
+        assert toolchain.get_idedata("/usr/bin/ccache") == {"ok": True}
+    mock_resolve.assert_not_called()
+    assert mock_build.call_args.kwargs["launcher"] == "/usr/bin/ccache"

tests/unit_tests/test_lazy_imports.py

@@ -34,7 +34,12 @@ HEAVY_MODULES = (
 
 # Everything the storage fast path must keep out of sys.modules; the
 # existence guard and the leak check must watch the same list.
-FAST_PATH_HEAVY_MODULES = HEAVY_MODULES + ("esphome.components.esp32",)
+FAST_PATH_HEAVY_MODULES = HEAVY_MODULES + (
+    "esphome.components.esp32",
+    # A native backend module resolves artifact paths on this path; its
+    # framework half pulls in the whole package-download stack
+    "esphome.platformio.registry",
+)
 
 # Heavy only for modules that must not know about the API transport;
 # in the existence guard so a rename can't silently no-op its check.
@@ -175,6 +180,27 @@ def test_esptool_upload_fast_path_does_not_import_heavy_modules(
     )
 
 
+def test_native_upload_fast_path_does_not_import_heavy_modules(
+    fixture_path: Path,
+    probe_env: dict[str, str],
+) -> None:
+    """The native-toolchain serial upload dispatches through a
+    toolchain-keyed backend table; resolving the flash image must not drag
+    in the esp32 or esp8266 component package or the validation stack.
+    """
+    leaked = _leaked_from_fixture(
+        fixture_path,
+        probe_env,
+        "native_upload_fast_path.py",
+        extra=("esphome.components.esp8266",),
+    )
+    assert not leaked, (
+        f"native upload_using_esptool pulls in heavy modules: {leaked}. "
+        "The upload fast path skips validation; importing a platform "
+        "component package executes its codegen module by design."
+    )
+
+
 def test_api_client_does_not_import_heavy_modules() -> None:
     """``esphome.api_client`` is on the logs fast path and must stay light.
 

tests/unit_tests/test_main.py

@@ -13,7 +13,7 @@ import sys
 import time
 from types import SimpleNamespace
 from typing import Any, Self
-from unittest.mock import AsyncMock, MagicMock, Mock, patch
+from unittest.mock import AsyncMock, MagicMock, Mock, PropertyMock, patch
 
 import pytest
 from pytest import CaptureFixture
@@ -7212,7 +7212,7 @@ def test_command_run_rp2040_bootsel_redetects_serial_port() -> None:
 
 def test_command_idedata_esp_idf_prints_json(capsys: CaptureFixture) -> None:
     """Under the native ESP-IDF toolchain, idedata is emitted as JSON."""
-    setup_core()
+    setup_core(platform=PLATFORM_ESP32)
     CORE.toolchain = Toolchain.ESP_IDF
     data = {"cxx_path": "g++", "prog_path": "/build/firmware.elf"}
 
@@ -7226,7 +7226,7 @@ def test_command_idedata_esp_idf_prints_json(capsys: CaptureFixture) -> None:
 
 def test_command_idedata_esp_idf_no_build_errors() -> None:
     """Under ESP-IDF, a missing build (no idedata) returns an error, not a crash."""
-    setup_core()
+    setup_core(platform=PLATFORM_ESP32)
     CORE.toolchain = Toolchain.ESP_IDF
 
     with patch("esphome.espidf.toolchain.get_idedata", return_value=None):
@@ -7400,6 +7400,201 @@ def test_warn_source_tree_mismatch_falls_back_when_stat_fails(
     assert not caplog.text
 
 
+def test_upload_using_esptool_arduino_toolchain(
+    tmp_path: Path,
+    mock_run_external_command_main: Mock,
+) -> None:
+    """The native ESP8266 Arduino toolchain flashes its factory image at
+    0x0, resolved from the toolchain-keyed backend table (deliberately not
+    the platform hook: that import would break the upload fast path)."""
+    setup_core(platform=PLATFORM_ESP8266, tmp_path=tmp_path, name="test")
+    CORE.toolchain = Toolchain.ARDUINO
+    from esphome.arduino8266 import toolchain as native
+
+    factory = native.get_factory_firmware_path()
+    factory.parent.mkdir(parents=True, exist_ok=True)
+    factory.touch()
+
+    config = {CONF_ESPHOME: {"platformio_options": {}}}
+    result = upload_using_esptool(config, "/dev/ttyUSB0", None, None)
+
+    assert result == 0
+    cmd_list = list(mock_run_external_command_main.call_args[0][1:])
+    firmware_offset_idx = cmd_list.index("write-flash") + 4
+    assert cmd_list[firmware_offset_idx] == "0x0"
+    assert cmd_list[firmware_offset_idx + 1] == str(factory)
+
+
+@pytest.mark.parametrize(
+    ("toolchain", "pio_project_written"),
+    [
+        # The native toolchain generates its project at compile time, so
+        # write_cpp_file must not write a platformio.ini; the default
+        # toolchain writes the PlatformIO project files.
+        (Toolchain.ARDUINO, False),
+        (None, True),
+    ],
+)
+def test_write_cpp_file_project_generation_follows_toolchain(
+    tmp_path: Path, toolchain: Toolchain | None, pio_project_written: bool
+) -> None:
+    setup_core(platform=PLATFORM_ESP8266, tmp_path=tmp_path, name="test")
+    CORE.toolchain = toolchain
+
+    with (
+        patch("esphome.writer.write_cpp") as mock_write_cpp,
+        patch("esphome.build_gen.platformio.write_project") as mock_pio_project,
+        patch.object(
+            type(CORE), "cpp_main_section", new_callable=PropertyMock
+        ) as mock_section,
+    ):
+        mock_section.return_value = ""
+        assert main.write_cpp_file() == 0
+
+    mock_write_cpp.assert_called_once()
+    assert mock_pio_project.called is pio_project_written
+
+
+def test_command_idedata_arduino_prints_json(
+    tmp_path: Path, capsys: CaptureFixture
+) -> None:
+    """Under the native ESP8266 Arduino toolchain, idedata is emitted as JSON."""
+    setup_core(platform=PLATFORM_ESP8266, tmp_path=tmp_path)
+    CORE.toolchain = Toolchain.ARDUINO
+    data = {"cxx_path": "g++", "prog_path": "/build/firmware.elf"}
+
+    with patch(
+        "esphome.arduino8266.toolchain.get_idedata", return_value=data
+    ) as mock_get:
+        result = command_idedata(MagicMock(), CORE.config)
+
+    assert result == 0
+    mock_get.assert_called_once_with()
+    assert json.loads(capsys.readouterr().out) == data
+
+
+def test_command_idedata_arduino_no_build_errors(tmp_path: Path) -> None:
+    """A missing native build (no idedata) returns an error, not a crash."""
+    setup_core(platform=PLATFORM_ESP8266, tmp_path=tmp_path)
+    CORE.toolchain = Toolchain.ARDUINO
+
+    with patch("esphome.arduino8266.toolchain.get_idedata", return_value=None):
+        result = command_idedata(MagicMock(), CORE.config)
+
+    assert result == 1
+
+
+@pytest.mark.parametrize(
+    ("platform", "toolchain", "module"),
+    [
+        (PLATFORM_ESP8266, Toolchain.ARDUINO, "esphome.arduino8266.toolchain"),
+        (PLATFORM_ESP32, Toolchain.ESP_IDF, "esphome.espidf.toolchain"),
+    ],
+)
+def test_command_analyze_memory_native_toolchains(
+    tmp_path: Path,
+    mock_write_cpp: Mock,
+    mock_compile_program: Mock,
+    mock_get_esphome_components: Mock,
+    mock_memory_analyzer_cli: Mock,
+    mock_ram_strings_analyzer: Mock,
+    platform: str,
+    toolchain: Toolchain,
+    module: str,
+) -> None:
+    """analyze-memory uses the native toolchain's binutils instead of
+    falling into the PlatformIO branch."""
+    setup_core(platform=platform, tmp_path=tmp_path, name="test_device")
+    CORE.toolchain = toolchain
+
+    config = {CONF_ESPHOME: {CONF_NAME: "test_device"}}
+    # The tools must exist: a missing binutils now fails by name instead of
+    # silently falling back to host tools
+    objdump = tmp_path / "objdump"
+    readelf = tmp_path / "readelf"
+    objdump.write_text("")
+    readelf.write_text("")
+    # The ELF must exist too: the analyzer swallows tool failures, so a
+    # missing image would report zeroes with exit 0
+    firmware_elf = tmp_path / "firmware.elf"
+    firmware_elf.write_text("")
+    with (
+        patch(f"{module}.get_objdump_path", return_value=objdump),
+        patch(f"{module}.get_readelf_path", return_value=readelf),
+        patch(f"{module}.get_elf_path", return_value=firmware_elf),
+    ):
+        result = command_analyze_memory(MockArgs(), config)
+
+    assert result == 0
+    mock_memory_analyzer_cli.assert_called_once_with(
+        str(firmware_elf),
+        str(objdump),
+        str(readelf),
+        set(),
+        idedata=None,
+    )
+
+
+def test_command_analyze_memory_native_missing_elf_fails(
+    tmp_path: Path,
+    mock_write_cpp: Mock,
+    mock_compile_program: Mock,
+    mock_get_esphome_components: Mock,
+    mock_memory_analyzer_cli: Mock,
+    mock_ram_strings_analyzer: Mock,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A missing firmware.elf fails by name instead of an exit-0 zeroed
+    report."""
+    setup_core(platform=PLATFORM_ESP8266, tmp_path=tmp_path, name="test_device")
+    CORE.toolchain = Toolchain.ARDUINO
+
+    config = {CONF_ESPHOME: {CONF_NAME: "test_device"}}
+    objdump = tmp_path / "objdump"
+    readelf = tmp_path / "readelf"
+    objdump.write_text("")
+    readelf.write_text("")
+    module = "esphome.arduino8266.toolchain"
+    with (
+        patch(f"{module}.get_objdump_path", return_value=objdump),
+        patch(f"{module}.get_readelf_path", return_value=readelf),
+        patch(f"{module}.get_elf_path", return_value=tmp_path / "missing.elf"),
+    ):
+        result = command_analyze_memory(MockArgs(), config)
+
+    assert result == 1
+    assert "compile the configuration first" in caplog.text
+    mock_memory_analyzer_cli.assert_not_called()
+
+
+def test_command_analyze_memory_missing_binutils_fails_by_name(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A truncated toolchain install fails naming the missing tool instead
+    of silently analyzing with host binutils."""
+    setup_core(platform="esp8266", tmp_path=tmp_path, name="test_device")
+    CORE.toolchain = Toolchain.ARDUINO
+    config = {CONF_ESPHOME: {CONF_NAME: "test_device"}}
+    module = "esphome.arduino8266.toolchain"
+    with (
+        patch(f"{module}.get_objdump_path", return_value=tmp_path / "missing-objdump"),
+        patch(f"{module}.get_readelf_path", return_value=tmp_path / "readelf"),
+        patch("esphome.__main__.write_cpp", return_value=0),
+        patch("esphome.__main__.compile_program", return_value=0),
+    ):
+        assert command_analyze_memory(MockArgs(), config) == 1
+    assert "missing-objdump" in caplog.text
+    assert "toolchain install may be incomplete" in caplog.text
+
+
+def test_command_idedata_incompatible_toolchain(tmp_path: Path) -> None:
+    """A non-native, non-platformio toolchain errors out cleanly."""
+    setup_core(platform=PLATFORM_ESP32, tmp_path=tmp_path)
+    CORE.toolchain = Toolchain.SDK_NRF
+
+    assert command_idedata(MagicMock(), CORE.config) == 1
+
+
 @pytest.mark.parametrize(
     "error",
     [
@@ -7476,6 +7671,49 @@ def test_compile_program_espidf_idedata_none_warns(
     assert "No idedata was generated" in caplog.text
 
 
+def test_native_toolchain_table_serves_every_native_toolchain() -> None:
+    """Every member of NATIVE_TOOLCHAINS has a backend entry; a gap would
+    surface as a targeted EsphomeError on the one affected config, and this
+    pin keeps the table from drifting when a toolchain is added."""
+    from esphome.build_helpers.native import NATIVE_TOOLCHAIN_MODULES
+    from esphome.const import NATIVE_TOOLCHAINS
+
+    assert {tc for _, tc in NATIVE_TOOLCHAIN_MODULES} == set(NATIVE_TOOLCHAINS)
+
+
+def test_native_toolchain_module_missing_backend_raises(tmp_path: Path) -> None:
+    """A native toolchain missing from the backend table is a bug and must
+    fail, not silently degrade to the PlatformIO path."""
+    from esphome.build_helpers import native
+
+    setup_core(platform=PLATFORM_ESP8266, tmp_path=tmp_path, name="test_device")
+    CORE.toolchain = Toolchain.ARDUINO
+    with (
+        patch.dict(native.NATIVE_TOOLCHAIN_MODULES, clear=True),
+        pytest.raises(EsphomeError, match="no native build backend"),
+    ):
+        native.native_backend()
+
+
+def test_command_analyze_memory_unsupported_toolchain(
+    tmp_path: Path,
+    mock_write_cpp: Mock,
+    mock_compile_program: Mock,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A hook-less non-PlatformIO toolchain is refused by name, never routed
+    into the PlatformIO branch."""
+    setup_core(platform=PLATFORM_NRF52, tmp_path=tmp_path, name="test_device")
+    CORE.toolchain = Toolchain.SDK_NRF
+    mock_write_cpp.return_value = 0
+    mock_compile_program.return_value = 0
+
+    result = command_analyze_memory(MockArgs(), {CONF_ESPHOME: {CONF_NAME: "t"}})
+
+    assert result == 1
+    assert "analyze-memory is not supported" in caplog.text
+
+
 def test_cli_toolchain_skips_the_validated_config_cache(tmp_path: Path) -> None:
     """An explicit --toolchain must run the per-platform validators, so the
     upload/logs fast path becomes a cache miss."""
@@ -7491,6 +7729,29 @@ def test_cli_toolchain_skips_the_validated_config_cache(tmp_path: Path) -> None:
     mock_read.assert_called_once()
 
 
+def test_upload_using_esptool_native_missing_firmware_raises(
+    tmp_path: Path,
+) -> None:
+    """A stale or absent firmware.bin fails by name instead of flashing air."""
+    setup_core(platform=PLATFORM_ESP8266, tmp_path=tmp_path, name="test")
+    CORE.toolchain = Toolchain.ARDUINO
+    with pytest.raises(EsphomeError, match="compile the configuration first"):
+        upload_using_esptool(
+            {CONF_ESPHOME: {"platformio_options": {}}}, "/dev/ttyUSB0", None, None
+        )
+
+
+def test_compile_program_unclaimed_native_toolchain_raises(
+    tmp_path: Path,
+) -> None:
+    """A resolved native toolchain no platform backend claims must fail,
+    never fall through to the PlatformIO project path."""
+    setup_core(platform=PLATFORM_ESP32, tmp_path=tmp_path, name="test_device")
+    CORE.toolchain = Toolchain.ARDUINO  # esp32 has no arduino-native backend
+    with pytest.raises(EsphomeError, match="no platform backend claimed"):
+        compile_program(MockArgs(), {})
+
+
 def test_cli_toolchain_still_refreshes_the_validated_config_cache(
     tmp_path: Path,
 ) -> None:

tests/unit_tests/test_writer.py

@@ -516,10 +516,13 @@ def test_clean_build(
     dependencies_lock = tmp_path / "dependencies.lock"
     dependencies_lock.write_text("lock file")
 
-    # idedata cache lives under the data dir, not the build path.
+    # idedata caches live under the data dir, not the build path; the
+    # .arduino.json variant is the native esp8266 toolchain's.
     idedata_cache = tmp_path / "idedata" / "test.json"
     idedata_cache.parent.mkdir()
     idedata_cache.write_text("{}")
+    arduino_idedata_cache = tmp_path / "idedata" / "test.arduino.json"
+    arduino_idedata_cache.write_text("{}")
 
     # Native ESP-IDF toolchain artifacts.
     idf_build_dir = tmp_path / "build"
@@ -580,6 +583,7 @@ def test_clean_build(
     assert not piolibdeps_dir.exists()
     assert not dependencies_lock.exists()
     assert not idedata_cache.exists()
+    assert not arduino_idedata_cache.exists()
     assert not idf_build_dir.exists()
     assert not managed_components_dir.exists()
     assert not pio_components_dir.exists()