breakpilot-pwa/docs/testing/integration-test-environment.md

Integration Test Environment

Letzte Aktualisierung: 2026-02-04 Status: Produktiv Maintainer: DevOps Team

---

Inhaltsverzeichnis

1. Uebersicht
2. Quick Start (Lokal)
3. Services
4. CI/CD Integration
5. Konfiguration
6. Troubleshooting

---

1. Uebersicht

Die Integration-Test-Umgebung ermoeglicht vollstaendige End-to-End-Tests aller Services in einer isolierten Docker-Compose-Umgebung. Sie wird sowohl lokal als auch in der CI/CD-Pipeline verwendet.

Architektur

┌─────────────────────────────────────────────────────────────────────┐
│                    docker-compose.test.yml                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────┐  │
│  │ postgres-test│    │  valkey-test │    │     mailpit-test     │  │
│  │  Port 55432  │    │  Port 56379  │    │  Web: 58025          │  │
│  │  PostgreSQL  │    │  Redis/Valkey│    │  SMTP: 51025         │  │
│  └──────────────┘    └──────────────┘    └──────────────────────┘  │
│         │                   │                      │                │
│         ▼                   ▼                      ▼                │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                   consent-service-test                       │   │
│  │                       Port 58081                             │   │
│  │                   Go Authentication Service                  │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                              │                                      │
│                              ▼                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                      backend-test                            │   │
│  │                       Port 58000                             │   │
│  │                   Python FastAPI Backend                     │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Vorteile

• Isolation: Keine Konflikte mit Produktions- oder Entwicklungs-Datenbanken
• Reproduzierbarkeit: Identische Umgebung lokal und in CI/CD
• Health Checks: Automatisches Warten auf Service-Verfuegbarkeit
• Cleanup: Automatisches Entfernen aller Volumes nach Tests

---

2. Quick Start (Lokal)

Test-Umgebung starten

# 1. Test-Umgebung starten
docker compose -f docker-compose.test.yml up -d

# 2. Warten bis alle Services healthy sind
docker compose -f docker-compose.test.yml ps

# 3. Health-Status pruefen (alle sollten "healthy" zeigen)
watch docker compose -f docker-compose.test.yml ps

Integration Tests ausfuehren

# In das Backend-Verzeichnis wechseln
cd backend

# Virtual Environment aktivieren (falls vorhanden)
source venv/bin/activate

# Integration Tests ausfuehren
export SKIP_INTEGRATION_TESTS=false
pytest tests/test_integration/ -v

Services einzeln testen

# Datenbank-Verbindung testen
psql -h localhost -p 55432 -U breakpilot -d breakpilot_test -c "SELECT 1"

# Consent Service Health Check
curl -f http://localhost:58081/health

# Backend Health Check
curl -f http://localhost:58000/health

# Mailpit Web UI
open http://localhost:58025

Aufraeumen

# Alle Container stoppen und Volumes loeschen
docker compose -f docker-compose.test.yml down -v

---

3. Services

Port-Strategie

Service	Test-Port (extern)	Container-Port	Prod-Port
PostgreSQL	55432	5432	5432
Valkey/Redis	56379	6379	6379
Consent Service	58081	8081	8081
Backend	58000	8000	8000
Mailpit Web	58025	8025	-
Mailpit SMTP	51025	1025	-

Service-Details

postgres-test

• Image: postgres:16-alpine
• Credentials: breakpilot:breakpilot_test@breakpilot_test
• Health Check: pg_isready -U breakpilot -d breakpilot_test

valkey-test

• Image: valkey/valkey:7-alpine
• Health Check: valkey-cli ping
• Hinweis: Ersetzt Redis fuer bessere ARM64-Kompatibilitaet

consent-service-test

• Build: ./consent-service/Dockerfile
• Health Check: GET /health
• Abhaengigkeiten: postgres-test, valkey-test

backend-test

• Build: ./backend/Dockerfile
• Health Check: GET /health
• Abhaengigkeiten: postgres-test, valkey-test, consent-service-test

mailpit-test

• Image: axllent/mailpit:latest
• Web UI: http://localhost:58025
• SMTP: localhost:51025
• Zweck: E-Mail-Testing ohne echten SMTP-Server

---

4. CI/CD Integration

Woodpecker Pipeline

Die Integration-Tests laufen automatisch bei jedem Push/PR zu main oder develop:

