# 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: `LadestationStandAlone`, `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.