Files
tsumugu/docs/ENTWICKLUNG_UND_TESTS.md
T
LarsandCursor d6b70d8f92
Deploy Development / deploy (push) Successful in 28s
Test Suite / pytest-backend (push) Failing after 2m18s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 10s
Schließe die Connector-Kapselung ab, damit Paperless, IMAP und weitere Quellen über dieselbe Anbindung laufen.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-19 15:00:50 +02:00

4.9 KiB
Raw Blame History

Entwicklung und Tests – lokal

Stand: 18.10.2026. Erstellt im Code-Review aus Code und Workflows. Deployment auf dem Raspberry Pi: DEPLOYMENT.md.

Voraussetzungen

  • Python 3.12, Node.js (das Build-Image nutzt Node 22; lokal funktioniert auch Node 24)
  • PostgreSQL 16. Der Benutzer aus DB_USER muss Tabellen anlegen und die Rolle tsumugu_runtime erstellen dürfen (CREATEROLE). Im Compose-Stack ist das der Superuser des Postgres-Containers.

Konfiguration

Das Backend liest ausschließlich die Prozessumgebung. Eine .env-Datei wird nicht automatisch geladen.

Variable Pflicht Default Bedeutung
TSUMUGU_ENV ja – development oder production; ein anderer Wert verhindert den Start
DB_NAME, DB_USER, DB_PASSWORD ja – Owner-Zugang; Migration und Runtime-Rolle
DB_HOST, DB_PORT nein localhost, 5432 –
DB_RUNTIME_USER nein tsumugu_runtime Rolle des laufenden Pools; erhält dasselbe Passwort wie DB_USER
ALLOWED_ORIGINS nein http://localhost:5173,http://localhost:3094 erlaubte Origin-Werte für schreibende Aufrufe
APP_URL nein http://localhost:5173 öffentliche Adresse
MEDIA_ROOT nein data/media Ablage eigener Dateien
PAPERLESS_MEDIA_ROOT nein leer lesender Paperless-Ablageordner als Rückfallweg
SEED_DEMO nein false wirkt nur in Development mit Datenbank *_test; in Production verhindert true den Start
SESSION_TTL_HOURS nein 336 Laufzeit einer Session
UPLOAD_MAX_BYTES nein 20971520 Upload-Grenze (Nginx erlaubt 21 MiB)

Backend starten

cd backend
python -m venv .venv && . .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt
export TSUMUGU_ENV=development DB_NAME=tsumugu_local DB_USER=postgres DB_PASSWORD=…
python -m app.cli migrate
python -m app.cli create-account --email ich@example.test --name "Ich" --password "mindestens-zehn"
uvicorn main:app --reload --port 8000

Das erste per CLI angelegte Konto wird Betreiber. Alternativ zeigt die Anmeldeseite auf einer leeren Datenbank das Formular „Betreiberkonto“ (siehe Review R-04). python -m app.entrypoint entspricht dem Containerstart: Migration, Entfernen von Fixture-Konten, danach Uvicorn auf Port 8000.

Frontend starten

cd frontend
npm ci
npm run dev        # http://localhost:5173, Proxy für /api und /health auf 127.0.0.1:8000

Ein anderes Backend erreicht der Proxy über VITE_API_PROXY. Über HTTP heißt das Session-Cookie jinkendo-session. Die Kennzeichnung „Entwicklungsumgebung“ erscheint im Vite-Server automatisch, im Image über VITE_TSUMUGU_ENV=development.

Produktionsbuild: npm run build. Für Development-Images ergänzt mark-environment.mjs danach Titel, Manifest und Farbe.

Tests

Backend

Die Suite läuft gegen echtes PostgreSQL. Sie verweigert jede Datenbank, deren Name nicht auf _test endet, sowie tsumugu, tsumugu_dev, postgres und die Templates. Vor und nach jedem Test werden alle Tabellen geleert.

cd backend
createdb tsumugu_local_test
export DB_NAME=tsumugu_local_test DB_USER=… DB_PASSWORD=… DB_HOST=localhost
python -m pytest tests -ra --basetemp=.pytest-tmp
  • conftest.py setzt TSUMUGU_ENV=development, ALLOWED_ORIGINS=http://testserver, SEED_DEMO=false und ein temporäres MEDIA_ROOT.
  • Unter Windows kann das Standard-Temp-Verzeichnis von pytest gesperrt sein. --basetemp=.pytest-tmp umgeht das; der Ordner gehört nicht ins Repository.
  • Zwei Läufe dürfen nicht gleichzeitig dieselbe Testdatenbank verwenden.
  • Paperless und IMAP werden in den Tests durch lokale Attrappen ersetzt. Es entsteht kein Netzzugriff.

Frontend

cd frontend
node --test src/list-meta.test.mjs

Weitere Frontend-Tests gibt es nicht. Ein npm test-Skript ist nicht registriert.

In CI

.gitea/workflows/test.yml erzeugt auf der Dev-Postgres die Datenbank tsumugu_test neu und führt die Suite im Backend-Image aus. Danach folgen ein lesender Health-Smoke der laufenden Dev-App und ein Frontend-Build. Bekannte Schwächen: Review 07.

Neue Migration

  1. Datei backend/migrations/YYYYMMDDTHHMMSSZ_kurzname.sql anlegen, Zeitstempel in UTC, lexikalisch nach der letzten.
  2. Keine eigene Transaktionssteuerung in der Datei; der Runner kapselt jede Datei.
  3. Angewandte Dateien nie ändern: Die Prüfsumme im Ledger verhindert danach den Start.
  4. DATENMODELL_IST.md nachziehen.

Neue Route

  1. Route in api/routes.py, api/sources.py oder api/export.py mit Depends(get_principal) und Depends(get_conn) anlegen.
  2. Rechte über die Funktionen in access/policy.py prüfen, nie nur im Frontend.
  3. Änderung samt audit(...) in derselben Verbindung.
  4. API_REFERENZ.md nachziehen.