From 8b44279baa55ab7159fc25eecd06dd146c0a9831 Mon Sep 17 00:00:00 2001 From: dschlueter Date: Mon, 22 Jun 2026 12:11:57 +0200 Subject: [PATCH] =?UTF-8?q?Docs:=20Verweise=20auf=20gel=C3=B6schte=20Test-?= =?UTF-8?q?Dateien=20bereinigt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Die in 6268ea6 entfernten test_app.py / test_metronome_velocity.py sowie SCROLL_IMPROVEMENTS.md waren noch in mehreren Dokumenten referenziert. Aktualisiert auf den realen Stand: - README.md, PROJECT_STRUCTURE.md: Dateibäume und Test-Tabellen/ -Abschnitte bereinigt; Testbefehle auf 'unittest discover -s tests -p "test_*.py"' vereinheitlicht - tests/README.md, JAVASCRIPT_MODULES.md, setup.sh: Testbefehle und Beispiel-Verweise auf das tests/-Verzeichnis umgestellt - README_METRONOME_TESTS.md gelöscht (dokumentierte ausschließlich die entfernte test_metronome_velocity.py); Metronom-Verweis zeigt nun auf static/js/metronome.js - CLAUDE.md in Doku als 'nur lokal, nicht versioniert' gekennzeichnet Co-Authored-By: Claude Sonnet 4.6 --- JAVASCRIPT_MODULES.md | 6 +- PROJECT_STRUCTURE.md | 16 ++- README.md | 24 +---- README_METRONOME_TESTS.md | 211 -------------------------------------- setup.sh | 2 +- tests/README.md | 6 +- 6 files changed, 14 insertions(+), 251 deletions(-) delete mode 100644 README_METRONOME_TESTS.md diff --git a/JAVASCRIPT_MODULES.md b/JAVASCRIPT_MODULES.md index 0def2b3..78ed5c5 100644 --- a/JAVASCRIPT_MODULES.md +++ b/JAVASCRIPT_MODULES.md @@ -316,11 +316,7 @@ KeyboardHandler → TypewriterApp ## Testing -Jedes Modul kann isoliert getestet werden: - -**Backend-Tests**: `python -m unittest test_app -v` - -**Metronom-Tests**: `python -m unittest test_metronome_velocity -v` +**Backend-Tests** (Service-Layer): `python -m unittest discover -s tests -p "test_*.py" -v` Die JavaScript-Module sind so strukturiert, dass sie leicht mit Jest oder ähnlichen Frameworks getestet werden können. diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md index d28b840..eb23a18 100644 --- a/PROJECT_STRUCTURE.md +++ b/PROJECT_STRUCTURE.md @@ -42,15 +42,12 @@ typewriter/ ├── 📄 requirements.txt # Python-Dependencies ├── 📄 alembic.ini # Alembic-Konfiguration │ -├── 🧪 test_app.py # Backend-Tests (236 Zeilen, 18 Tests) -├── 🧪 test_metronome_velocity.py # Metronom-Tests (537 Zeilen) +├── 🧪 tests/ # Service-Layer Unit- & Integration-Tests │ -├── 📚 CLAUDE.md # Projekt-Dokumentation für Claude Code +├── 📚 CLAUDE.md # Projekt-Dokumentation für Claude Code (nur lokal) ├── 📚 JAVASCRIPT_MODULES.md # JavaScript-Modul-Dokumentation ├── 📚 MIGRATIONS.md # Alembic-Migrations-Guide ├── 📚 README.md # Haupt-README -├── 📚 README_METRONOME_TESTS.md # Metronom-Test-Dokumentation -├── 📚 SCROLL_IMPROVEMENTS.md # Scroll-Verbesserungen ├── 📚 PROJECT_STRUCTURE.md # Diese Datei │ ├── 🔧 setup.sh # Komplettes Setup-Script @@ -86,12 +83,12 @@ typewriter/ - `.gitignore` - Git-Ignore-Regeln ### 🟡 Dokumentation (versioniert) -- `CLAUDE.md` - Projekt-Guide - `README.md` - Haupt-Dokumentation +- `HILFE.md` - Benutzer-Hilfe - `JAVASCRIPT_MODULES.md` - JS-Architektur - `MIGRATIONS.md` - Datenbank-Migrations-Guide -- `SCROLL_IMPROVEMENTS.md` - Changelog - `PROJECT_STRUCTURE.md` - Struktur-Übersicht +- `CLAUDE.md` - Projekt-Guide für Claude Code (nur lokal, nicht versioniert) ### 🟠 Scripts (versioniert) - `setup.sh` - Komplettes Setup @@ -100,8 +97,7 @@ typewriter/ - `setup_database.py` - Datenbank-Setup ### 🔴 Tests (versioniert) -- `test_app.py` - Backend-Tests -- `test_metronome_velocity.py` - Metronom-Tests +- `tests/` - Service-Layer Unit- & Integration-Tests (80 Tests) ### ⚫ Temporär/Generiert (NICHT versioniert) - `venv/` - Virtual Environment @@ -126,7 +122,7 @@ typewriter/ ```bash source venv/bin/activate # Environment aktivieren python app.py # Server starten -python -m unittest test_app # Tests ausführen +python -m unittest discover -s tests -p "test_*.py" # Tests ausführen ``` ### Datenbank diff --git a/README.md b/README.md index a9a5417..f1c521b 100644 --- a/README.md +++ b/README.md @@ -98,8 +98,6 @@ typewriter/ ├── app.py # Flask-Hauptanwendung ├── models.py # SQLAlchemy Datenbankmodelle ├── convert_txt_files_to_lessons_json.py # Tool: TXT → lessons.json -├── test_app.py # Unit-Tests (18 Tests) -├── test_metronome_velocity.py # Metronom-Tests (22 Tests) ├── requirements.txt # Python-Dependencies ├── .env # Secret Key (automatisch generiert) ├── .gitignore # Git-Ignore-Konfiguration @@ -137,8 +135,7 @@ typewriter/ │ ├── README.md # Diese Datei ├── CLAUDE.md # Projektdokumentation für KI -├── MIGRATIONS.md # Alembic-Anleitung -└── README_METRONOME_TESTS.md # Metronom-Test-Dokumentation +└── MIGRATIONS.md # Alembic-Anleitung ``` ## 🎮 Verwendung @@ -216,7 +213,6 @@ Das Projekt enthält eine umfassende Test-Suite mit **80 Tests** (100% Erfolgsra | **Gesamt** | 80 Tests | ~2.9s | ✅ 100% | | **Unit Tests** | 54 Tests | 0.002s ⚡ | ✅ Bestanden | | **Integration Tests** | 26 Tests | 2.856s | ✅ Bestanden | -| **Legacy Tests** | 40 Tests | ~1s | ✅ Bestanden | ### Test-Ausführung @@ -235,15 +231,6 @@ python -m unittest tests.test_integration_progress tests.test_integration_statis ./run_coverage.sh ``` -**Legacy Tests (40 Tests):** -```bash -# App-Tests (18 Tests) -python -m unittest test_app -v - -# Metronom-Tests (22 Tests) -python test_metronome_velocity.py -``` - ### Was wird getestet? **Service Layer Tests (`tests/`):** @@ -252,10 +239,6 @@ python test_metronome_velocity.py - ✅ **SettingsService** (22): Validierungen, Boundary Values - ✅ **ProgressService** (12): CRUD, State Management, Multi-Lesson Independence -**Legacy Tests:** -- ✅ **App-Tests**: Statistik-Berechnungen, API-Endpoints, Input-Validierung, CSV/JSON-Export -- ✅ **Metronom-Tests**: 5 Anpassungsregeln, Realistische Szenarien, Edge Cases - ### Lokale Validierung Die Validierung läuft lokal über einen Git-Pre-commit-Hook (aktuell ist keine serverseitige CI eingerichtet). @@ -272,7 +255,6 @@ chmod +x .git/hooks/pre-commit **Weitere Informationen:** - 📖 Service Tests: [`tests/README.md`](tests/README.md) -- 📖 Metronom Tests: [`README_METRONOME_TESTS.md`](README_METRONOME_TESTS.md) ## 🔧 Entwicklung @@ -389,7 +371,7 @@ Das adaptive Metronom ist das Herzstück des Trainers: - Nach 100 Eingaben: ~200 BPM (Maximum erreicht) - Plus Streak-Boni bei 15+ korrekten Zeichen -Siehe [`README_METRONOME_TESTS.md`](README_METRONOME_TESTS.md) für detaillierte Erklärung und Tests. +Die Implementierung findet sich in [`static/js/metronome.js`](static/js/metronome.js). ## 📊 Datenbank-Schema @@ -432,7 +414,7 @@ Contributions sind willkommen! Bitte: 1. Fork das Repository 2. Erstelle einen Feature-Branch (`git checkout -b feature/AmazingFeature`) -3. Führe Tests aus (`python -m unittest test_app -v`) +3. Führe Tests aus (`python -m unittest discover -s tests -p "test_*.py" -v`) 4. Commit deine Änderungen (`git commit -m 'Add AmazingFeature'`) 5. Push zum Branch (`git push origin feature/AmazingFeature`) 6. Öffne einen Pull Request diff --git a/README_METRONOME_TESTS.md b/README_METRONOME_TESTS.md deleted file mode 100644 index f29f6bb..0000000 --- a/README_METRONOME_TESTS.md +++ /dev/null @@ -1,211 +0,0 @@ -# Metronom-Geschwindigkeitsanpassung - Test-Dokumentation - -## Übersicht - -`test_metronome_velocity.py` ist eine umfassende Test-Suite für die adaptive Metronom-Geschwindigkeitsanpassung des Typewriter Trainers. Das Programm implementiert die JavaScript-Logik in Python nach und testet alle Aspekte der Geschwindigkeitsanpassung. - -## Installation und Ausführung - -```bash -# Keine zusätzlichen Dependencies nötig (nur Python Standard Library) -python test_metronome_velocity.py -``` - -**Ausgabe:** -1. Detaillierte Simulation mit visueller Ausgabe -2. 22 Unit-Tests mit detaillierten Ergebnissen - -## Test-Struktur - -### 📊 **Test-Kategorien** - -#### 1. **TestAdaptiveMetronomeBasics** (5 Tests) -Grundlegende Funktionalität: -- ✅ Initialwerte korrekt gesetzt -- ✅ Einzelner korrekter Tastendruck -- ✅ Einzelner falscher Tastendruck -- ✅ History-Limit auf 50 Einträge -- ✅ Consecutive-Counter Reset bei Fehler - -#### 2. **TestAdaptiveMetronomeSpeedAdjustment** (7 Tests) -Alle 5 Anpassungsregeln: -- ✅ **Regel #1**: Streak-Bonus bei 15+ korrekten Zeichen (+3%) -- ✅ **Regel #2**: Zu einfach bei >95% Genauigkeit (+2%) -- ✅ **Regel #3**: Zu schwer bei <85% Genauigkeit (-8%) -- ✅ **Regel #4**: Leicht unter Ziel bei 85-91% (-3%) -- ✅ **Regel #5**: Im Zielbereich bei 91-95% (+1%) -- ✅ Minimum-Grenze (40 BPM) -- ✅ Maximum-Grenze (200 BPM) - -#### 3. **TestAdaptiveMetronomeScenarios** (6 Tests) -Realistische Szenarien: -- ✅ **Anfänger**: 70% Genauigkeit → Speed sinkt -- ✅ **Fortgeschrittener**: 92% Genauigkeit → Speed steigt leicht -- ✅ **Experte**: 98% Genauigkeit → Speed steigt stark -- ✅ **Erholung**: Nach Fehlerphase wieder schneller werden -- ✅ **Wechselnde Performance**: Auf/Ab-Zyklen -- ✅ **Difficulty-Parameter**: Höhere Schwierigkeit = niedrigeres Ziel - -#### 4. **TestAdaptiveMetronomeEdgeCases** (4 Tests) -Grenzfälle und Edge Cases: -- ✅ Leere History -- ✅ Exakt an Regelgrenzen -- ✅ Streak exakt bei 15 -- ✅ Schnelle Wechsel (alternierend korrekt/falsch) - -## 📈 **Detaillierte Simulation** - -Die Simulation zeigt 6 typische Phasen: - -``` -Phase | Genauigkeit | Speed-Änderung -------------------------------|-------------|---------------- -Anfangsphase (70% korrekt) | 70% | 60 → 40 BPM -Verbesserung (85% korrekt) | 85% | 40 → 40 BPM -Zielbereich (93% korrekt) | 93% | 40 → 200 BPM -Exzellent (98% korrekt) | 98% | 200 → 200 BPM -Fehlerphase (50% korrekt) | 50% | 200 → 92 BPM -Erholung (95% korrekt) | 95% | 92 → 107 BPM -``` - -## 🎯 **Wichtige Erkenntnisse aus den Tests** - -### 1. **Schnelle Anpassung bei schlechter Performance** -- Bei 70% Genauigkeit: 60 → 40 BPM in 50 Eingaben -- System bremst aggressiv ab um Fehlerrate zu reduzieren - -### 2. **Langsame Beschleunigung bei guter Performance** -- Bei 92% Genauigkeit: Langsame Steigerung (+1% pro Schritt) -- Verhindert Überforderung - -### 3. **Streak-Bonus ist effektiv** -- 15+ fehlerfreie Zeichen: +3% Boost -- Motiviert zu fehlerfreiem Tippen - -### 4. **Grenzen werden respektiert** -- Minimum 40 BPM: Auch bei 0% Genauigkeit -- Maximum 200 BPM: Auch bei perfekter Performance - -### 5. **Sliding Window funktioniert** -- Letzte 50 Eingaben werden berücksichtigt -- Alte Fehler werden vergessen -- Erlaubt Erholung nach Fehlerphasen - -## 🔍 **Test-Beispiele** - -### Beispiel 1: Streak-Bonus - -```python -metronome = AdaptiveMetronome() -# 15 korrekte Zeichen -for _ in range(15): - metronome.process_keystroke(True) - -initial_speed = metronome.speed -# 16. korrektes Zeichen löst Bonus aus -speed = metronome.process_keystroke(True) - -# Speed erhöht sich um 3% -assert speed == initial_speed * 1.03 -``` - -### Beispiel 2: Zu schwierig → Bremsen - -```python -metronome = AdaptiveMetronome() -metronome.speed = 100.0 - -# 20% Genauigkeit (2 korrekt, 8 falsch) -for _ in range(2): - metronome.process_keystroke(True) -for _ in range(8): - metronome.process_keystroke(False) - -initial_speed = metronome.speed -metronome.process_keystroke(False) - -# Speed reduziert sich um 8% -assert metronome.speed == initial_speed * 0.92 -``` - -## 🐛 **Bekannte Einschränkungen** - -1. **Difficulty-Parameter wird nicht genutzt** - - Aktuell immer `1.0` in der JavaScript-Implementation - - Könnte für schwierige Zeichenkombinationen verwendet werden - -2. **Consecutive-Counter wird bei JEDEM Fehler resettet** - - Verhindert Streak-Bonus bei vereinzelten Fehlern - - Könnte toleranter sein (z.B. 1 Fehler pro 20 Zeichen erlauben) - -3. **Speed kann bei Maximum "stecken bleiben"** - - Bei 200 BPM und perfekter Performance keine weitere Steigerung - - Tests müssen dies berücksichtigen - -## 📊 **Test-Ergebnisse interpretieren** - -### ✅ **Alle Tests bestanden (22/22)** -Das adaptive Metronom funktioniert wie designed: -- Alle 5 Anpassungsregeln arbeiten korrekt -- Grenzen werden eingehalten -- Realistische Szenarien werden korrekt verarbeitet - -### ⚠️ **Mögliche Verbesserungen** -Basierend auf den Tests könnten folgende Anpassungen sinnvoll sein: - -1. **Sanfteres Bremsen bei Anfängern** - - Aktuell: 70% Genauigkeit → Speed auf Minimum - - Besser: Graduelleres Abbremsen - -2. **Toleranterer Streak-Counter** - - Aktuell: 1 Fehler → Streak auf 0 - - Besser: Streak nur bei 2+ aufeinanderfolgenden Fehlern resetten - -3. **Dynamische Ziel-Genauigkeit** - - Aktuell: Fest auf 96% - - Besser: Anpassbar in Settings (aus `target_error_rate` berechnen) - -## 🚀 **Verwendung der Test-Suite** - -### Regression Testing -```bash -# Nach Änderungen an der Metronom-Logik -python test_metronome_velocity.py -``` - -### Einzelne Tests ausführen -```bash -# Nur Regel #1 testen -python -m unittest test_metronome_velocity.TestAdaptiveMetronomeSpeedAdjustment.test_rule_1_streak_bonus -v - -# Alle Scenario-Tests -python -m unittest test_metronome_velocity.TestAdaptiveMetronomeScenarios -v -``` - -### Neue Tests hinzufügen -```python -class TestAdaptiveMetronomeSpeedAdjustment(unittest.TestCase): - def test_my_new_scenario(self): - """Test: Beschreibung""" - metronome = AdaptiveMetronome() - - # Setup - # ... - - # Execute - result = metronome.process_keystroke(True) - - # Assert - self.assertEqual(result, expected_value) -``` - -## 📝 **Zusammenfassung** - -Die Test-Suite bestätigt, dass die adaptive Metronom-Geschwindigkeit: -- ✅ Korrekt auf User-Performance reagiert -- ✅ Alle 5 Anpassungsregeln korrekt implementiert -- ✅ Grenzen (40-200 BPM) respektiert -- ✅ In realistischen Szenarien funktioniert -- ✅ Edge Cases korrekt behandelt - -**Empfehlung:** Bei Änderungen an `static/js/script.js` (Zeilen 80-137) immer diese Tests ausführen, um Regressionen zu vermeiden. diff --git a/setup.sh b/setup.sh index ec09faf..5d1dc81 100755 --- a/setup.sh +++ b/setup.sh @@ -98,5 +98,5 @@ echo "" echo "Weitere Befehle:" echo " • ./cleanup.sh - Projekt aufräumen" echo " • ./start.sh - Anwendung starten" -echo " • python test_app.py - Tests ausführen" +echo " • python -m unittest discover -s tests -p 'test_*.py' - Tests ausführen" echo "" diff --git a/tests/README.md b/tests/README.md index b172870..db6f97c 100644 --- a/tests/README.md +++ b/tests/README.md @@ -94,7 +94,7 @@ Dieses Verzeichnis enthält Unit Tests für die Service-Layer der Typewriter Tra ### Warum unittest statt pytest? -- Bereits im Projekt verwendet (siehe `test_app.py`) +- Bereits im Projekt verwendet (siehe `tests/`) - Keine zusätzlichen Dependencies - Standard Python-Tool - Ausreichend für Service-Layer Unit Tests @@ -220,7 +220,7 @@ if __name__ == '__main__': ## Integration Tests -Für vollständige Integration Tests (mit Datenbank, Flask-Context, etc.) siehe `test_app.py` im Hauptverzeichnis. +Für vollständige Integration Tests (mit Datenbank, Flask-Context, etc.) siehe `tests/test_integration_progress.py` und `tests/test_integration_statistics.py`. ## Continuous Integration @@ -245,7 +245,7 @@ python -m unittest discover tests -v ### Problem: SQLAlchemy-Fehler -**Lösung:** Services mit Datenbankzugriff erfordern Flask-App-Context. Siehe `test_app.py` für Beispiele mit `app.app_context()`. +**Lösung:** Services mit Datenbankzugriff erfordern Flask-App-Context. Siehe `tests/test_integration_progress.py` für Beispiele mit `app.app_context()`. ### Problem: Tests schlagen intermittierend fehl