mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
92028d9e02
meldestelle/docs/07_Infrastructure/runbooks/POSTMAN_API_Tests_Runbook.md

7.0 KiB
Raw Blame History

type status owner tags last_update
Runbook ACTIVE QA Specialist
postman
testing
api
backend
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 (Einstiegspunkt für alle APIs)
  • Keycloak: http://localhost:8180
  • Ping‑Service (direkt): http://localhost:8082
  • ZNS‑Import (direkt): http://localhost:8095
  • Consul: http://localhost:8500

Hinweis: Nutze für Postman immer die gateway_url (:8081), um die Security- und Routing-Logik des Systems zu testen.

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
  1. 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)
  1. API‑Gateway Health
  • Methode: GET
  • URL: {{gateway_url}}/actuator/health
  • Auth: Keine
  • Erwartet: 200 OK mit { "status": "UP" }
  1. 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", ...}
  1. Health
  • GET {{gateway_url}}/api/ping/health
  • Erwartet: 200 OK mit {"status":"up", ...}
  1. 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
  1. Sync Ping (unauthenticated)
  • GET {{gateway_url}}/api/ping/sync?since=0
  • Erwartet: 401 Unauthorized (Sicherheit erhöht)
  1. Enhanced Ping (unauthenticated)
  • GET {{gateway_url}}/api/ping/enhanced
  • 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", ...}
  1. 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
  1. 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.