test: Add Pact mock server

Author: ArneLimburg

.github/workflows/build.yaml

@@ -39,6 +39,12 @@ jobs:
         run: npm run test
         working-directory: customer-client
 
+      - name: Upload pact files
+        uses: actions/upload-artifact@v4
+        with:
+          name: pact-files
+          path: pacts/
+
       - name: Upload Playwright report
         uses: actions/upload-artifact@v4
         if: failure()
@@ -47,6 +53,7 @@ jobs:
           path: customer-client/playwright-report/
 
   build:
+    needs: build-client
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -59,6 +66,12 @@ jobs:
           distribution: 'temurin'
           cache: maven
 
+      - name: Download pact files
+        uses: actions/download-artifact@v4
+        with:
+          name: pact-files
+          path: pacts/
+
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:

README.md

@@ -2,38 +2,57 @@
 
 Herzlich willkommen zum Workshop API Design.
 
-## Übungen
+## Übung: Von Playwright-Mocking zu Pact Consumer Tests
 
-### API Design
+### Ausgangssituation
 
-- [OpenAPI](https://github.com/openknowledge/workshop-api-design/tree/openapi)
-- [Mocking](https://github.com/openknowledge/workshop-api-design/tree/wiremock)
-- [AsyncAPI](https://github.com/openknowledge/workshop-api-design/tree/asyncapi)
+Im Branch `playwright-pact` befinden sich drei Playwright-Testdateien im Verzeichnis `customer-client/test/`:
 
-### API Testing
+- `customer-list.spec.ts` – Tests für die Kundenliste
+- `customer-detail.spec.ts` – Tests für die Kundendetailansicht inkl. Adressen
+- `create-customer.spec.ts` – Tests für das Anlegen eines neuen Kunden (**bereits auf Pact umgebaut, dient als Referenz**)
 
-- [Pact](https://github.com/openknowledge/workshop-api-design/tree/pact-mock-server)
-- [Pact Pipeline](https://github.com/openknowledge/workshop-api-design/tree/pact)
+Die Tests in `customer-list.spec.ts` und `customer-detail.spec.ts` verwenden aktuell Playwright's eingebautes `page.route()`, um API-Aufrufe direkt im Browser abzufangen und mit statischen Antworten zu mocken. Dieser Ansatz dokumentiert den API-Vertrag nicht maschinenlesbar und kann nicht automatisch gegen den echten Service verifiziert werden.
 
-### API Security
+Das Hilfsmuster `pact-proxy.ts` stellt zwei Funktionen bereit:
+- `createProvider()` – erstellt einen Pact-Mock-Server mit Consumer- und Providernamen
+- `setupApiProxy(page, mockServerUrl)` – leitet alle API-Aufrufe der Seite transparent an den Pact-Mock-Server weiter
 
-- [JWT](https://github.com/openknowledge/workshop-api-design/tree/jwt)
-- [OAuth2](https://github.com/openknowledge/workshop-api-design/tree/oauth2)
-- [OAuth2 mit PKCE](https://github.com/openknowledge/workshop-api-design/tree/oauth2-pkce)
+### Aufgabe
 
-### API Governance
+Baue die Playwright-Tests in `customer-list.spec.ts` und `customer-detail.spec.ts` so um, dass sie statt `page.route()` den Pact-Mock-Server nutzen. Orientiere dich dabei an `create-customer.spec.ts`.
 
-- [Linting](https://github.com/openknowledge/workshop-api-design/tree/linting)
+Für jeden Test, der API-Aufrufe mockt, gilt folgendes Muster:
 
-### API Management
+```typescript
+await createProvider()
+  .addInteraction({
+    uponReceiving: 'Beschreibung der Anfrage',
+    withRequest: {
+      method: 'GET',
+      path: '/customers/',
+    },
+    willRespondWith: {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+      body: [ /* ... */ ],
+    },
+  })
+  .executeTest(async (mockServer) => {
+    await setupApiProxy(page, mockServer.url);
+    // eigentlicher Test
+  });
+```
 
-- [Rate Limiting](https://github.com/openknowledge/workshop-api-design/tree/rate-limiting)
-- [Backstage](https://github.com/openknowledge/workshop-api-design/tree/backstage)
+**Hinweise:**
+- Tests, die keinerlei API-Aufrufe machen (z. B. reine UI-Validierungen), müssen nicht umgebaut werden.
+- Wenn ein Test mehrere API-Endpunkte anspricht, können mehrere `.addInteraction()`-Aufrufe verkettet werden.
+- Nach dem Umbau werden die Pact-Dateien automatisch im Verzeichnis `pacts/` erzeugt. Prüfe, ob die erzeugten Pacts den erwarteten Vertrag korrekt abbilden.
+- `beforeEach`-Blöcke mit `page.route()` müssen in die jeweiligen `executeTest`-Callbacks verschoben werden, weil `setupApiProxy` erst innerhalb des Callbacks aufgerufen werden kann.
 
-### API Operation
+### Ziel
 
-- [Observability](https://github.com/openknowledge/workshop-api-design/tree/observability)
+Nach dem Umbau laufen alle Tests weiterhin erfolgreich, und im Verzeichnis `pacts/` liegt eine aktualisierte JSON-Datei mit den Consumer-Driven Contracts, die später gegen den echten Customer Service verifiziert werden können.
 
-### API Evolution
+Der entstandene Contract kann mit dem Provider Test `CustomerServiceTest.java` im Customer Service gegen die echte Implementierung überprüft werden.
 
-- [Versioning](https://github.com/openknowledge/workshop-api-design/tree/versioning)