procurex-frontend

Angular-22-SPA (Standalone Components, @if/@for-Control-Flow) für PROCUREX — PRX-20

("Angular-Frontend-Struktur und Accessibility-Regeln festlegen").

Struktur

src/app/
├── core/
│   ├── models/           TypeScript-Interfaces, gespiegelt von den Backend-DTOs
│   ├── services/         HttpClient-Services (ein Service pro Bounded Context) + AuthService
│   ├── auth.config.ts    OIDC-Konfiguration (Keycloak, Authorization Code + PKCE)
│   ├── jwt.util.ts        Access-Token-Payload dekodieren (fuer Rollen-Claim, keine Signaturpruefung)
│   └── http-error.interceptor.ts   uebersetzt RFC-7807-Problem-Details in Nutzermeldungen
├── features/
│   ├── suppliers/        PRX-3
│   ├── catalog/          PRX-4
│   ├── cart/             PRX-2
│   └── orders/           PRX-12 (Liste) + PRX-5/PRX-8 (Genehmigung) + PRX-10 (Wareneingang)
│                          + PRX-11/PRX-9 (Rechnungspruefung) auf der Detailseite
├── app.ts / app.html     Shell: Skip-Link, Hauptnavigation, Login/Logout, Statusmeldung
└── app.routes.ts         Lazy-geladene Feature-Routen

Login (PRX-19, Umsetzung)

Echtes OIDC-Login über angular-oauth2-oidc (Authorization Code + PKCE) gegen den

Keycloak-Realm procurex (siehe ../keycloak/README.md für Testnutzer/Rollen). Solange nicht

eingeloggt, zeigt die Shell nur einen "Anmelden"-Button; nach dem Login steuert der

realm_access.roles-Claim aus dem Access Token (nicht dem ID-Token), welche Navigationspunkte und

Bestelldetail-Abschnitte sichtbar sind (AuthService.roles, siehe app.ts/order-detail.component.ts).

Das ist reine UI-Sichtbarkeit — die eigentliche Autorisierung erzwingt das Backend

(procurex-app/SecurityConfig), das jeden API-Call unabhängig vom Frontend gegen den Access

Token prüft.

Accessibility

Skip-Link zum Hauptinhalt
Alle Formularfelder mit <label for>, Fehlermeldungen über aria-invalid
Statusmeldungen (Erfolg/Fehler) als role="status" mit aria-live="polite"
Tabellen mit <caption> (visuell versteckt) und <th scope="col">
Sichtbarer Fokusindikator (:focus-visible) statt Browser-Default zu entfernen

API-Anbindung

environment.apiBaseUrl: lokal http://localhost:8081/api/v1, im Production-Build (ng build,

Docker/PRX-21) http://procurex-api.localhost/api/v1 (eigener Traefik-Host, siehe

environment.prod.ts und ../docker-compose.yml). Jeder API-Call bekommt automatisch den

Bearer-Token angehängt (provideOAuthClient mit resourceServer.allowedUrls, siehe app.config.ts).

Starten

Lokal:

npm install
npx ng serve

Voraussetzung: procurex-app läuft auf Port 8081, Keycloak auf keycloak.localhost (siehe

../procurex-app/README.md).

Docker (PRX-21): siehe ../docker-compose.yml und ../procurex-app/README.md.

Build & Test

npx ng build   # Production-Build nach dist/procurex-frontend
npx ng test --watch=false

E2E-Tests (PRX-33, Umsetzung)

Playwright-Tests unter e2e/, laufen gegen den echten docker-compose-Stack (Traefik, Keycloak,

Backend, Postgres) — kein Mock, echter Authorization-Code+PKCE-Redirect zu Keycloak inklusive

Ausfüllen des echten Keycloak-Login-Formulars (e2e/auth.ts).

Datei	Deckt ab
`login.spec.ts`	Nicht angemeldet zeigt Hinweis; Login als buyer1 zeigt Navigation/Rolle; Logout
`procure-to-pay.spec.ts`	Kompletter Kern-Ablauf: supplieradmin1 legt Lieferant+Katalogartikel an → buyer1 sendet Warenkorb ab → approver1 genehmigt dieselbe Bestellung (PRX-2, PRX-5/PRX-8)

Legt sich eigene Testdaten mit Zeitstempel-Suffix an, statt sich auf vorhandene Daten im Stack zu

