Skip to content

Development and Testing

Tom-Bom-badil edited this page Sep 15, 2026 · 1 revision

Tip

See Contributions-workflow for the branch and pull-request workflow.

Before changing code

The ownership rules are maintained in Architecture-and-internals rather than repeated on every developer page.

Use the routing table there to decide whether a change belongs in trovis-modbus-hass, trovis-modbus, modbus-connection, tmodbus, or serialx.

Tip

Moving another Home Assistant Modbus integration toward modbus-connection? Start with Architecture-and-internals, then continue with Connections-and-transports.

What is tested where

The project intentionally tests each layer where that layer is owned.

trovis-modbus

Controller semantics, datapoint decoding, grouped reads, hydronic roles and library-side write validation are tested in the library repository.

See the library's Development and contributions page for its test workflow.

trovis-modbus-hass

The integration test suite focuses on Home Assistant-specific behavior such as:

  • config flow and reconfiguration,
  • device and entity creation,
  • entity gating and identity,
  • the Write access gate,
  • translations,
  • coordinator behavior,
  • connection lifecycle at the integration boundary.

Real-controller tests complement both repositories where mocks cannot fully prove controller behavior.

Local HAOS / VS Code environment

The HAOS / VS Code shell is intentionally lightweight and does not necessarily provide a full Home Assistant development environment.

When testing integration changes against an unreleased trovis-modbus branch, prefer the local source override instead of repeatedly reinstalling the library. Create the gitignored file:

custom_components/trovis557x/local_dev.py

with:

LOCAL_TROVIS_MODBUS_SRC = "/config/dev/trovis-modbus/src"

After a Home Assistant restart, the integration will prefer that local source tree. This makes it much easier to work on both repositories side by side.

When checking dependency upgrades, remember that importlib.metadata.version("trovis-modbus") reports the installed distribution version. With the local source override active, the imported source tree can be newer than that version string.

A temporary runtime diagnostic can be useful:

from importlib.metadata import version

_LOGGER.warning(
    "TROVIS stack: trovis-modbus=%s, modbus-connection=%s, tmodbus=%s",
    version("trovis-modbus"),
    version("modbus-connection"),
    version("tmodbus"),
)

Keep that kind of diagnostic at WARNING only while testing; it is not intended as permanent normal logging.

Install the local checking tools when required:

python -m pip install --upgrade ruff pytest pytest-asyncio

Do not assume that uv, uvx, or uv sync are available in the HAOS / VS Code shell. The repository can use uv in a prepared development environment, but the supported local scripts do not require it merely to format and check the source tree.

Preferred local scripts

Run formatting and repository checks with:

cd /config/dev/trovis-modbus-hass
script/format.sh
script/hasscheck.sh

script/format.sh applies safe Ruff fixes and formats the repository.

script/hasscheck.sh verifies formatting and linting, compiles the integration and test files, and validates JSON files. It does not run pytest.

Equivalent direct checks

For diagnosis or in a minimal shell, the core checks can also be run directly:

python -m ruff format --check .
python -m ruff check .
python -m compileall custom_components tests

Run the available test suite in an environment containing the declared development dependencies:

python -m pytest

The complete Home Assistant custom-component test suite requires a prepared Home Assistant development environment and is also executed by GitHub Actions.

Current hardware test setup

The integration is regularly verified with the following controllers:

  • one TROVIS 5576 in a live heating installation, system 2.1, with four additional Pt 1000 sensors,
  • one dedicated TROVIS 5578 test controller, system 6.1, with all 17 sensor inputs equipped with Pt 1000 sensors,
  • one dedicated TROVIS 5579 test controller, system 5.1, with all 17 sensor inputs equipped with Pt 1000 sensors.

The hardware tests complement the automated software tests. They are especially important for controller probing, model- and hydronic-aware entity creation, grouped reads, write-access handling, and real register and coil writes.

Live verification

After local checks:

  1. make sure the intended trovis-modbus source/version is active,
  2. restart Home Assistant,
  3. confirm that every configured TROVIS entry loads,
  4. check the detected model, hydronic system, Rk roles, optional subsystems, and physical sensors,
  5. verify normal polling and availability,
  6. test representative reads on each affected device,
  7. enable Write access only for deliberate write tests,
  8. verify representative register and coil writes on real hardware,
  9. confirm the resulting value on the controller display where possible,
  10. disable Write access again after the test.

Use additional care with a controller operating a live heating installation. Prefer harmless test values and restore the original setting immediately.

Implementation rules

Do not maintain a second copy of the architecture rules here.

Use the dedicated references instead:

Config-flow and identity checks

Changes to setup or reconfiguration should verify:

  • Network and Serial setup paths build the expected modbus-connection parameters,
  • switching transport during reconfiguration does not leave stale connection settings behind,
  • the selected unit ID is validated,
  • controller probing reports a useful error,
  • display names can change without changing the stored slug,
  • reconfiguration keeps existing entity identities stable,
  • newly detected sensors are added without unnecessarily removing known ones,
  • multiple controller entries do not collide.

Translations

Keep German and English translations synchronized. New entity descriptions, config-flow fields, errors, device names, and options should be added to the appropriate translation files and validated as JSON.

Visible sensor names should retain the documented TROVIS abbreviations such as AF, VF, RüF, RF, SF, FG, and IMP. ASCII-safe entity IDs use forms such as ruef.

Documentation checks

A change that affects setup, device structure, entity identity, writing, connection behavior, or user-visible limitations should update the relevant Wiki page. Keep release-specific migration notes out of the permanent README.

german Wiki - Start english


english Bauanleitungen

Schritt 1 - Kabel

Schritt 2 - Adapter

Schritt 3 - Schnittstelle

Schritt 4 - Regler

Schritt 5 - Erster Test

🔥 Update: Weitere Adapter


english Home Assistant Integration

🚀 Getting started

🔌 Using the integration

🧑‍💻 Technical reference

🔢 Related projects


english SmartHomeNG Plugin


german2 Anhang: Info-Sammlung

Clone this wiki locally