michaelschiemer/docs/livecomponents/implementation-plan-testing-docs-middleware.md

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:

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:

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:

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:

#[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:

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