Merge pull request #53 from traktore-org/develop

v1.0.8: Platinum quality scale — 803 tests, CI pipeline, beginner docs

Author: traktore-org

.github/workflows/tests.yml

@@ -0,0 +1,63 @@
+name: Tests
+
+on:
+  push:
+    branches: [develop, main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest pytest-asyncio pytest-cov freezegun homeassistant
+
+      - name: Set up importable package structure
+        run: |
+          # Create custom_components structure outside the checkout
+          # so pytest doesn't try to collect __init__.py from repo root
+          mkdir -p /tmp/ha-config/custom_components
+          cp -r $GITHUB_WORKSPACE /tmp/ha-config/custom_components/solar_energy_management
+
+      - name: Run tests with coverage
+        working-directory: /tmp/ha-config/custom_components/solar_energy_management
+        env:
+          PYTHONPATH: /tmp/ha-config
+        run: |
+          python -m pytest tests/ \
+            --cov=custom_components.solar_energy_management \
+            --cov-report=term-missing \
+            --cov-report=xml:$GITHUB_WORKSPACE/coverage.xml \
+            -v --tb=short
+
+      - name: Upload coverage report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-py${{ matrix.python-version }}
+          path: coverage.xml
+
+      - name: Coverage summary
+        if: always()
+        working-directory: /tmp/ha-config/custom_components/solar_energy_management
+        env:
+          PYTHONPATH: /tmp/ha-config
+        run: |
+          python -m pytest tests/ \
+            --cov=custom_components.solar_energy_management \
+            --cov-report=term \
+            -q --no-header 2>&1 | tail -30 || true

README.md

@@ -5,6 +5,7 @@
 # Solar Energy Management (SEM)
 
 [![GitHub Release][releases-shield]][releases]
+[![Tests](https://github.com/traktore-org/sem-community/actions/workflows/tests.yml/badge.svg)](https://github.com/traktore-org/sem-community/actions/workflows/tests.yml)
 [![GitHub Activity][commits-shield]][commits]
 [![License][license-shield]](LICENSE)
 [![hacs][hacsbadge]][hacs]
@@ -44,6 +45,8 @@ SEM monitors your solar production, battery, grid, and EV charger every 10 secon
 
 ## Installation
 
+> **New to custom integrations?** See the [Step-by-Step Setup Guide](docs/SETUP_GUIDE.md) for a beginner-friendly walkthrough with checklist and FAQ.
+
 ### Via HACS (Recommended)
 
 1. Open **HACS** > **Integrations** > **Custom repositories**

coordinator/coordinator.py

@@ -167,6 +167,10 @@ def __init__(self, hass: HomeAssistant, config: Dict[str, Any]) -> None:
         # Phase 8: Consumption/solar predictor (#3)
         self._predictor = ConsumptionPredictor()
 
+        # Per-cycle caches (initialized here, populated in _async_update_data)
+        self._cycle_forecast = None
+        self._cycle_vehicle_soc: Optional[float] = None
+
         # EV stall detection for self-healing
         self._ev_stalled_since: Optional[float] = None
 
@@ -313,6 +317,19 @@ async def _async_update_data(self) -> Dict[str, Any]:
             self._observer_mode = observer_state.state == "on"
 
         try:
+            # Per-cycle caches — avoid redundant lookups within one 10s cycle (#52)
+            self._cycle_forecast = self._forecast_reader.read_forecast()
+            # Cache vehicle SOC (read in both _async_update_data and _determine_charging_strategy)
+            _vehicle_soc_entity = self.config.get("vehicle_soc_entity", "")
+            self._cycle_vehicle_soc = None
+            if _vehicle_soc_entity:
+                _soc_state = self.hass.states.get(_vehicle_soc_entity)
+                if _soc_state and _soc_state.state not in (STATE_UNKNOWN, STATE_UNAVAILABLE):
+                    try:
+                        self._cycle_vehicle_soc = float(_soc_state.state)
+                    except (ValueError, TypeError):
+                        pass
+
             # Step 1: Read power values from sensors
             power = self._sensor_reader.read_power()
 
@@ -505,15 +522,9 @@ async def _async_update_data(self) -> Dict[str, Any]:
                 solar = lifetime.get("total_solar_kwh", 0)
                 result["lifetime_ev_solar_share"] = round(solar / total * 100, 1) if total > 0 else 0
 
-            # Vehicle SOC (if configured)
-            vehicle_soc_entity = self.config.get("vehicle_soc_entity", "")
-            if vehicle_soc_entity:
-                soc_state = self.hass.states.get(vehicle_soc_entity)
-                if soc_state and soc_state.state not in (STATE_UNKNOWN, STATE_UNAVAILABLE):
-                    try:
-                        result["vehicle_soc"] = float(soc_state.state)
-                    except (ValueError, TypeError):
-                        pass
+            # Vehicle SOC (from per-cycle cache)
+            if self._cycle_vehicle_soc is not None:
+                result["vehicle_soc"] = self._cycle_vehicle_soc
 
             # EV departure time (if configured via input_datetime entity)
             departure_entity = self.config.get("ev_departure_time_entity", "")
@@ -561,7 +572,7 @@ async def _update_analytics_phases(
         # Forecast (Phase 0.3)
         forecast_data = ForecastSensorData()
         try:
-            forecast = self._forecast_reader.read_forecast()
+            forecast = self._cycle_forecast
             if forecast.available:
                 forecast_data.forecast_today_kwh = forecast.forecast_today_kwh
                 forecast_data.forecast_tomorrow_kwh = forecast.forecast_tomorrow_kwh
@@ -877,14 +888,7 @@ def _determine_charging_strategy(self, power: PowerReadings, energy: Any) -> tup
         ev_battery_capacity = self.config.get("ev_battery_capacity_kwh", 40)
         ev_target_soc = self.config.get("ev_target_soc", 80)
 
-        vehicle_soc = None
-        if vehicle_soc_entity:
-            soc_state = self.hass.states.get(vehicle_soc_entity)
-            if soc_state and soc_state.state not in (STATE_UNKNOWN, STATE_UNAVAILABLE):
-                try:
-                    vehicle_soc = float(soc_state.state)
-                except (ValueError, TypeError):
-                    pass
+        vehicle_soc = self._cycle_vehicle_soc
 
         if vehicle_soc is not None:
             # SOC-based: remaining = (target_soc - current_soc) / 100 * capacity
@@ -965,7 +969,7 @@ def _determine_charging_strategy(self, power: PowerReadings, energy: Any) -> tup
         if power.battery_soc >= buffer_soc:
             # Use forecast if available to check if surplus alone is enough
             try:
-                forecast = self._forecast_reader.read_forecast()
+                forecast = self._cycle_forecast
                 if forecast.available:
                     surplus_factor = 0.5
                     estimated_surplus = forecast.forecast_remaining_today_kwh * surplus_factor
@@ -999,7 +1003,7 @@ def _determine_charging_strategy(self, power: PowerReadings, energy: Any) -> tup
                 )
             reason = f"Zone 2: SOC={power.battery_soc:.0f}% in [{priority_soc}%..{buffer_soc}%) — surplus only"
             try:
-                forecast = self._forecast_reader.read_forecast()
+                forecast = self._cycle_forecast
                 if forecast.available:
                     surplus_factor = 0.5
                     estimated_surplus = forecast.forecast_remaining_today_kwh * surplus_factor
@@ -1055,7 +1059,7 @@ def _build_charging_context(
         # Use EV budget (with battery redirect) instead of surplus-style available_power
         forecast_remaining = 0
         try:
-            forecast = self._forecast_reader.read_forecast()
+            forecast = self._cycle_forecast
             if forecast.available:
                 forecast_remaining = forecast.forecast_remaining_today_kwh
         except Exception: