docs: Improve frontend migration guide visibility and remove obsolete test files
- Add prominent migration guide reference in README.dev.md API section - Remove backend/TESTING.md (info now in README.dev.md) - Remove backend/test-openapi-paths.js (replaced by automated tests)
This commit is contained in:
parent
cdb2aa95e6
commit
36e7302677
|
|
@ -1,5 +1,24 @@
|
|||
# Development Setup
|
||||
|
||||
## ⚠️ Wichtige Hinweise für Frontend-Entwickler
|
||||
|
||||
### 🔴 BREAKING CHANGES - API-Umstrukturierung (November 2025)
|
||||
|
||||
Im Rahmen der OpenAPI-Auto-Generation wurden **massive Änderungen** an der API-Struktur vorgenommen:
|
||||
|
||||
- **Authentication**: Alle Admin-Endpoints benötigen jetzt Bearer Token
|
||||
- **Route-Struktur**: Einige Pfade haben sich geändert (Single Source of Truth: `routeMappings.js`)
|
||||
- **Error Handling**: Neue HTTP-Status-Codes (403 für Auth-Fehler)
|
||||
|
||||
**📖 Siehe:**
|
||||
- **`frontend/MIGRATION-GUIDE.md`** - Detaillierte Migrations-Anleitung für Frontend
|
||||
- **`backend/src/routes/README.md`** - Vollständige API-Route-Dokumentation
|
||||
- **`AUTHENTICATION.md`** - Auth-System-Setup und Verwendung
|
||||
|
||||
**Geschätzter Migrations-Aufwand**: 2-3 Stunden
|
||||
|
||||
---
|
||||
|
||||
## Schnellstart
|
||||
|
||||
### Starten (Development Environment)
|
||||
|
|
@ -33,6 +52,15 @@ docker compose -f docker/dev/docker-compose.yml logs -f backend-dev
|
|||
|
||||
## API-Entwicklung
|
||||
|
||||
### ⚠️ BREAKING CHANGES - Frontend Migration erforderlich
|
||||
|
||||
**Massive API-Änderungen im November 2025:**
|
||||
- Bearer Token Authentication für alle Admin-Endpoints
|
||||
- Route-Pfade umstrukturiert (siehe `routeMappings.js`)
|
||||
- Neue Error-Response-Formate
|
||||
|
||||
**📖 Frontend Migration Guide**: `frontend/MIGRATION-GUIDE.md`
|
||||
|
||||
### Route-Struktur
|
||||
|
||||
Die API verwendet eine **Single Source of Truth** für Route-Mappings:
|
||||
|
|
|
|||
|
|
@ -1,297 +0,0 @@
|
|||
# API Testing Guide
|
||||
|
||||
## 🎯 Testing-Strategie
|
||||
|
||||
### 1. Smoke Tests (Aktuell)
|
||||
|
||||
**Script:** `test-openapi-paths.js`
|
||||
|
||||
**Was wird getestet:**
|
||||
- ✅ Alle Pfade sind erreichbar
|
||||
- ✅ Server antwortet
|
||||
- ❌ Keine Schema-Validierung
|
||||
- ❌ Keine Auth-Tests
|
||||
- ❌ Keine Request Bodies
|
||||
|
||||
**Verwendung:**
|
||||
```bash
|
||||
npm run test-openapi
|
||||
```
|
||||
|
||||
**Zweck:** Schneller Check ob alle Routen mounted sind.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Empfohlene Testing-Tools
|
||||
|
||||
### Option 1: Dredd (Contract Testing) ⭐ EMPFOHLEN
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
npm install --save-dev dredd
|
||||
```
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
# dredd.yml erstellen
|
||||
cat > dredd.yml << EOF
|
||||
color: true
|
||||
dry-run: false
|
||||
hookfiles: null
|
||||
language: nodejs
|
||||
require: null
|
||||
server: npm start
|
||||
server-wait: 3
|
||||
init: false
|
||||
custom: {}
|
||||
names: false
|
||||
only: []
|
||||
reporter: []
|
||||
output: []
|
||||
header: []
|
||||
sorted: false
|
||||
user: null
|
||||
inline-errors: false
|
||||
details: false
|
||||
method: []
|
||||
loglevel: warning
|
||||
path: []
|
||||
blueprint: docs/openapi.json
|
||||
endpoint: http://localhost:5000
|
||||
EOF
|
||||
```
|
||||
|
||||
**Ausführen:**
|
||||
```bash
|
||||
npx dredd
|
||||
```
|
||||
|
||||
**Vorteile:**
|
||||
- ✅ Validiert Responses gegen OpenAPI-Schema
|
||||
- ✅ Testet alle HTTP-Methoden
|
||||
- ✅ Prüft Request/Response Bodies
|
||||
- ✅ Unterstützt Hooks für Auth
|
||||
|
||||
---
|
||||
|
||||
### Option 2: Postman + Newman
|
||||
|
||||
**Setup:**
|
||||
1. OpenAPI importieren:
|
||||
- Öffne Postman
|
||||
- File → Import → `backend/docs/openapi.json`
|
||||
|
||||
2. Collection generieren lassen
|
||||
|
||||
3. Tests hinzufügen (automatisch oder manuell)
|
||||
|
||||
4. Export als Collection
|
||||
|
||||
**CLI-Tests:**
|
||||
```bash
|
||||
npm install --save-dev newman
|
||||
npx newman run postman_collection.json
|
||||
```
|
||||
|
||||
**Vorteile:**
|
||||
- ✅ GUI für manuelles Testen
|
||||
- ✅ Automatische Test-Generierung
|
||||
- ✅ CI/CD Integration
|
||||
- ✅ Environment Variables
|
||||
|
||||
---
|
||||
|
||||
### Option 3: Prism (Mock + Validate)
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
npm install --save-dev @stoplight/prism-cli
|
||||
```
|
||||
|
||||
**Mock Server starten:**
|
||||
```bash
|
||||
npx prism mock docs/openapi.json
|
||||
# Server läuft auf http://localhost:4010
|
||||
```
|
||||
|
||||
**Validierung:**
|
||||
```bash
|
||||
npx prism validate docs/openapi.json
|
||||
```
|
||||
|
||||
**Vorteile:**
|
||||
- ✅ Mock Server für Frontend-Entwicklung
|
||||
- ✅ Schema-Validierung
|
||||
- ✅ Contract Testing
|
||||
- ✅ Keine echte API nötig
|
||||
|
||||
---
|
||||
|
||||
### Option 4: Jest + Supertest (Unit/Integration Tests)
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
npm install --save-dev jest supertest jest-openapi
|
||||
```
|
||||
|
||||
**Beispiel Test:**
|
||||
```javascript
|
||||
// tests/api/groups.test.js
|
||||
const request = require('supertest');
|
||||
const jestOpenAPI = require('jest-openapi');
|
||||
const app = require('../../src/server');
|
||||
|
||||
// Load OpenAPI spec
|
||||
jestOpenAPI(require('../../docs/openapi.json'));
|
||||
|
||||
describe('Groups API', () => {
|
||||
it('GET /api/groups should return valid response', async () => {
|
||||
const response = await request(app)
|
||||
.get('/api/groups')
|
||||
.expect(200);
|
||||
|
||||
// Validate against OpenAPI schema
|
||||
expect(response).toSatisfyApiSpec();
|
||||
|
||||
// Custom assertions
|
||||
expect(response.body).toHaveProperty('groups');
|
||||
expect(Array.isArray(response.body.groups)).toBe(true);
|
||||
});
|
||||
|
||||
it('GET /api/groups/:groupId should return 404 for invalid ID', async () => {
|
||||
const response = await request(app)
|
||||
.get('/api/groups/invalid-id')
|
||||
.expect(404);
|
||||
|
||||
expect(response).toSatisfyApiSpec();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**package.json:**
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"test": "jest",
|
||||
"test:watch": "jest --watch",
|
||||
"test:coverage": "jest --coverage"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Vorteile:**
|
||||
- ✅ Vollständige Integration Tests
|
||||
- ✅ Schema-Validierung mit jest-openapi
|
||||
- ✅ Code Coverage
|
||||
- ✅ CI/CD Integration
|
||||
- ✅ Watch Mode für TDD
|
||||
|
||||
---
|
||||
|
||||
## 📊 Vergleich
|
||||
|
||||
| Tool | Setup | Schema Validation | Auth Support | CI/CD | Best For |
|
||||
|------|-------|-------------------|--------------|-------|----------|
|
||||
| **test-openapi-paths.js** | ✅ Fertig | ❌ | ❌ | ✅ | Quick smoke test |
|
||||
| **Dredd** | ⚠️ Mittel | ✅ | ✅ | ✅ | Contract testing |
|
||||
| **Postman/Newman** | ⚠️ Mittel | ✅ | ✅ | ✅ | Manual + automated |
|
||||
| **Prism** | ✅ Easy | ✅ | ⚠️ | ✅ | Mock + validate |
|
||||
| **Jest + Supertest** | ⚠️ Komplex | ✅ | ✅ | ✅ | Full testing suite |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Empfehlung für dieses Projekt
|
||||
|
||||
### Phase 1: Quick Wins (Jetzt)
|
||||
```bash
|
||||
# 1. Behalte aktuelles Smoke-Test Script
|
||||
npm run test-openapi
|
||||
|
||||
# 2. Installiere Prism für Validierung
|
||||
npm install --save-dev @stoplight/prism-cli
|
||||
|
||||
# 3. Validiere OpenAPI Spec
|
||||
npm run validate-openapi # (siehe unten)
|
||||
```
|
||||
|
||||
### Phase 2: Contract Testing (Später)
|
||||
```bash
|
||||
# 1. Installiere Dredd
|
||||
npm install --save-dev dredd
|
||||
|
||||
# 2. Erstelle dredd.yml (siehe oben)
|
||||
|
||||
# 3. Schreibe Hooks für Auth
|
||||
# tests/dredd-hooks.js
|
||||
|
||||
# 4. Führe aus
|
||||
npm run test:contract
|
||||
```
|
||||
|
||||
### Phase 3: Full Testing Suite (Optional)
|
||||
```bash
|
||||
# Jest + Supertest + jest-openapi
|
||||
npm install --save-dev jest supertest jest-openapi @types/jest
|
||||
|
||||
# Schreibe Integration Tests in tests/
|
||||
npm run test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Neue NPM Scripts
|
||||
|
||||
Füge zu `package.json` hinzu:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"test-openapi": "node test-openapi-paths.js",
|
||||
"validate-openapi": "prism validate docs/openapi.json",
|
||||
"test:contract": "dredd",
|
||||
"test": "jest",
|
||||
"test:watch": "jest --watch"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Swagger-eigene Test-Tools
|
||||
|
||||
**Swagger Inspector:**
|
||||
- Online: https://inspector.swagger.io/
|
||||
- Import `openapi.json`
|
||||
- Manuelles Testen in GUI
|
||||
- Kann Test-Collections exportieren
|
||||
|
||||
**Swagger Codegen:**
|
||||
```bash
|
||||
# Generiert Client-Code + Tests
|
||||
npx @openapitools/openapi-generator-cli generate \
|
||||
-i docs/openapi.json \
|
||||
-g javascript \
|
||||
-o generated-client
|
||||
```
|
||||
|
||||
**Swagger UI "Try it out":**
|
||||
- Bereits aktiv unter http://localhost:5000/api/docs
|
||||
- Manuelles Testing direkt in Browser
|
||||
- ✅ Einfachstes Tool für Quick Tests
|
||||
|
||||
---
|
||||
|
||||
## ✅ Fazit
|
||||
|
||||
**Aktuell:** `test-openapi-paths.js` ist OK für Smoke Tests.
|
||||
|
||||
**Nächster Schritt:**
|
||||
1. Installiere **Prism** für Schema-Validierung
|
||||
2. Später: **Dredd** für Contract Testing
|
||||
3. Optional: **Jest** für vollständige Test-Suite
|
||||
|
||||
**Best Practice:** Kombiniere mehrere Tools:
|
||||
- Prism für Schema-Validierung
|
||||
- Dredd für Contract Testing
|
||||
- Jest für Unit/Integration Tests
|
||||
- Swagger UI für manuelles Testing
|
||||
|
|
@ -1,64 +0,0 @@
|
|||
/**
|
||||
* OpenAPI Path Validator
|
||||
*
|
||||
* Basic smoke test to verify all OpenAPI paths are reachable.
|
||||
* Does NOT replace proper API testing!
|
||||
*
|
||||
* For comprehensive testing, consider:
|
||||
* - Dredd (npm install -g dredd) - Contract testing against OpenAPI spec
|
||||
* - Postman/Newman - Import openapi.json and run automated tests
|
||||
* - Prism (npm install -g @stoplight/prism-cli) - Mock server + validation
|
||||
* - Jest/Supertest - Full integration tests with schema validation
|
||||
*
|
||||
* This script only checks if paths respond (basic reachability check).
|
||||
*/
|
||||
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
|
||||
// Read generated openapi.json
|
||||
const specPath = path.join(__dirname, 'docs', 'openapi.json');
|
||||
const spec = JSON.parse(fs.readFileSync(specPath, 'utf8'));
|
||||
|
||||
const baseUrl = 'http://localhost:5000';
|
||||
const paths = Object.keys(spec.paths || {});
|
||||
|
||||
console.log(`🔍 Testing ${paths.length} paths from openapi.json against ${baseUrl}\n`);
|
||||
|
||||
async function testPath(path, methods) {
|
||||
const method = Object.keys(methods)[0]; // take first method (usually GET)
|
||||
const url = `${baseUrl}${path}`;
|
||||
|
||||
return new Promise((resolve) => {
|
||||
const http = require('http');
|
||||
const req = http.request(url, { method: method.toUpperCase() }, (res) => {
|
||||
const status = res.statusCode;
|
||||
const statusEmoji = status === 200 ? '✅' : status === 404 ? '❌' : '⚠️';
|
||||
console.log(`${statusEmoji} ${method.toUpperCase()} ${path} → ${status}`);
|
||||
resolve({ path, status, ok: status === 200 });
|
||||
});
|
||||
req.on('error', (err) => {
|
||||
console.log(`💥 ${method.toUpperCase()} ${path} → ERROR: ${err.message}`);
|
||||
resolve({ path, status: 'ERROR', ok: false });
|
||||
});
|
||||
req.end();
|
||||
});
|
||||
}
|
||||
|
||||
(async () => {
|
||||
const results = [];
|
||||
for (const p of paths) {
|
||||
const result = await testPath(p, spec.paths[p]);
|
||||
results.push(result);
|
||||
}
|
||||
|
||||
const failed = results.filter(r => !r.ok);
|
||||
console.log(`\n📊 Summary: ${results.length} paths tested, ${failed.length} failed\n`);
|
||||
|
||||
if (failed.length > 0) {
|
||||
console.log('❌ Failed paths (likely missing route prefixes):');
|
||||
failed.forEach(f => console.log(` ${f.path} → ${f.status}`));
|
||||
console.log('\n💡 Hint: Generator scanned route files without mount prefixes.');
|
||||
console.log(' Check backend/src/routes/index.js for app.use() calls with prefixes like /api/admin');
|
||||
}
|
||||
})();
|
||||
Loading…
Reference in New Issue
Block a user