HA Sim Test Tool

HA-Sim Test Tool

Automated end-to-end test suite for ramses_cc + ramses_extras running on the ha-sim Docker container. It exercises schema management, discovery services, HVAC/FAN handling, device lifecycle, and more — via the HA websocket + REST API at 100x simulator speed.

Quick start

cd /home/willem/dev/ramses_extras
source ~/venvs/extras/bin/activate

# Run all 73 recipes (default)
python -m tools.ha_sim_test

# Run specific recipes
python -m tools.ha_sim_test R01 R11 R47

# Run across 3 parallel containers
python -m tools.ha_sim_test --parallel 3

A full run takes ~6 minutes and executes 449 checks across 73 recipes.

Prerequisites

• The ha-sim Docker container must be running (port 8124)
• MQTT broker at localhost:1884 (host network)
• The ramses_extras venv activated (source ~/venvs/extras/bin/activate)
• The ha-sim container has ramses_cc + ramses_extras installed (dev mount or PYTHONPATH override)

See Device Simulator for container setup details.

What it tests

• Schema management — load, merge, sync, survive restart
• Device lifecycle — remove, discover, accept, disable, discard
• HVAC/FAN handling — schema caching, device loss, remotes, via_device grouping
• Raw packet injection — zone binding via 000C, config entry migration
• Zone/area sensors — spike detection, CO2, comfort temp, demand hydration
• Concurrency/stress — parallel container runs, topology event storms
• Log monitoring — 0 unexpected errors, 0 unexpected warnings

Reports

After each run, reports are written to ~/.local/share/ramses_extras/ha_sim_reports/ (override with --reports-dir):

• Log report (log_report_ha-sim_<timestamp>.txt) — ERROR/WARNING analysis with expected-warning filtering
• Summary report (summary_ha-sim_<timestamp>.md) — per-recipe pass/fail counts and timing

~30 known simulator artifacts and expected warnings are filtered out. If a new bug introduces an unexpected ERROR or WARNING, it appears in the report and fails the test.

Sub-pages

• Command-line Options — all CLI flags and environment variables
• Test Recipes — full recipe table with check counts

In-repo documentation

The complete technical reference (log monitor design, wait scaling internals, services tested, troubleshooting) is in docs/HA_SIM_TEST_TOOL.md in the repo.