Observability and testing
Mode annunciation
Section titled “Mode annunciation”Degradation is never silent. The climate entity exposes:
control_mode— the fail-soft rung (optimal,sensor_fallback,hold),degraded_for_secondsandunavailable_sensors— what is degraded, since when,calibrator_health— per TRV, whether its calibration controller is healthy, has self-healed, or shows oscillating output.
Entering degraded mode raises a repair issue (suppressed during the five-minute startup grace window so slow cloud integrations do not alarm) which clears itself on recovery.
The flight recorder
Section titled “The flight recorder”Because decide() is pure, recording the tuple
(snapshot, pre-decide state, desired) per control cycle is enough to
reproduce any decision offline. core/recorder.py keeps a bounded ring
of the last 50 decision tuples; the diagnostics download
(Settings → Devices & services → Better Thermostat → Download
diagnostics) exports it alongside the configuration and device states.
replay() feeds an exported tuple back through the kernel and compares
the result, so a bug report’s diagnostics file answers why Better
Thermostat did what it did, deterministically, on the developer’s
machine. A
completeness test forces every new field of the recorded types through
the export/reconstruct round-trip, so the replay side cannot silently
drift from the dataclasses.
Test strategy
Section titled “Test strategy”Four nets with distinct failure modes they catch:
- Pure unit tests (
tests/unit/holds the bulk, and further unit test files sit directly intests/) — the core is HA-free, so the kernel, the regions, the safety hull, and the recorder are tested without mocks; the shell is tested againstMagicMockentities. The core is covered exhaustively: every branch of the decision path and every region transition has a test. - Integration tests (
tests/integration/) — a config entry driving a simulated climate entity inside a running Home Assistant instance. They exist because a control path that silently writes nothing keeps every unit test green: the assertions are the service calls that arrive at the device. Covered end to end: startup sync, window → OFF, restore after restart, unload/reload, and the reconciler healing a dropped write. - The calibration benchmark (
tests/benchmark/) — a pure thermal simulation comparing all controllers across ~36 scenarios. Seeded and deterministic, so two runs are byte-identical: refactorings of the calibration code are proven behavior-preserving by diffing the benchmark output before and after. - Golden replays (
tests/fixtures/replay_corpus/) — committed decision tuples for startup, maintenance, mode OFF, an open window, an open door, no call for heat, heating, the SENSOR_FALLBACK and HOLD rungs, and an unreachable TRV, pinned byte-stable. An intentional kernel change regenerates them (BT_REGEN_GOLDENS=1) and the diff shows exactly which decisions changed.
The standby contract, the no-raw-dict-access guard, and the controller state-threading contract each live in their own file, so a regression reads as a broken contract rather than an incidental unit failure.