# 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