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

# Integration Test Environment

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

---

## Inhaltsverzeichnis

1. [Uebersicht](#1-uebersicht)
2. [Quick Start (Lokal)](#2-quick-start-lokal)
3. [Services](#3-services)
4. [CI/CD Integration](#4-cicd-integration)
5. [Konfiguration](#5-konfiguration)
6. [Troubleshooting](#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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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`:

```yaml
# .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

```bash
# 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:

```python
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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

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

### Cleanup bei Problemen

```bash
# 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*