Archive outdated journal logs and documents. Add Postman Runbook structure and centralize API testing documentation. Update Flyway configuration for ping-service with service-specific schema history.
This commit is contained in:
@@ -0,0 +1,206 @@
|
||||
---
|
||||
type: Runbook
|
||||
status: ACTIVE
|
||||
owner: QA Specialist
|
||||
tags: [postman, testing, api, backend]
|
||||
last_update: 2026-04-03
|
||||
---
|
||||
# Runbook: API-Tests mit Postman (für Nicht‑Programmierer)
|
||||
|
||||
> Ziel: Alle Kern-APIs der Meldestelle lokal prüfen – sicher, reproduzierbar und ohne Programmierkenntnisse.
|
||||
|
||||
Inhalt:
|
||||
1. Voraussetzungen (Docker-Profile starten)
|
||||
2. Postman einrichten (Collection + Environment)
|
||||
3. Login/Token beschaffen
|
||||
4. Smoke‑Tests (System & Health)
|
||||
5. Ping‑Service durchtesten (ohne/mit Login, Resilience)
|
||||
6. Master‑Data & Pferde (Beispiele)
|
||||
7. Empfohlene Test‑Reihenfolge
|
||||
8. Troubleshooting & FAQ
|
||||
|
||||
---
|
||||
|
||||
## 1. Voraussetzungen
|
||||
|
||||
Bitte sicherstellen, dass die lokale Umgebung läuft:
|
||||
|
||||
- Infrastruktur starten: `docker compose --profile infra up -d`
|
||||
- Backend starten: `docker compose --profile backend up -d`
|
||||
|
||||
Standard‑Ports (lokal):
|
||||
- Gateway: `http://localhost:8081`
|
||||
- Keycloak: `http://localhost:8180`
|
||||
- Ping‑Service (direkt): `http://localhost:8082`
|
||||
- ZNS‑Import (direkt): `http://localhost:8095`
|
||||
- Consul: `http://localhost:8500`
|
||||
|
||||
Hinweis: Warte 30–60 Sekunden nach dem Start, bis alle Dienste „UP“ sind.
|
||||
|
||||
---
|
||||
|
||||
## 2. Postman einrichten
|
||||
|
||||
### 2.1 Collection importieren
|
||||
1. Postman öffnen → „Import“ → Datei wählen:
|
||||
```
|
||||
backend/infrastructure/gateway/src/main/resources/static/docs/postman/Meldestelle_API_Collection.json
|
||||
```
|
||||
2. Die Collection „Meldestelle API Collection“ erscheint links.
|
||||
|
||||
### 2.2 Environment anlegen (z. B. „Meldestelle Local“)
|
||||
Trage folgende Variablen ein:
|
||||
|
||||
| Variable | Wert (Initial) | Beschreibung |
|
||||
|---|---|---|
|
||||
| `gateway_url` | `http://localhost:8081` | API‑Gateway Einstieg |
|
||||
| `auth_url` | `http://localhost:8180/realms/meldestelle/protocol/openid-connect/token` | Token‑Endpoint |
|
||||
| `client_id` | `postman-client` | Keycloak Client |
|
||||
| `client_secret` | `postman-secret-123` | Secret zum Client |
|
||||
| `username` | `admin` | Testuser |
|
||||
| `password` | `Admin#1234` | Passwort |
|
||||
| `ping_url` | `http://localhost:8082` | Direkter Ping‑Service |
|
||||
| `zns_url` | `http://localhost:8095` | Direkter ZNS‑Import |
|
||||
| `consul_url` | `http://localhost:8500` | Consul UI |
|
||||
| `auth_token` | (leer) | Wird nach Login automatisch befüllt |
|
||||
| `horse_id` | (leer) | Wird bei Pferde‑Tests befüllt |
|
||||
| `country_id` | (leer) | Wird bei Länder‑Tests befüllt |
|
||||
|
||||
---
|
||||
|
||||
## 3. Login/Token beschaffen
|
||||
|
||||
In Postman im Reiter „Authorization“ (Request „Login“ in der Collection nutzen oder manuell):
|
||||
- Type: „OAuth 2.0“
|
||||
- Grant Type: „Password Credentials“
|
||||
- Access Token URL: `{{auth_url}}`
|
||||
- Client ID: `{{client_id}}`
|
||||
- Client Secret: `{{client_secret}}`
|
||||
- Username: `{{username}}`
|
||||
- Password: `{{password}}`
|
||||
- Button „Get New Access Token“ → „Use Token“
|
||||
|
||||
Das Token wird im Environment als `auth_token` gespeichert (Pre‑Request Scripts der Collection setzen es automatisch, sofern vorhanden).
|
||||
|
||||
---
|
||||
|
||||
## 4. Smoke‑Tests (immer zuerst)
|
||||
|
||||
Zweck: Schnell prüfen, ob das System erreichbar und „UP“ ist.
|
||||
|
||||
1) API‑Gateway Info
|
||||
- Methode: `GET`
|
||||
- URL: `{{gateway_url}}/actuator/info`
|
||||
- Auth: Keine
|
||||
- Erwartet: `200 OK` (leerer JSON‑Body ist aktuell normal)
|
||||
|
||||
2) API‑Gateway Health
|
||||
- Methode: `GET`
|
||||
- URL: `{{gateway_url}}/actuator/health`
|
||||
- Auth: Keine
|
||||
- Erwartet: `200 OK` mit `{ "status": "UP" }`
|
||||
|
||||
3) OpenAPI (optional)
|
||||
- Methode: `GET`
|
||||
- URL: `{{gateway_url}}/v3/api-docs`
|
||||
- Erwartet: `200 OK` (OpenAPI JSON)
|
||||
|
||||
---
|
||||
|
||||
## 5. Ping‑Service Tests
|
||||
|
||||
### 5.1 Öffentlich (ohne Login)
|
||||
1) Simple Ping
|
||||
- `GET {{gateway_url}}/api/ping/simple`
|
||||
- Erwartet: `200 OK` mit `{"status":"pong", ...}`
|
||||
|
||||
2) Health
|
||||
- `GET {{gateway_url}}/api/ping/health`
|
||||
- Erwartet: `200 OK` mit `{"status":"up", ...}`
|
||||
|
||||
3) Public Ping
|
||||
- `GET {{gateway_url}}/api/ping/public`
|
||||
- Erwartet: `200 OK`
|
||||
|
||||
### 5.2 Sicherheit (Negativ‑Test, ohne Login)
|
||||
1) Secure Ping (unauthenticated)
|
||||
- `GET {{gateway_url}}/api/ping/secure`
|
||||
- Erwartet: `401 Unauthorized`
|
||||
|
||||
2) Sync Ping (unauthenticated)
|
||||
- `GET {{gateway_url}}/api/ping/sync`
|
||||
- Erwartet: `401 Unauthorized`
|
||||
|
||||
### 5.3 Authentifiziert (mit Token)
|
||||
1) Secure Ping (authenticated)
|
||||
- `GET {{gateway_url}}/api/ping/secure`
|
||||
- Auth: OAuth 2.0 (Token)
|
||||
- Erwartet: `200 OK` mit `{"status":"secure-pong", ...}`
|
||||
|
||||
2) Sync Ping (authenticated)
|
||||
- `GET {{gateway_url}}/api/ping/sync?lastSyncTimestamp=0`
|
||||
- Erwartet: `200 OK` (Liste von Events)
|
||||
|
||||
### 5.4 Resilience (Circuit Breaker Demo)
|
||||
1) Enhanced Ping (normal)
|
||||
- `GET {{gateway_url}}/api/ping/enhanced` → `200 OK`
|
||||
|
||||
2) Enhanced Ping (Fehler provozieren)
|
||||
- `GET {{gateway_url}}/api/ping/enhanced?simulate=true` mehrfach senden
|
||||
- Erwartet: teils `500`, danach Fallback‑Antwort mit `circuitBreakerState: "OPEN"`
|
||||
|
||||
---
|
||||
|
||||
## 6. Master‑Data & Pferde (Beispiele)
|
||||
|
||||
Hinweis: Endpunkte können sich ändern. Maßgeblich ist die OpenAPI unter `{{gateway_url}}/v3/api-docs` sowie die importierte Postman‑Collection.
|
||||
|
||||
### 6.1 Countries
|
||||
- Create: `POST {{gateway_url}}/api/masterdata/countries` (Body siehe Collection)
|
||||
- Read: `GET {{gateway_url}}/api/masterdata/countries/{{country_id}}`
|
||||
- Erwartet: `201 Created` bei Anlage, `200 OK` beim Lesen.
|
||||
|
||||
### 6.2 Horse Registry
|
||||
- Create: `POST {{gateway_url}}/api/horses` → speichert `{{horse_id}}`
|
||||
- Get: `GET {{gateway_url}}/api/horses/{{horse_id}}`
|
||||
- Delete (optional): `DELETE {{gateway_url}}/api/horses/{{horse_id}}`
|
||||
|
||||
---
|
||||
|
||||
## 7. Empfohlene Test‑Reihenfolge (Checkliste)
|
||||
|
||||
1) Infrastruktur & Backend starten (Docker Profiles)
|
||||
2) Collection importieren, Environment setzen
|
||||
3) Smoke‑Tests (Info, Health, OpenAPI)
|
||||
4) Ping öffentlich (simple, health, public)
|
||||
5) Negativ‑Tests (secure/sync ohne Token → 401)
|
||||
6) Login/Token holen
|
||||
7) Ping authentifiziert (secure/sync)
|
||||
8) Resilience testen (enhanced, simulate=true)
|
||||
9) Optionale Domänen‑Tests (Countries, Horses)
|
||||
|
||||
---
|
||||
|
||||
## 8. Troubleshooting & FAQ
|
||||
|
||||
- 401 Unauthorized trotz Login:
|
||||
- Token wirklich gesetzt? In Postman „Use Token“ klicken; im Request unter „Authorization“ prüfen.
|
||||
- Uhrzeit/Zeitzone korrekt? Abgelaufene Tokens werden abgewiesen.
|
||||
- 502/503 vom Gateway:
|
||||
- Service wirklich „UP“? `{{gateway_url}}/actuator/health` und Container‑Logs prüfen: `docker compose ps` / `docker compose logs -f <service>`
|
||||
- Keycloak nicht erreichbar:
|
||||
- Warten Sie nach Start 30–60 Sekunden. Prüfen: `http://localhost:8180`.
|
||||
- OpenAPI leer oder 404:
|
||||
- Backend neu gestartet? Warten, bis Gateway die Routen geladen hat.
|
||||
|
||||
Weitere Details und Hintergründe finden Sie in der ursprünglichen, technischen Langfassung der QA‑Dokumentation (siehe Archiv‑Hinweis unten).
|
||||
|
||||
---
|
||||
|
||||
Quellen & Verweise:
|
||||
- Postman‑Collection: `backend/infrastructure/gateway/src/main/resources/static/docs/postman/Meldestelle_API_Collection.json`
|
||||
- Backend‑Referenz: `docs/05_Backend/Services/PingService_Reference.md`
|
||||
- OpenAPI: `{{gateway_url}}/v3/api-docs`
|
||||
|
||||
Archiv‑Hinweis:
|
||||
- Die frühere, sehr detaillierte Arbeitsversion „Postman Tests — Vollständige Dokumentation“ aus dem Agents‑Besprechungsordner wurde in dieses Runbook konsolidiert und ins Archiv verschoben.
|
||||
Reference in New Issue
Block a user