Add Home Assistant integration test suite, running in CI

The class of bug that has cost the most time this week is invisible to the existing suite: it deliberately avoids Home Assistant, so anything in a voluptuous schema or the entry lifecycle cannot be reached.

The Max Register Block Size selector shipped broken in v1.2.0 and survived four releases. The read path was wired correctly, so inspecting the code looked fine - the value simply never reached it. Two users found it independently as two different symptoms (#360, #367), and I told the second one the code was correct.

tests_ha/ covers exactly that gap:

  test_options_flow.py  every offered block-size label persists; the saved value
                        reaches the read path; the form opens with a valid default;
                        an unrelated option can still be changed
  test_setup.py         setup, unload, reload, entities created, coordinator on
                        runtime_data rather than hass.data, diagnostics produced
                        without raising and with the host redacted

Those setup/unload/reload cases are the checks I have been asking a user to perform by hand after every release - the reason v1.3.1 and v1.3.2 both shipped as pre-releases.

Kept as a separate directory and a separate CI job on purpose. tests/ has three small dependencies and runs in half a second, which is what makes it usable on every register-map change; pulling Home Assistant into that would lose it.

Linux only. Home Assistant pins lru-dict==1.3.0, which has no CPython 3.13 Windows wheel and needs a C compiler, so these cannot run on the development machine. CI is the only place they execute, and the first run may well need iteration.

pytest-homeassistant-custom-component is pinned to 0.13.316 deliberately - each release targets one HA version, so leaving it floating lets an upstream release break CI with no change here.

tests/conftest.py now checks whether Home Assistant is importable rather than already imported, so its stub steps aside instead of shadowing the real package.

pytest.ini sets testpaths=tests so a bare pytest run does not try to collect tests_ha and fail on a missing dependency.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: 0xAHA

.github/workflows/tests.yaml

@@ -7,21 +7,45 @@ on:
     branches: [main]
 
 jobs:
-  test:
+  # Fast suite: pure protocol logic, no Home Assistant. Runs in well under a second,
+  # which is what makes it usable on every register-map change.
+  unit:
+    name: Unit tests (no HA)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
 
-      # Home Assistant is deliberately NOT installed. The protocol layer is
-      # HA-free, and tests/conftest.py stubs the one unused import so it stays
-      # that way — keeping the suite fast and the coupling visible.
       - name: Install dependencies
         run: pip install pytest pymodbus pyserial
 
       - name: Run tests
         run: pytest tests/ -v
+
+  # Home Assistant suite: config flow, setup/unload, entity creation, diagnostics.
+  #
+  # Linux only. Home Assistant pins lru-dict==1.3.0, which has no CPython 3.13 Windows
+  # wheel and needs a C compiler — so this cannot run on a Windows dev machine, and CI
+  # is the only place these tests execute.
+  #
+  # pytest-homeassistant-custom-component is pinned deliberately: each release targets
+  # one specific HA version, so leaving it floating means an upstream HA release can
+  # break this job without any change here. Bump it on purpose.
+  homeassistant:
+    name: Home Assistant integration tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install Home Assistant test harness
+        run: pip install pytest-homeassistant-custom-component==0.13.316
+
+      - name: Run tests
+        run: pytest tests_ha/ -v

pytest.ini

@@ -1,5 +1,11 @@
 [pytest]
+# Bare `pytest` runs only the fast, Home-Assistant-free suite. Running it from the repo
+# root would otherwise try to collect tests_ha/ and fail on a missing
+# pytest-homeassistant-custom-component, which is confusing rather than informative.
+#
+# The Home Assistant suite is opt-in:   pytest tests_ha/
+# It requires Linux — see tests_ha/conftest.py for why it cannot run on Windows.
 testpaths = tests
-python_files = test_*.py
-python_classes = Test*
-python_functions = test_*
+
+# tests_ha/ uses async test functions without explicit markers.
+asyncio_mode = auto

tests/conftest.py

@@ -19,6 +19,7 @@
 from __future__ import annotations
 
 import importlib
+import importlib.util
 import sys
 import types
 from pathlib import Path
@@ -30,6 +31,12 @@
 
 
 def _stub_homeassistant() -> None:
+    # Step aside when a real Home Assistant is installed. Checking importability rather
+    # than "already imported" matters: pytest loads this conftest before anything touches
+    # HA, so an unconditional stub would shadow the real package for the whole session
+    # and break the tests_ha/ suite in confusing ways.
+    if importlib.util.find_spec("homeassistant") is not None:
+        return
     if "homeassistant" in sys.modules:
         return
     ha = types.ModuleType("homeassistant")

tests_ha/__init__.py

@@ -0,0 +1 @@
+"""Home Assistant integration tests — CI only, Linux only. See conftest.py."""

tests_ha/conftest.py

@@ -0,0 +1,61 @@
+"""Fixtures for the Home Assistant integration tests.
+
+These run only in CI, on Linux, where `pytest-homeassistant-custom-component` installs
+from prebuilt wheels. They cannot run on Windows: Home Assistant pins
+`lru-dict==1.3.0`, which has no CPython 3.13 Windows wheel and needs a C compiler.
+
+Kept separate from `tests/` deliberately. That suite has three small dependencies and
+runs in half a second, which is what makes it usable on every register-map change.
+Merging the two would drag Home Assistant into every run and lose that.
+"""
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+from pytest_homeassistant_custom_component.common import MockConfigEntry
+
+from custom_components.growatt_modbus.const import DOMAIN
+
+
+@pytest.fixture(autouse=True)
+def auto_enable_custom_integrations(enable_custom_integrations):
+    """Load `custom_components/` — without this HA ignores the integration entirely."""
+    yield
+
+
+@pytest.fixture
+def mock_entry() -> MockConfigEntry:
+    """A TCP config entry resembling a real installation."""
+    return MockConfigEntry(
+        domain=DOMAIN,
+        title="Growatt Test",
+        data={
+            "name": "Growatt Test",
+            "connection_type": "tcp",
+            "host": "192.0.2.10",     # TEST-NET-1, guaranteed unroutable
+            "port": 502,
+            "slave_id": 1,
+            "inverter_series": "min_7000_10000_tl_x",
+            "register_map": "MIN_7000_10000TL_X",
+            "vpp_protocol_confirmed": False,
+        },
+        options={
+            "scan_interval": 60,
+            "modbus_delay": 250,
+        },
+    )
+
+
+@pytest.fixture
+def bypass_connection():
+    """Stop the coordinator opening a socket.
+
+    The config and options flows are what these tests exercise; letting them attempt a
+    real connection would make them slow and dependent on network behaviour.
+    """
+    with patch(
+        "custom_components.growatt_modbus.GrowattModbusCoordinator._fetch_data",
+        return_value=None,
+    ):
+        yield

tests_ha/test_options_flow.py

@@ -0,0 +1,131 @@
+"""Options flow tests.
+
+These exist because of a specific failure. The "Max Register Block Size" selector
+shipped in v1.2.0 declared as `vol.In({0: "Auto", 25: "25 registers", ...})` — keyed by
+integers, with `default=0`. **The option could never be saved.**
+
+It survived four releases. The read path was wired correctly, so code inspection looked
+fine; the value simply never reached it. Two users found it independently, as two
+different symptoms — "nothing is selected" (#360) and "the option had zero effect"
+(#367) — and I initially told the second one the code was correct.
+
+Nothing in the HA-free suite could have caught it: the defect is in a voluptuous schema
+that only misbehaves when Home Assistant renders and submits it. That is the entire
+argument for this directory existing.
+"""
+from __future__ import annotations
+
+import pytest
+from homeassistant.core import HomeAssistant
+
+from custom_components.growatt_modbus.const import BLOCK_SIZE_OPTIONS
+
+
+async def _open_options(hass: HomeAssistant, entry):
+    entry.add_to_hass(hass)
+    assert await hass.config_entries.async_setup(entry.entry_id)
+    await hass.async_block_till_done()
+    return await hass.config_entries.options.async_init(entry.entry_id)
+
+
+@pytest.mark.parametrize("label", list(BLOCK_SIZE_OPTIONS))
+async def test_every_block_size_label_can_be_saved(
+    hass: HomeAssistant, mock_entry, bypass_connection, label
+):
+    """The regression, stated directly: each offered choice must persist.
+
+    Under the old schema this failed for every value — which is what made the option
+    inert rather than merely awkward.
+    """
+    result = await _open_options(hass, mock_entry)
+
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"],
+        user_input={
+            "device_name": "Growatt Test",
+            "inverter_series": "MIN (7-10kW)",
+            "scan_interval": 60,
+            "offline_scan_interval": 300,
+            "invert_grid_power": False,
+            "invert_battery_power": False,
+            "battery_voltage_range": "Auto-detect",
+            "modbus_delay": 250,
+            "max_block_size": label,
+        },
+    )
+    await hass.async_block_till_done()
+
+    assert result["type"] == "create_entry"
+    assert mock_entry.options["max_block_size"] == label
+
+
+async def test_saved_block_size_reaches_the_read_path(
+    hass: HomeAssistant, mock_entry, bypass_connection
+):
+    """Saving is only half of it — the value must arrive at the client.
+
+    v1.2.0 wired this end correctly while the form end was broken, so verifying only the
+    wiring gave a false positive. This asserts the whole chain.
+    """
+    from custom_components.growatt_modbus.const import resolve_block_size
+
+    result = await _open_options(hass, mock_entry)
+    await hass.config_entries.options.async_configure(
+        result["flow_id"],
+        user_input={
+            "device_name": "Growatt Test",
+            "inverter_series": "MIN (7-10kW)",
+            "scan_interval": 60,
+            "offline_scan_interval": 300,
+            "invert_grid_power": False,
+            "invert_battery_power": False,
+            "battery_voltage_range": "Auto-detect",
+            "modbus_delay": 250,
+            "max_block_size": "25 registers",
+        },
+    )
+    await hass.async_block_till_done()
+
+    assert resolve_block_size(mock_entry.options["max_block_size"]) == 25
+
+
+async def test_options_form_opens_with_a_valid_default(
+    hass: HomeAssistant, mock_entry, bypass_connection
+):
+    """A default that matches no offered choice renders as nothing selected.
+
+    That was the visible half of the bug (#360) — and because the field is Required,
+    an unselected form also refuses to submit, blocking *every* option on the page.
+    """
+    result = await _open_options(hass, mock_entry)
+    assert result["type"] == "form"
+    assert result["errors"] in (None, {})
+
+
+async def test_unrelated_option_can_be_changed_without_touching_block_size(
+    hass: HomeAssistant, mock_entry, bypass_connection
+):
+    """The real user impact: a broken selector locked the whole form.
+
+    #360 could not change scan interval, because the invalid block-size default failed
+    validation for the entire submission.
+    """
+    result = await _open_options(hass, mock_entry)
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"],
+        user_input={
+            "device_name": "Growatt Test",
+            "inverter_series": "MIN (7-10kW)",
+            "scan_interval": 120,
+            "offline_scan_interval": 300,
+            "invert_grid_power": False,
+            "invert_battery_power": False,
+            "battery_voltage_range": "Auto-detect",
+            "modbus_delay": 250,
+            "max_block_size": "Auto (recommended)",
+        },
+    )
+    await hass.async_block_till_done()
+
+    assert result["type"] == "create_entry"
+    assert mock_entry.options["scan_interval"] == 120