# .woodpecker/main.yml
integration-tests:
  image: docker:27-cli
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
  commands:
    - docker compose -f docker-compose.test.yml up -d
    - # Wait for services...
    - docker compose -f docker-compose.test.yml exec -T backend-test \
        pytest tests/test_integration/ -v
    - docker compose -f docker-compose.test.yml down -v
  when:
    - event: [push, pull_request]
      branch: [main, develop]

Pipeline-Ablauf

1. Unit Tests (test-go-, test-python-) laufen zuerst
2. Integration Tests starten Docker Compose Umgebung
3. Report sendet alle Ergebnisse ans Test Dashboard

Manueller Pipeline-Trigger

# Via Gitea/Woodpecker UI oder:
curl -X POST "https://macmini:4431/api/repos/pilotadmin/breakpilot-pwa/pipelines" \
  -H "Authorization: Bearer $WOODPECKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main"}'

---

5. Konfiguration

Environment Variables

Die Test-Umgebung konfiguriert automatisch alle noetigen Variablen:

Variable	Wert in Test-Umgebung
DATABASE_URL	postgresql://breakpilot:breakpilot_test@postgres-test:5432/breakpilot_test
CONSENT_SERVICE_URL	http://consent-service-test:8081
VALKEY_URL	redis://valkey-test:6379
REDIS_URL	redis://valkey-test:6379
JWT_SECRET	test-jwt-secret-for-integration-tests
ENVIRONMENT	test
SMTP_HOST	mailpit-test
SMTP_PORT	1025

conftest.py Integration

Das backend/tests/conftest.py erkennt automatisch die Integration-Umgebung:

# Wird aktiviert wenn SKIP_INTEGRATION_TESTS=false
IS_INTEGRATION_ENV = os.environ.get("SKIP_INTEGRATION_TESTS", "").lower() == "false"

if IS_INTEGRATION_ENV:
    os.environ.setdefault("DATABASE_URL",
        "postgresql://breakpilot:breakpilot_test@postgres-test:5432/breakpilot_test")
    # ... weitere Container-URLs

---

6. Troubleshooting

Service startet nicht

# Logs eines spezifischen Services anzeigen
docker compose -f docker-compose.test.yml logs consent-service-test --tail=100

# Alle Logs anzeigen
docker compose -f docker-compose.test.yml logs

Health Check schlaegt fehl

# Container-Status pruefen
docker compose -f docker-compose.test.yml ps

# In Container einloggen
docker compose -f docker-compose.test.yml exec backend-test bash

# Health-Endpoint manuell pruefen
docker compose -f docker-compose.test.yml exec backend-test curl -v http://localhost:8000/health

Datenbank-Verbindungsprobleme

# Datenbank-Container pruefen
docker compose -f docker-compose.test.yml exec postgres-test pg_isready -U breakpilot

# Datenbank-Logs
docker compose -f docker-compose.test.yml logs postgres-test

Port-Konflikte

Falls Ports bereits belegt sind:

# Pruefen welcher Prozess den Port belegt
lsof -i :55432

# Container mit anderen Ports starten (manuell .yml anpassen)
# Oder: Bestehende Container stoppen
docker compose -f docker-compose.test.yml down

Tests finden keine Services

Stellen Sie sicher, dass:

1. SKIP_INTEGRATION_TESTS=false gesetzt ist
2. Tests innerhalb des Docker-Netzwerks laufen
3. Container-Namen (nicht localhost) verwendet werden

# Innerhalb des Backend-Containers:
export SKIP_INTEGRATION_TESTS=false
pytest tests/test_integration/ -v

Cleanup bei Problemen

# Komplettes Aufräumen
docker compose -f docker-compose.test.yml down -v --remove-orphans

# Auch Netzwerke entfernen
docker network prune -f

# Alle Test-Container entfernen
docker rm -f $(docker ps -a -q --filter "name=breakpilot-*-test") 2>/dev/null || true

---

Anhang: Test-Verzeichnisstruktur

backend/tests/
├── conftest.py              # Pytest Konfiguration mit Integration-Detection
├── test_consent_client.py   # Unit Tests (Mock-basiert)
├── test_gdpr_api.py         # Unit Tests
└── test_integration/        # Integration Tests (benoetigen Docker Compose)
    ├── __init__.py
    ├── conftest.py          # Integration-spezifische Fixtures
    ├── test_consent_flow.py # E2E Consent Workflow
    ├── test_auth_flow.py    # E2E Auth Workflow
    └── test_email_flow.py   # E2E E-Mail Tests (Mailpit)

---

Generiert am 2026-02-04 von Claude Code