106 lines
3.6 KiB
Markdown
106 lines
3.6 KiB
Markdown
# 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\EnelixUtils\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: `Energiediagramm`, `ShellyModul`,
|
|
`Verbrauchskostenreport`.
|
|
|
|
Die Utils-Module werden jeweils eigenständig und ohne Abhängigkeit zu Enelix EMS getestet.
|
|
|
|
## 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-Utils/tests/Symcon/bootstrap.php';
|
|
|
|
$result = enelixUtilsRunSymconTests('all');
|
|
echo $result['console'];
|
|
```
|
|
|
|
Ein Einzeltest wird beispielsweise mit
|
|
`enelixUtilsRunSymconTests('single', 'ShellyModul')` 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 ShellyModul
|
|
```
|
|
|
|
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.
|