tests_ha/test_setup.py

@@ -0,0 +1,96 @@
+"""Setup and teardown tests.
+
+These cover what I have been asking a user to confirm by hand after every release —
+"does it load, does it reload" — which is the check that catches a broken `runtime_data`
+migration or entity base class before anyone installs it.
+
+v1.3.1 and v1.3.2 both shipped as pre-releases purely because I could not answer that
+question locally.
+"""
+from __future__ import annotations
+
+from homeassistant.config_entries import ConfigEntryState
+from homeassistant.core import HomeAssistant
+
+from custom_components.growatt_modbus.const import DOMAIN
+
+
+async def test_entry_sets_up(hass: HomeAssistant, mock_entry, bypass_connection):
+    mock_entry.add_to_hass(hass)
+    assert await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    assert mock_entry.state is ConfigEntryState.LOADED
+
+
+async def test_coordinator_is_on_runtime_data(
+    hass: HomeAssistant, mock_entry, bypass_connection
+):
+    """v1.3.1 moved the coordinator off `hass.data[DOMAIN]`.
+
+    `hass.data[DOMAIN]` should now hold only the cross-entry connection registry — the
+    two used to be mixed, which is why code walking it needed a defensive check.
+    """
+    mock_entry.add_to_hass(hass)
+    assert await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+
+    assert getattr(mock_entry, "runtime_data", None) is not None
+    assert mock_entry.entry_id not in hass.data.get(DOMAIN, {})
+
+
+async def test_entry_unloads(hass: HomeAssistant, mock_entry, bypass_connection):
+    """The unload path can only fail on unload — a load test cannot reach it."""
+    mock_entry.add_to_hass(hass)
+    assert await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+
+    assert await hass.config_entries.async_unload(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    assert mock_entry.state is ConfigEntryState.NOT_LOADED
+
+
+async def test_entry_reloads(hass: HomeAssistant, mock_entry, bypass_connection):
+    """Reload is unload followed by setup, so it exercises both directions."""
+    mock_entry.add_to_hass(hass)
+    assert await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+
+    assert await hass.config_entries.async_reload(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    assert mock_entry.state is ConfigEntryState.LOADED
+
+
+async def test_entities_are_created(hass: HomeAssistant, mock_entry, bypass_connection):
+    """Guards the GrowattEntity migration (v1.3.2).
+
+    A wrong base class shows up as entities silently not being created — the
+    integration still loads, so a load check would pass.
+    """
+    mock_entry.add_to_hass(hass)
+    assert await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+
+    entities = [
+        s for s in hass.states.async_all()
+        if s.entity_id.startswith(("sensor.", "binary_sensor."))
+    ]
+    assert entities, "no entities were created"
+
+
+async def test_diagnostics_can_be_produced(
+    hass: HomeAssistant, mock_entry, bypass_connection
+):
+    """Diagnostics must never raise — it is needed when things are already broken."""
+    from custom_components.growatt_modbus.diagnostics import (
+        async_get_config_entry_diagnostics,
+    )
+
+    mock_entry.add_to_hass(hass)
+    assert await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+
+    diagnostics = await async_get_config_entry_diagnostics(hass, mock_entry)
+    assert "entry" in diagnostics
+    assert "coordinator" in diagnostics
+    # Host is redacted — users paste these into public issues.
+    assert diagnostics["entry"]["data"].get("host") != "192.0.2.10"