# Observability and testing

> The flight recorder, the diagnostics download, the annunciation attributes, and the test strategy.

Source: https://better-thermostat.org/internals/observability-and-testing/

## Mode annunciation

Degradation is never silent. The climate entity exposes:

- `control_mode` — the fail-soft rung (`optimal`, `sensor_fallback`,
  `hold`),
- `degraded_for_seconds` and `unavailable_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

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

Four nets with distinct failure modes they catch:

1. **Pure unit tests** (`tests/unit/` holds the bulk, and further unit
   test files sit directly in `tests/`) — the core is HA-free,
   so the kernel, the regions, the safety hull, and the recorder are
   tested without mocks; the shell is tested against `MagicMock`
   entities. The core is covered exhaustively: every branch of the
   decision path and every region transition has a test.
2. **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.
3. **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.
4. **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.
