Michael Schiemer
77abc65cd7
Some checks failed
Deploy Application / deploy (push) Has been cancelled
522 lines
13 KiB
Markdown
522 lines
13 KiB
Markdown
# Implementation Plan: Testing Infrastructure, Documentation & Middleware Support
|
|
|
|
## Übersicht
|
|
|
|
Dieser Plan umfasst drei große Bereiche:
|
|
1. **Test Infrastructure** - Verbesserte Test-Harness und Testing-Tools
|
|
2. **Documentation** - Vollständige Dokumentation für alle LiveComponents Features
|
|
3. **Middleware Support** - Component-Level Middleware für flexible Request/Response Transformation
|
|
|
|
---
|
|
|
|
## Phase 1: Test Infrastructure Verbesserung
|
|
|
|
### 1.1 LiveComponentTestCase Base Class
|
|
|
|
**Ziel**: Zentrale Test-Base-Class mit allen Helpers für einfache Component-Tests
|
|
|
|
**Datei**: `tests/Feature/Framework/LiveComponents/TestHarness/LiveComponentTestCase.php`
|
|
|
|
**Features**:
|
|
- `mount(string $componentId, array $initialData = [])` - Component mounten
|
|
- `call(string $action, array $params = [])` - Action aufrufen
|
|
- `seeHtmlHas(string $needle)` - HTML-Assertion
|
|
- `seeStateEquals(array $expectedState)` - State-Assertion
|
|
- `seeStateKey(string $key, mixed $value)` - Einzelne State-Key-Assertion
|
|
- `seeEventDispatched(string $eventName, ?array $payload = null)` - Event-Assertion
|
|
- `seeFragment(string $fragmentName, string $content)` - Fragment-Assertion
|
|
- `assertComponent(LiveComponentContract $component)` - Component-Instance-Assertion
|
|
|
|
**Architektur**:
|
|
```php
|
|
abstract class LiveComponentTestCase extends TestCase
|
|
{
|
|
protected ComponentRegistry $registry;
|
|
protected LiveComponentHandler $handler;
|
|
protected LiveComponentRenderer $renderer;
|
|
protected ?LiveComponentContract $currentComponent = null;
|
|
|
|
protected function setUp(): void
|
|
{
|
|
parent::setUp();
|
|
$this->registry = container()->get(ComponentRegistry::class);
|
|
$this->handler = container()->get(LiveComponentHandler::class);
|
|
$this->renderer = container()->get(LiveComponentRenderer::class);
|
|
}
|
|
|
|
protected function mount(string $componentId, array $initialData = []): self
|
|
{
|
|
$this->currentComponent = $this->registry->resolve(
|
|
ComponentId::fromString($componentId),
|
|
$initialData
|
|
);
|
|
return $this;
|
|
}
|
|
|
|
protected function call(string $action, array $params = []): self
|
|
{
|
|
// Action ausführen und Component aktualisieren
|
|
return $this;
|
|
}
|
|
|
|
protected function seeHtmlHas(string $needle): self
|
|
{
|
|
$html = $this->renderer->render($this->currentComponent);
|
|
expect($html)->toContain($needle);
|
|
return $this;
|
|
}
|
|
|
|
// ... weitere Helper-Methoden
|
|
}
|
|
```
|
|
|
|
### 1.2 Snapshot Testing
|
|
|
|
**Ziel**: Render-Ausgabe als Snapshots speichern und vergleichen
|
|
|
|
**Datei**: `tests/Feature/Framework/LiveComponents/TestHarness/ComponentSnapshotTest.php`
|
|
|
|
**Features**:
|
|
- Whitespace-normalisierte Snapshots
|
|
- Automatische Snapshot-Generierung
|
|
- Snapshot-Vergleich mit Diff-Output
|
|
- Snapshot-Update-Modus für Refactoring
|
|
|
|
**Usage**:
|
|
```php
|
|
it('renders counter component correctly', function () {
|
|
$component = mountComponent('counter:test', ['count' => 5]);
|
|
|
|
expect($component['html'])->toMatchSnapshot('counter-initial-state');
|
|
});
|
|
```
|
|
|
|
### 1.3 Contract Compliance Tests
|
|
|
|
**Ziel**: Automatische Tests für Interface-Compliance
|
|
|
|
**Datei**: `tests/Feature/Framework/LiveComponents/ContractComplianceTest.php`
|
|
|
|
**Tests**:
|
|
- `Pollable` Interface Compliance
|
|
- `Cacheable` Interface Compliance
|
|
- `Uploadable` Interface Compliance
|
|
- `LifecycleAware` Interface Compliance
|
|
- `SupportsSlots` Interface Compliance
|
|
|
|
**Features**:
|
|
- Reflection-basierte Interface-Checks
|
|
- Method-Signature-Validierung
|
|
- Return-Type-Validierung
|
|
- Required-Method-Checks
|
|
|
|
### 1.4 Security Tests
|
|
|
|
**Ziel**: Umfassende Security-Tests für alle Security-Features
|
|
|
|
**Datei**: `tests/Feature/Framework/LiveComponents/SecurityTest.php`
|
|
|
|
**Tests**:
|
|
- CSRF Protection Tests
|
|
- Rate Limiting Tests
|
|
- Idempotency Tests
|
|
- Action Allow-List Tests
|
|
- Authorization Tests (`#[RequiresPermission]`)
|
|
|
|
**Features**:
|
|
- Test für alle Security-Patterns
|
|
- Edge-Case-Tests (Token-Manipulation, etc.)
|
|
- Integration-Tests mit echten Requests
|
|
|
|
### 1.5 E2E Tests
|
|
|
|
**Ziel**: End-to-End Tests für komplexe Szenarien
|
|
|
|
**Datei**: `tests/e2e/livecomponents/`
|
|
|
|
**Tests**:
|
|
- Partial Rendering E2E
|
|
- Batch Operations E2E
|
|
- SSE Reconnect E2E
|
|
- Upload Chunking E2E
|
|
- Island Loading E2E
|
|
- Lazy Loading E2E
|
|
|
|
**Tools**:
|
|
- Playwright für Browser-Tests
|
|
- Real HTTP Requests
|
|
- Component-Interaction-Tests
|
|
|
|
---
|
|
|
|
## Phase 2: Documentation Vervollständigung
|
|
|
|
### 2.1 End-to-End Guide
|
|
|
|
**Datei**: `docs/livecomponents/end-to-end-guide.md`
|
|
|
|
**Inhalte**:
|
|
- Component erstellen (von Grund auf)
|
|
- RenderData definieren
|
|
- Actions implementieren
|
|
- Events dispatchen
|
|
- State Management
|
|
- Caching konfigurieren
|
|
- Fragments verwenden
|
|
- Slots nutzen
|
|
- Lifecycle Hooks
|
|
- Best Practices
|
|
|
|
**Struktur**:
|
|
1. Quick Start (5 Minuten)
|
|
2. Component Basics
|
|
3. State Management
|
|
4. Actions & Events
|
|
5. Advanced Features
|
|
6. Performance Optimization
|
|
7. Real-World Examples
|
|
|
|
### 2.2 Security Guide
|
|
|
|
**Datei**: `docs/livecomponents/security-guide-complete.md`
|
|
|
|
**Inhalte**:
|
|
- CSRF Protection (wie es funktioniert, Best Practices)
|
|
- Rate Limiting (Konfiguration, Custom Limits)
|
|
- Idempotency (Use Cases, Implementation)
|
|
- Action Allow-List (Security-Pattern)
|
|
- Authorization (`#[RequiresPermission]`)
|
|
- Input Validation
|
|
- XSS Prevention
|
|
- Secure State Management
|
|
|
|
**Beispiele**:
|
|
- Secure Component Patterns
|
|
- Common Security Pitfalls
|
|
- Security Checklist
|
|
|
|
### 2.3 Performance Guide
|
|
|
|
**Datei**: `docs/livecomponents/performance-guide-complete.md`
|
|
|
|
**Inhalte**:
|
|
- Caching Strategies (varyBy, SWR)
|
|
- Request Batching
|
|
- Debounce/Throttle Patterns
|
|
- Lazy Loading Best Practices
|
|
- Island Components für Performance
|
|
- Fragment Updates
|
|
- SSE Optimization
|
|
- Memory Management
|
|
|
|
**Beispiele**:
|
|
- Performance-Optimierte Components
|
|
- Benchmarking-Strategien
|
|
- Performance Checklist
|
|
|
|
### 2.4 Upload Guide
|
|
|
|
**Datei**: `docs/livecomponents/upload-guide-complete.md`
|
|
|
|
**Inhalte**:
|
|
- File Upload Basics
|
|
- Validation Patterns
|
|
- Chunked Uploads
|
|
- Progress Tracking
|
|
- Quarantine System
|
|
- Virus Scanning Integration
|
|
- Error Handling
|
|
- Security Considerations
|
|
|
|
**Beispiele**:
|
|
- Image Upload Component
|
|
- Large File Upload
|
|
- Multi-File Upload
|
|
|
|
### 2.5 DevTools/Debugging Guide
|
|
|
|
**Datei**: `docs/livecomponents/devtools-debugging-guide.md`
|
|
|
|
**Inhalte**:
|
|
- DevTools Overlay verwenden
|
|
- Component Inspector
|
|
- Action Logging
|
|
- Event Monitoring
|
|
- Network Timeline
|
|
- Performance Profiling
|
|
- Debugging-Tipps
|
|
- Common Issues & Solutions
|
|
|
|
### 2.6 API Reference
|
|
|
|
**Datei**: `docs/livecomponents/api-reference-complete.md`
|
|
|
|
**Inhalte**:
|
|
- Alle Contracts (LiveComponentContract, Pollable, Cacheable, etc.)
|
|
- Alle Attributes (`#[LiveComponent]`, `#[Action]`, `#[Island]`, etc.)
|
|
- Alle Controller-Endpoints
|
|
- Alle Value Objects
|
|
- JavaScript API
|
|
- Events API
|
|
|
|
**Format**:
|
|
- Vollständige Method-Signatures
|
|
- Parameter-Beschreibungen
|
|
- Return-Types
|
|
- Examples für jede Methode
|
|
|
|
---
|
|
|
|
## Phase 3: Middleware Support
|
|
|
|
### 3.1 Component Middleware Interface
|
|
|
|
**Ziel**: Interface für Component-Level Middleware
|
|
|
|
**Datei**: `src/Framework/LiveComponents/Middleware/ComponentMiddlewareInterface.php`
|
|
|
|
**Interface**:
|
|
```php
|
|
interface ComponentMiddlewareInterface
|
|
{
|
|
public function handle(
|
|
LiveComponentContract $component,
|
|
string $action,
|
|
ActionParameters $params,
|
|
callable $next
|
|
): ComponentUpdate;
|
|
}
|
|
```
|
|
|
|
### 3.2 Middleware Attribute
|
|
|
|
**Ziel**: Attribute zum Registrieren von Middleware auf Component-Level
|
|
|
|
**Datei**: `src/Framework/LiveComponents/Attributes/Middleware.php`
|
|
|
|
**Usage**:
|
|
```php
|
|
#[LiveComponent('user-profile')]
|
|
#[Middleware(LoggingMiddleware::class)]
|
|
#[Middleware(CachingMiddleware::class, priority: 10)]
|
|
final readonly class UserProfileComponent implements LiveComponentContract
|
|
{
|
|
}
|
|
```
|
|
|
|
### 3.3 Built-in Middleware
|
|
|
|
**Ziel**: Standard-Middleware für häufige Use Cases
|
|
|
|
**Middleware**:
|
|
1. **LoggingMiddleware** - Action-Logging
|
|
2. **CachingMiddleware** - Response-Caching
|
|
3. **RateLimitMiddleware** - Component-Level Rate Limiting
|
|
4. **ValidationMiddleware** - Input-Validation
|
|
5. **TransformMiddleware** - Request/Response Transformation
|
|
|
|
**Dateien**:
|
|
- `src/Framework/LiveComponents/Middleware/LoggingMiddleware.php`
|
|
- `src/Framework/LiveComponents/Middleware/CachingMiddleware.php`
|
|
- `src/Framework/LiveComponents/Middleware/RateLimitMiddleware.php`
|
|
- `src/Framework/LiveComponents/Middleware/ValidationMiddleware.php`
|
|
- `src/Framework/LiveComponents/Middleware/TransformMiddleware.php`
|
|
|
|
### 3.4 Middleware Pipeline
|
|
|
|
**Ziel**: Middleware-Pipeline für Component Actions
|
|
|
|
**Datei**: `src/Framework/LiveComponents/Middleware/ComponentMiddlewarePipeline.php`
|
|
|
|
**Features**:
|
|
- Middleware-Stack-Verwaltung
|
|
- Priority-basierte Ausführung
|
|
- Request/Response Transformation
|
|
- Error Handling in Middleware
|
|
|
|
**Architektur**:
|
|
```php
|
|
final readonly class ComponentMiddlewarePipeline
|
|
{
|
|
public function __construct(
|
|
private array $middlewares
|
|
) {}
|
|
|
|
public function process(
|
|
LiveComponentContract $component,
|
|
string $action,
|
|
ActionParameters $params
|
|
): ComponentUpdate {
|
|
// Execute middleware stack
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3.5 Middleware Integration
|
|
|
|
**Ziel**: Integration in LiveComponentHandler
|
|
|
|
**Datei**: `src/Framework/LiveComponents/LiveComponentHandler.php`
|
|
|
|
**Änderungen**:
|
|
- Middleware-Discovery aus Component-Attributes
|
|
- Middleware-Pipeline vor Action-Execution
|
|
- Middleware-Configuration aus Metadata
|
|
|
|
### 3.6 Middleware Tests
|
|
|
|
**Ziel**: Umfassende Tests für Middleware-System
|
|
|
|
**Dateien**:
|
|
- `tests/Unit/Framework/LiveComponents/Middleware/ComponentMiddlewarePipelineTest.php`
|
|
- `tests/Unit/Framework/LiveComponents/Middleware/LoggingMiddlewareTest.php`
|
|
- `tests/Unit/Framework/LiveComponents/Middleware/CachingMiddlewareTest.php`
|
|
- `tests/Feature/Framework/LiveComponents/MiddlewareIntegrationTest.php`
|
|
|
|
---
|
|
|
|
## Implementierungsreihenfolge
|
|
|
|
### Sprint 1: Test Infrastructure (Woche 1-2)
|
|
1. LiveComponentTestCase Base Class
|
|
2. Snapshot Testing
|
|
3. Contract Compliance Tests
|
|
4. Security Tests (Basis)
|
|
|
|
### Sprint 2: Documentation Phase 1 (Woche 3)
|
|
1. End-to-End Guide
|
|
2. Security Guide
|
|
3. Performance Guide
|
|
|
|
### Sprint 3: Middleware Support (Woche 4-5)
|
|
1. ComponentMiddlewareInterface
|
|
2. Middleware Attribute
|
|
3. Middleware Pipeline
|
|
4. Built-in Middleware (Logging, Caching)
|
|
|
|
### Sprint 4: Documentation Phase 2 & Testing Completion (Woche 6)
|
|
1. Upload Guide
|
|
2. DevTools Guide
|
|
3. API Reference
|
|
4. E2E Tests
|
|
5. Security Tests (Vollständig)
|
|
|
|
---
|
|
|
|
## Akzeptanzkriterien
|
|
|
|
### Test Infrastructure
|
|
- [ ] LiveComponentTestCase mit allen Helpers implementiert
|
|
- [ ] Snapshot Testing funktional
|
|
- [ ] Contract Compliance Tests für alle Interfaces
|
|
- [ ] Security Tests für alle Security-Features
|
|
- [ ] E2E Tests für komplexe Szenarien
|
|
- [ ] Alle Tests dokumentiert mit Examples
|
|
|
|
### Documentation
|
|
- [ ] End-to-End Guide vollständig
|
|
- [ ] Security Guide vollständig
|
|
- [ ] Performance Guide vollständig
|
|
- [ ] Upload Guide vollständig
|
|
- [ ] DevTools Guide vollständig
|
|
- [ ] API Reference vollständig
|
|
- [ ] Alle Guides mit praktischen Examples
|
|
|
|
### Middleware Support
|
|
- [ ] ComponentMiddlewareInterface definiert
|
|
- [ ] Middleware Attribute implementiert
|
|
- [ ] Middleware Pipeline funktional
|
|
- [ ] Built-in Middleware implementiert (Logging, Caching, RateLimit)
|
|
- [ ] Integration in LiveComponentHandler
|
|
- [ ] Umfassende Tests
|
|
- [ ] Dokumentation mit Examples
|
|
|
|
---
|
|
|
|
## Technische Details
|
|
|
|
### Test Infrastructure
|
|
|
|
**Pest Integration**:
|
|
- Custom Expectations erweitern
|
|
- Helper-Functions in `tests/Pest.php`
|
|
- Test-Harness als Trait für Wiederverwendung
|
|
|
|
**Snapshot Format**:
|
|
- JSON-basiert für strukturierte Daten
|
|
- HTML-Snapshots mit Whitespace-Normalisierung
|
|
- Versionierte Snapshots für Breaking Changes
|
|
|
|
### Middleware Architecture
|
|
|
|
**Execution Order**:
|
|
1. Request Transformation (TransformMiddleware)
|
|
2. Validation (ValidationMiddleware)
|
|
3. Rate Limiting (RateLimitMiddleware)
|
|
4. Caching (CachingMiddleware)
|
|
5. Logging (LoggingMiddleware)
|
|
6. Action Execution
|
|
7. Response Transformation
|
|
|
|
**Priority System**:
|
|
- Higher priority = earlier execution
|
|
- Default priority: 100
|
|
- Built-in middleware: 50-150 range
|
|
|
|
### Documentation Structure
|
|
|
|
**Markdown Format**:
|
|
- Code-Beispiele mit Syntax-Highlighting
|
|
- TOC für Navigation
|
|
- Cross-References zwischen Guides
|
|
- Version-Info für Breaking Changes
|
|
|
|
---
|
|
|
|
## Erfolgsmetriken
|
|
|
|
### Test Infrastructure
|
|
- 90%+ Test Coverage für alle Core-Features
|
|
- Alle Security-Features getestet
|
|
- E2E Tests für kritische Flows
|
|
|
|
### Documentation
|
|
- Alle Guides vollständig
|
|
- Praktische Examples für alle Features
|
|
- Positive Developer Feedback
|
|
|
|
### Middleware Support
|
|
- Middleware-System funktional
|
|
- Built-in Middleware getestet
|
|
- Developer können Custom Middleware erstellen
|
|
|
|
---
|
|
|
|
## Risiken & Mitigation
|
|
|
|
### Test Infrastructure
|
|
- **Risiko**: Snapshot-Tests können bei Refactoring störend sein
|
|
- **Mitigation**: Update-Modus für einfaches Refactoring
|
|
|
|
### Documentation
|
|
- **Risiko**: Dokumentation kann schnell veralten
|
|
- **Mitigation**: Automatische Tests für Code-Examples, regelmäßige Reviews
|
|
|
|
### Middleware Support
|
|
- **Risiko**: Performance-Impact durch Middleware-Stack
|
|
- **Mitigation**: Caching, Lazy Loading, Performance-Tests
|
|
|
|
---
|
|
|
|
## Nächste Schritte
|
|
|
|
1. **Sprint Planning**: Detaillierte Task-Aufteilung
|
|
2. **Implementation Start**: Mit Test Infrastructure beginnen
|
|
3. **Documentation**: Parallel zur Implementation
|
|
4. **Middleware**: Nach Test Infrastructure
|
|
|
|
|
|
|
|
|
|
|