[core] cpp tests: Allow customizing code generation during tests (#14681)

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

tests/components/README.md

@@ -14,11 +14,63 @@ include the relevant `.cpp` and `.h` test files there.
 
 ### Override component code generation for testing
 
-When generating code for testing, ESPHome won't invoke the component's `to_code` function, since most components do not
-need to generate configuration code for testing.
+During C++ test builds, `to_code` is suppressed for every component by default — most components do not
+need to generate configuration code for a unit test binary.
 
-If you do need to generate code to for example configure compilation flags or add libraries,
-add the component name to the `CPP_TESTING_CODEGEN_COMPONENTS` allowlist in `script/cpp_unit_test.py`.
+#### Manifest overrides
+
+If your component needs to customise code generation behavior for testing — for example to re-enable
+`to_code`, supply a lightweight stub, add a test-only dependency, or change any other manifest attribute —
+create an `__init__.py` in your component's test directory and define `override_manifest`:
+
+**Top-level component** (`tests/components/<component>/__init__.py`):
+
+```python
+from tests.testing_helpers import ComponentManifestOverride
+
+def override_manifest(manifest: ComponentManifestOverride) -> None:
+    # Re-enable the component's own to_code (needed when the component must
+    # emit C++ setup code that the test binary depends on at link time).
+    manifest.enable_codegen()
+```
+
+Or supply a lightweight stub instead of the real `to_code`:
+
+```python
+from tests.testing_helpers import ComponentManifestOverride
+
+def override_manifest(manifest: ComponentManifestOverride) -> None:
+    async def to_code_testing(config):
+        # Only emit what the C++ tests actually need
+        pass
+
+    manifest.to_code = to_code_testing
+    manifest.dependencies = manifest.dependencies + ["some_test_only_dep"]
+```
+
+**Platform component** (`tests/components/<component>/<domain>/__init__.py`,
+e.g. `tests/components/my_sensor/sensor/__init__.py`):
+
+```python
+from tests.testing_helpers import ComponentManifestOverride
+
+def override_manifest(manifest: ComponentManifestOverride) -> None:
+    manifest.enable_codegen()
+```
+
+`override_manifest` receives a `ComponentManifestOverride` that wraps the real manifest.
+Attribute assignments store an override; reads fall back to the real manifest when no
+override is present.
+
+Key methods:
+
+| Method | Effect |
+|---|---|
+| `manifest.enable_codegen()` | Remove the `to_code` suppression, re-enabling code generation |
+| `manifest.restore()` | Clear **all** overrides, reverting every attribute to the original |
+
+The function is called after `to_code` has already been set to `None`, so calling
+`enable_codegen()` is a deliberate opt-in.
 
 ## Running component unit tests
 

tests/components/core/__init__.py

@@ -0,0 +1,8 @@
+from tests.testing_helpers import ComponentManifestOverride
+
+
+def override_manifest(manifest: ComponentManifestOverride) -> None:
+    # core (esphome/core/config.py) must run its to_code during C++ test builds
+    # because it bootstraps the fundamental application infrastructure that all
+    # components depend on (component registration, event loop, etc.).
+    manifest.enable_codegen()

tests/components/host/__init__.py

@@ -0,0 +1,7 @@
+from tests.testing_helpers import ComponentManifestOverride
+
+
+def override_manifest(manifest: ComponentManifestOverride) -> None:
+    # host must run its to_code during C++ test builds because it sets up the
+    # host platform target, which is the execution environment for all unit tests.
+    manifest.enable_codegen()

tests/components/logger/__init__.py

@@ -0,0 +1,7 @@
+from tests.testing_helpers import ComponentManifestOverride
+
+
+def override_manifest(manifest: ComponentManifestOverride) -> None:
+    # logger must run its to_code during C++ test builds because it configures
+    # the logging subsystem used by ESP_LOG* macros throughout component code.
+    manifest.enable_codegen()

tests/components/time/__init__.py

@@ -0,0 +1,9 @@
+import esphome.codegen as cg
+from tests.testing_helpers import ComponentManifestOverride
+
+
+def override_manifest(manifest: ComponentManifestOverride) -> None:
+    async def to_code(config):
+        cg.add_build_flag("-DUSE_TIME_TIMEZONE")
+
+    manifest.to_code = to_code