Standardisiere Symcon-Modultests

docs/adr/0003-standardisierte-teststrategie.md

@@ -0,0 +1,43 @@
+# ADR 0003: Standardisierte Teststrategie
+
+## Kontext
+
+Die Module besitzen PHPUnit-Tests, ihre Prüfungen in einer echten
+IP-Symcon-Installation waren jedoch unterschiedlich aufgebaut. Dadurch fehlten
+ein einheitlicher Aufruf, sicherer Cleanup, maschinenlesbare Berichte und eine
+verbindliche Regel für neue Module.
+
+## Entscheidung
+
+Enelix verwendet zwei Testebenen. PHPUnit bleibt die schnelle Pflichtprüfung bei
+jedem Push. Zusätzlich erhält jedes Modul einen registrierten Symcon-Modultest
+mit dem gemeinsamen `TestContext`. Der Runner unterstützt `single`,
+`affected` und `all`, isoliert jeden Testlauf und liefert Konsole, JSON und
+JUnit XML.
+
+Der Manager-Test erzeugt jeden implementierten Verbrauchertyp und prüft ihn
+einzeln sowie in einer gemeinsamen Konstellation. Neue Verbrauchertypen müssen
+diese Matrix erweitern.
+
+## Alternativen
+
+- Nur PHPUnit: verworfen, weil das reale Objektmodell, Actions und
+  Modulinteraktionen nicht abgedeckt werden.
+- Freie Schnellausführungs-Skripte pro Modul: verworfen, weil Aufbau, Cleanup
+  und Berichte erneut auseinanderlaufen würden.
+- Ein drittes Test-Repository: vorerst verworfen, weil Tests zusammen mit dem
+  jeweiligen Modul versioniert und atomar geändert werden sollen.
+
+## Folgen
+
+Jedes neue Modul benötigt zusätzlich zu Unit-Tests einen Manifest-Eintrag und
+einen Symcon-Test. Der Vertrags-Unit-Test verhindert unregistrierte Module.
+Integrationstests benötigen einen isolierten IP-Symcon-8.x-Runner. Testobjekte
+dürfen ausschließlich innerhalb der vom Framework erzeugten Kategorie liegen.
+
+## Offene Punkte
+
+- Bereitstellung und Registrierung des Gitea-Runners mit Label `symcon-8`.
+- Festlegung der Aufbewahrungsdauer für JSON- und JUnit-Artefakte.
+- Erweiterung der Manager-Matrix, sobald weitere Verbrauchertypen umgesetzt
+  werden.

docs/testing/README.md

@@ -0,0 +1,104 @@
+# Standardisierte Tests
+
+## Ziel
+
+Dieses Repository verwendet zwei verbindliche Testebenen:
+
+1. PHPUnit prüft reine PHP-Logik und Struktur bei jedem Push.
+2. Symcon-Modultests prüfen reale Instanzen, Variablen, Actions und Zusammenspiel
+   in IP-Symcon 8.x.
+
+Alle implementierten Module müssen in `tests/Symcon/manifest.php` eingetragen
+sein und ein eigenes Skript in `tests/Symcon/modules/` besitzen. Der
+PHPUnit-Test `SymconTestContractTest` erzwingt diese Regel auch für künftig
+hinzugefügte Module.
+
+## Testvertrag
+
+Ein Modultest gibt eine aufrufbare Funktion mit dieser Signatur zurück:
+
+```php
+use Belevo\EnelixEMS\SymconTest\TestContext;
+
+return static function (TestContext $test): void {
+    $test->runCase('Beschreibung', static function (TestContext $test): void {
+        // Instanz aufbauen, Eingang simulieren und Ergebnis prüfen.
+    });
+};
+```
+
+Das Framework erzeugt für jeden Modultest eine eindeutige Kategorie unterhalb
+der Objektwurzel. Instanzen und Hilfsobjekte werden ausschließlich dort
+angelegt. Der Runner entfernt den vollständigen Baum in einem `finally`-Pfad.
+Ein fehlgeschlagener Cleanup macht den Gesamtlauf rot.
+
+Tests dürfen keine vorhandenen Objekte verändern oder anhand ihres Namens
+löschen. Globale Variablenprofile müssen nur dann registriert und entfernt
+werden, wenn sie vor dem Lauf nicht existierten.
+
+## Modi
+
+- `all`: alle registrierten Module
+- `single`: genau die als Auswahl übergebenen Module
+- `affected`: die durch geänderte Pfade ermittelten Module
+
+Verfügbare Module: `Manager`, `VerbraucherEinStufig`, `Warmwassererwaermer`.
+
+Der Manager-Test enthält Manager ohne Verbraucher, jeden Verbrauchertyp einzeln und alle aktuell implementierten Verbrauchertypen gemeinsam.
+
+## Manuelle Ausführung in IP-Symcon
+
+Das Repository muss über die Modulverwaltung installiert und auf dem zu
+prüfenden Stand sein. In der Schnellausführung:
+
+```php
+require_once IPS_GetKernelDir() . 'modules/Enelix-EMS/tests/Symcon/bootstrap.php';
+
+$result = enelixEmsRunSymconTests('all');
+echo $result['console'];
+```
+
+Ein Einzeltest wird beispielsweise mit
+`enelixEmsRunSymconTests('single', 'Manager')` gestartet.
+
+Auf dem Agent-Server kann derselbe Lauf über JSON-RPC ausgeführt werden:
+
+```bash
+tests/Symcon/bin/run-symcon-tests.sh all
+tests/Symcon/bin/run-symcon-tests.sh single Manager
+```
+
+Die URL kann ausschließlich zur Laufzeit über `ENELIX_SYMCON_URL` gesetzt
+werden. Zugangsdaten gehören nicht in Repository, Skripte oder Logs.
+
+## Berichte
+
+Jeder Lauf erzeugt:
+
+- eine kurze Konsolenzusammenfassung,
+- `build/symcon-tests/report.json` für Diagnose und Archivierung,
+- `build/symcon-tests/junit.xml` für CI-Auswertung.
+
+Zusätzlich schreibt der Runner die Zusammenfassung in das IP-Symcon-Log.
+
+## CI-Regeln
+
+Bei jedem Push laufen sämtliche PHPUnit-Tests. Auf `develop` werden zusätzlich
+die von den geänderten Pfaden betroffenen Symcon-Modultests ausgeführt. Bei
+gemeinsamen Framework- oder Vertragsänderungen läuft die vollständige Suite.
+Für `beta` ist immer `all` vorgeschrieben.
+
+Die Symcon-Jobs benötigen einen geschützten Runner mit dem Label `symcon-8`,
+lokalem Zugriff auf eine isolierte IP-Symcon-8.x-Instanz und den installierten
+Repository-Stand. Ohne diesen Runner ist die Richtlinie dokumentiert, aber
+nicht technisch durchsetzbar.
+
+## Checkliste für neue Module
+
+1. PHPUnit-Tests für die reine Logik ergänzen.
+2. `tests/Symcon/modules/<Modul>.php` hinzufügen.
+3. Modul und betroffene Pfade in `tests/Symcon/manifest.php` registrieren.
+4. Instanz, Pflichtvariablen, Actions, Normalfall und mindestens einen
+   Fehler- oder Grenzfall prüfen.
+5. Alle Hilfsobjekte über `TestContext` anlegen.
+6. `composer check`, Einzeltest und Gesamttest erfolgreich ausführen.