verlassen.

npx playwright test        # Voraussetzung: docker compose up -d (siehe procurex-app/README.md)

Gefundener und behobener Bug dabei: Die Katalogsuche (CatalogItemRepository.search) schlug

mit HTTP 500 fehl, sobald die Seite ohne Suchbegriff geladen wurde (`function lower(bytea) does

not exist) — Postgres konnte den Typ des :query-Parameters nicht ableiten, wenn er null` war,

weil in der JPQL kein expliziter Cast stand. Behoben durch CAST(:query AS string) in der Query.

Der bestehende CatalogItemTest (Mockito, keine echte DB) konnte das strukturell nicht prüfen —

erst der echte Browser-Durchlauf gegen die echte Datenbank hat es aufgedeckt.

Playwright – was im Lernprojekt eingerichtet wurde

Playwright ist das für PRX-33 ausgewählte Werkzeug für End-to-End-Tests (E2E). Dabei wird ein

echter Browser automatisiert. Der Test prüft deshalb den Weg aus Sicht eines Benutzers: Angular-

Oberfläche, Keycloak-Login, Backend-REST-API und Datenbank werden gemeinsam durchlaufen.

Vorhandene Einrichtung

Abhängigkeit @playwright/test Version 1.62.1 in package.json und package-lock.json
Konfiguration in playwright.config.ts
Testverzeichnis e2e/
Gemeinsame Login-Hilfe in e2e/auth.ts
Chromium für die lokale Ausführung über den Playwright-Browser-Cache
npm-Script: npm run e2e

Die Installation befindet sich im Projekt lokal unter procurex-frontend/node_modules und wird

nicht in Git versioniert. Die Browser-Binaries liegen normalerweise außerhalb des Repositories

unter %LOCALAPPDATA%\ms-playwright. Versioniert werden nur Quellcode, Konfiguration und

Lockdatei, damit andere Lernende die Umgebung reproduzierbar mit npm ci aufbauen können.

Testablauf

Playwright startet Chromium
        ↓
PROCUREX-SPA öffnet Keycloak-Login
        ↓
Test meldet sich mit einem Testbenutzer an
        ↓
Angular ruft echte APIs mit OIDC/JWT auf
        ↓
Playwright prüft sichtbare Ergebnisse und Rollenverhalten

Die Tests laufen bewusst gegen den laufenden Docker-Compose-Stack. Dadurch werden keine

Backend- oder Browser-Services gemockt. Vor dem Lauf müssen daher mindestens Frontend, Traefik,

Keycloak, Backend und PostgreSQL erreichbar sein.

cd procurex-frontend
npm ci
npx playwright install chromium       # nur nötig, wenn Chromium noch fehlt
npm run e2e

Nützliche Varianten:

npx playwright test --list            # Tests nur auflisten
npx playwright test e2e/login.spec.ts # nur Login-Test
npx playwright test --headed          # Browser sichtbar anzeigen
npx playwright show-report             # lokalen HTML-Report öffnen, falls erzeugt

Die Tests erzeugen eigene Lieferanten, Katalogartikel und Bestellungen mit Zeitstempeln. Nach

einem Lauf können diese Datensätze in der lokalen Datenbank verbleiben und müssen bei Bedarf

manuell bereinigt werden. Ein vorhandener Testcode bedeutet außerdem nicht automatisch, dass ein

aktueller Lauf erfolgreich war: Dafür benötigt man einen Testreport oder einen nachvollziehbaren

CI-Log.

Jenkins-Ausführung

Das Jenkinsfile enthält ein optionales Stage Frontend: Playwright E2E. Es wird über den

Build-Parameter RUN_E2E=true aktiviert und verwendet das offizielle Playwright-Container-Image

mit Node.js und Browser-Binaries. Der Docker-Compose-Stack muss vor dem Build erreichbar sein;

das Stage startet keine dauerhafte Infrastruktur selbst. Testberichte und Screenshots werden als

Jenkins-Artefakte archiviert.

Der Standard-Build bleibt bei RUN_E2E=false, damit ein normaler Compile-/Unit-Test-Build nicht

unbemerkt eine Datenbank- oder Keycloak-Umgebung benötigt.

Selenium – alternative Technologie

Selenium ist ebenfalls ein etabliertes Werkzeug zur Browserautomatisierung. Tests werden meist

über Selenium WebDriver geschrieben. WebDriver kommuniziert mit dem jeweiligen Browser über einen

Browser-Treiber, zum Beispiel ChromeDriver oder GeckoDriver für Firefox.

Für PROCUREX wurde Selenium nicht zusätzlich eingerichtet und nicht ausgeführt. Es ist hier

als Vergleich und mögliche Alternative dokumentiert, damit die Technologieentscheidung

verständlich bleibt.

Playwright und Selenium im Vergleich

Kriterium	Playwright	Selenium
Browsersteuerung	Moderne Playwright-API über eine einheitliche Verbindung	WebDriver-Standard mit Browser-Treiber
Einrichtung	Ein npm-Paket plus verwaltete Browser-Binaries	Selenium-Bibliothek plus passende Treiber oder Selenium Grid
Sprachen	JavaScript/TypeScript, außerdem Python, Java und .NET	Sehr breite Sprachauswahl, unter anderem Java, JavaScript, Python und C#
Synchronisation	Automatisches Warten auf sichtbare und interaktive Elemente	Häufig explizite Waits erforderlich, moderne Selenium-Versionen unterstützen ebenfalls bessere Waits
Browserabdeckung	Chromium, Firefox und WebKit	Sehr breite Browser- und Grid-Unterstützung, auch Enterprise-Sonderfälle
Parallelisierung	Im Test Runner direkt integriert	Mit Selenium Grid, Test Runner oder CI-Konfiguration üblich
Debugging	Trace Viewer, Screenshots, Videos und HTML-Report integriert	Screenshots und Reports meist über zusätzliche Test- oder CI-Werkzeuge
PROCUREX-Passung	Sehr gut für Angular/TypeScript und den vorhandenen npm-Workflow	Möglich, aber zusätzlicher Treiber-/Grid- und Implementierungsaufwand

Entscheidung für dieses Projekt

Playwright passt im aktuellen Lernprojekt besser, weil das Frontend Angular und TypeScript nutzt,

die Tests im selben npm-Projekt liegen und der E2E-Test-Runner Traces, Screenshots und Reports

ohne zusätzliche Selenium-Grid-Infrastruktur unterstützt. Selenium wäre sinnvoll, wenn die

Plattform bereits einen zentralen Selenium Grid betreibt, viele unterschiedliche Browser-

Versionen verbindlich getestet werden müssen oder vorhandene Java-Selenium-Standards übernommen

werden sollen.

Die Entscheidung ist keine Aussage, dass Selenium schlechter ist. Beide Werkzeuge können den

PROCUREX-Kernprozess testen; Playwright ist lediglich die passendere und kleinere Lernprojekt-

Entscheidung für den derzeitigen Angular-/npm-Stack.

Kommerzielle Nutzung und Lizenzierung

Playwright und Selenium sind keine kostenpflichtigen kommerziellen Produkte im Sinne einer

verpflichtenden Laufzeit- oder Benutzerlizenz. Die Kernprojekte werden als Open Source unter der

Apache License 2.0 veröffentlicht. Damit ist eine Nutzung in einem kommerziellen Projekt

grundsätzlich möglich, sofern die Bedingungen der Apache-2.0-Lizenz eingehalten werden, zum

Beispiel Copyright- und Lizenzhinweise beibehalten sowie Änderungen korrekt gekennzeichnet

werden.

Für dieses Lernprojekt bedeutet das:

Playwright darf für interne, kommerzielle oder CI/CD-Tests eingesetzt werden.
Selenium darf ebenfalls für interne, kommerzielle oder CI/CD-Tests eingesetzt werden.
Es ist keine Playwright- oder Selenium-Subscription für die hier beschriebene Nutzung nötig.
Die Lizenz der verwendeten Browser, Container-Images, npm-Pakete und weiterer Abhängigkeiten

muss zusätzlich separat geprüft werden.

Diese Dokumentation ist keine Rechtsberatung; vor einem Produktiv- oder SaaS-Einsatz sollte

die konkrete Dependency-Liste durch die zuständige Rechts-/Compliance-Stelle geprüft werden.

Quellen: Playwright-Repository und Lizenz sowie

Selenium-Repository und Lizenz. Beide offiziellen

Repositories weisen die Apache-2.0-Lizenz aus.