Lisp Tests im Readme dokumentiert

Lisp/README.md

@@ -358,6 +358,77 @@ Testbefehle für die Python-Integration. Export-Funktionen wurden in `export.lsp
 
 ---
 
+## Tests
+
+Zwei Test-Ebenen, beide gesteuert über `bin\run_tests.bat` (Details und
+Verzeichnisstruktur: [`../tests/README.md`](../tests/README.md)):
+
+1. **LISP-Unit-Tests** (`tests/test_unit.lsp`) – prüfen reine
+   Standardfunktionen direkt in AutoLISP, ohne Zeichnung.
+2. **Zeichnungsbasierte Integrationstests** (`tests/test_*.lsp` +
+   `tests/test_*.py`) – erzeugen Blöcke in BricsCAD und validieren das
+   Ergebnis anschließend mit pytest/ezdxf.
+
+### LISP-Unit-Tests (`test_unit.lsp`)
+
+Testen **reine Hilfsfunktionen** – solche, die nur aus ihren Argumenten ein
+Ergebnis berechnen und keine Zeichnungsdatenbank, Auswahlsätze, Dialoge oder
+Blockdateien brauchen (String-, Zahl-, Vektor-, Listen- und Alist-Helfer).
+Abgedeckt werden Funktionen aus `ssg_core`, `ssg_lang`, `ssg_id`, `vf_core`,
+`export`, `Gefaellestrecke`, `OmniModulInsert` und `KreiselInsert`.
+
+**Aufruf über die Kommandozeile** (startet BricsCAD headless):
+
+```cmd
+bin\run_tests.bat --lisp
+```
+
+`run_tests.bat --lisp` löscht das alte Ergebnis, startet BricsCAD mit
+`tests/test_unit.scr` (lädt `ssg_load.lsp` + `test_unit.lsp`, ruft `TEST_UNIT`
+auf und beendet BricsCAD), gibt danach `tests/output/unit_results.txt` aus und
+liefert Exit-Code 1, wenn ein Test fehlschlägt oder kein Report entsteht.
+
+**Aufruf direkt in BricsCAD** (SSG_LIB geladen):
+
+```lisp
+(load (strcat (getenv "DXFMAKRO") "/tests/test_unit.lsp"))
+TEST_UNIT
+```
+
+**Aufbau eines Testfalls.** `test_unit.lsp` enthält ein Mini-Framework: jeder
+Testfall ruft eine Funktion auf und vergleicht das Ergebnis gegen einen
+erwarteten Wert. Die Assertion-Helfer zählen Treffer/Fehler mit und schreiben
+je eine `PASS`/`FAIL`-Zeile:
+
+| Helfer | Vergleich |
+| --- | --- |
+| `tu-eq name erwartet ist` | exakt (`equal`) – Strings, Ganzzahlen, Listen davon |
+| `tu-eqf name erwartet ist` | numerisch mit Toleranz `1e-6` – Fliesskomma, auch verschachtelte Listen |
+| `tu-true name ist` | Ergebnis ist nicht `nil` |
+| `tu-nil name ist` | Ergebnis ist `nil` |
+
+Beispiel – Formatierung einer ID und ein Vektor-Kreuzprodukt:
+
+```lisp
+(tu-eq  "ssg-id-format/1"      "0001"          (ssg-id-format 1))
+(tu-eqf "vec3-cross/x-cross-y" '(0.0 0.0 1.0)  (vec3-cross '(1.0 0.0 0.0) '(0.0 1.0 0.0)))
+```
+
+Die Testfälle sind in `tu-tests-<modul>`-Funktionen gruppiert; `c:TEST_UNIT`
+ruft alle nacheinander auf, gibt eine Zusammenfassung
+(`Gesamt / PASS / FAIL`) aus und schreibt den Report `unit_results.txt` mit
+einer abschließenden Zeile `RESULT: OK` bzw. `RESULT: FAIL` (die
+`run_tests.bat` auswertet).
+
+**Neuen Testfall ergänzen:** in der passenden `tu-tests-<modul>`-Funktion eine
+`tu-eq`/`tu-eqf`/`tu-true`/`tu-nil`-Zeile hinzufügen. Für ein neues Modul eine
+eigene `tu-tests-<modul>`-Funktion anlegen und in `c:TEST_UNIT` aufrufen.
+Getestet werden sollten nur Funktionen ohne Zeichnungs-/Dialog-Umfeld – alles
+mit `ssget`/`entget`/`entmake`/`command`/`vla-*`/`entsel`/DCL gehört in die
+zeichnungsbasierten Integrationstests.
+
+---
+
 ### `KreiselInsert.lsp` – ILS Kreisel und Eckrad
 
 AutoLISP-Implementierung fuer ILS Kreisel und Eckrad. Enthaelt alle Befehle fuer Einfuegen, Verbinden, Neuzeichnen und Bearbeiten.