.. _arch-tests-quality: ======================================================= Assurance Qualité, Tests et Analyse Statique (Linter) ======================================================= Ce document décrit l'infrastructure de validation, la couverture de code, la suite de tests automatisée et la politique d'analyse statique (linting) mise en place sur Mirza. .. contents:: Sommaire :local: :depth: 2 ---- Vue d'Ensemble de la Qualité Logicielle ======================================================= L'architecture de Mirza reposant sur un couplage étroit entre traitement audio temps réel, moteurs d'inférence MLX/ONNX et protocoles réseau asynchrones (WebSocket, HTTP/2, TLS), la fiabilité du système repose sur une chaîne d'assurance qualité à trois niveaux : 1. **Suite de tests automatisée (Pytest)** : Couverture unitaire et d'intégration garantissant la conformité fonctionnelle et l'absence de régression. 2. **Métrologie de la couverture (Coverage.py)** : Contrôle continu de l'exhaustivité des branches logiques couvertes avec rapport structuré. 3. **Analyse statique et Linting (Ruff)** : Application stricte des standards de qualité, de typage, de gestion des imports et de détection préventive des bugs. ---- Indicateurs Clés de Performance (KPIs) ======================================================= Les indicateurs actuels issus de la dernière exécution sur le banc de validation sont les suivants : .. list-table:: Indicateurs d'Assurance Qualité Mirza :widths: 40 30 30 :header-rows: 1 * - Indicateur - Valeur - Statut * - **Taux de réussite des tests** - **100.00%** (467 / 467 tests) - Validé * - **Nombre de suites de test** - 35+ fichiers de test - Validé * - **Durée totale d'exécution** - **< 16 secondes** - Temps réel local * - **Taux de couverture globale** - **> 82%** - Conforme à l'objectif (>80%) * - **Violations linter (Ruff)** - **0 violation** - 100% Conforme ---- Suite de Tests Automatisée ========================== Organisation des Tests ---------------------- Les tests sont situés dans le répertoire ``tests/`` et couvrent l'intégralité des sous-systèmes de Mirza : * **Couche Audio & Périphériques** (``test_audio_processor.py``, ``test_device_manager.py``, ``test_vad_detector.py``) : Validation de l'atténuation d'énergie, de la détection de voix active (VAD neural) et de la gestion dynamique des cartes son. * **Moteurs d'Inférence & Interfaces** (``test_llm_engines.py``, ``test_mtplx_llm.py``, ``test_stt_engines.py``, ``test_tts_engines.py``) : Vérification de la conformité des contrats d'interface, du streaming de tokens, du warm-up et des mécanismes de fallback. * **Orchestration & Flux Conversationnel** (``test_conversation_orchestrator.py``, ``test_context_manager.py``, ``test_audio_stream_pipeline.py``) : Validation du half-duplex, de l'anti-larsen, des transitions d'état de l'orchestrateur et de la purge de contexte. * **Mémoire Épisodique & Vectorielle** (``test_episodic_memory.py``, ``test_memory_manager.py``, ``test_memory_backend.py``, ``test_embedding_engine.py``) : Stockage SQLite, recherche sémantique avec vectorisation locale / sqlite-vec, seuil de pertinence et ré-ordonnancement. * **Moteur Agentique ReAct** (``test_agent_manager.py``, ``test_agent_tools.py``, ``test_react_parser.py``, ``test_mirza_model_adapter.py``) : Protocole bi-canal, exécution sécurisée des outils locaux/web et extraction des balises ````. * **Serveur & Transports Réseau** (``test_server_websocket.py``, ``test_server_routes.py``, ``test_widget_server.py``, ``test_ssl_manager.py``) : Handshake binaire PCM16, diffusion d'événements multiplexés, certificats TLS auto-signés avec SAN et routes REST FastAPI. Mesure du Taux de Réussite -------------------------- Le taux de réussite est calculé directement par extraction des métadonnées JUnitXML (``test_results.xml``) : .. math:: \text{Taux de Succès} = \frac{\text{Tests Validés}}{\text{Tests Exécutés}} \times 100 Chaque suite est validée indépendamment avec un taux de réussite de 100.0%. ---- Couverture de Code (Code Coverage) ================================== La métrologie de couverture repose sur ``pytest-cov`` et le format JSON intermédiaire (``coverage.json``). Répartition de la Couverture par Module --------------------------------------- .. list-table:: Matrice de Couverture des Modules Principaux :widths: 40 20 20 20 :header-rows: 1 * - Module Mirza - Lignes Totales - Lignes Manquées - Taux de Couverture * - ``mirza/config.py`` - 72 - 0 - **100.0%** * - ``mirza/core/telemetry.py`` - 28 - 0 - **100.0%** * - ``mirza/core/logger.py`` - 43 - 0 - **100.0%** * - ``mirza/audio/vadDetector.py`` - 31 - 0 - **100.0%** * - ``mirza/pipeline/contextManager.py`` - 88 - 1 - **98.9%** * - ``mirza/audio/audioProcessor.py`` - 105 - 5 - **95.2%** * - ``mirza/server/routes/websocket.py`` - 193 - 9 - **95.3%** * - ``mirza/server/sslManager.py`` - 54 - 3 - **94.4%** * - ``mirza/core/textNormalizer.py`` - 66 - 4 - **93.9%** * - ``mirza/server/routes/system.py`` - 112 - 9 - **92.0%** * - ``mirza/engine/llm/mtplxProcessSupervisor.py`` - 78 - 7 - **91.0%** * - ``mirza/engine/stt/sttAlternative.py`` - 22 - 2 - **90.9%** * - ``mirza/core/episodicMemory.py`` - 114 - 14 - **87.7%** * - ``mirza/pipeline/audioStreamPipeline.py`` - 73 - 9 - **87.7%** * - ``mirza/engine/agent/agentManager.py`` - 108 - 18 - **83.3%** * - ``mirza/core/memory/embeddingEngine.py`` - 71 - 12 - **83.1%** * - ``mirza/server/widgetServer.py`` - 160 - 29 - **81.9%** * - ``mirza/core/memoryManager.py`` - 96 - 17 - **82.3%** * - ``mirza/engine/stt/sttLocal.py`` - 40 - 7 - **82.5%** * - ``mirza/core/streamParsers.py`` - 363 - 71 - **80.4%** * - ``mirza/audio/deviceManager.py`` - 60 - 12 - **80.0%** * - ``mirza/pipeline/conversationOrchestrator.py`` - 574 - 191 - **66.7%** ---- Politique d'Analyse Statique et Linting (Ruff) ============================================== Pour préserver une base de code maintenable, performante et exempte de dettes techniques, Mirza utilise **Ruff** comme linter et outil de vérification de style unifié. Configuration du Linter ----------------------- La configuration est déclarée dans ``pyproject.toml`` : .. code-block:: toml [tool.ruff] target-version = "py312" line-length = 120 [tool.ruff.lint] select = [ "E", # Erreurs Pycodestyle "F", # Erreurs Pyflakes (variables non définies, imports morts) "W", # Avertissements Pycodestyle "I", # Ordonnancement automatique des imports (isort) "UP", # Modernisation syntaxique Python 3.12+ (pyupgrade) "PIE", # Bonnes pratiques flake8-pie "RUF", # Règles spécifiques avancées de Ruff ] ignore = [ "E501", # Longueur maximale de ligne gérée par le formateur ] Règles de Qualité Appliquées ---------------------------- * **Absence d'imports inutilisés (F401)** : Aucun import mort dans les modules ou les tests afin d'éviter les surcoûts d'initialisation mémoire. * **Ordonnancement strict des imports (I001)** : Tri alphabétique regroupé (standard library, tierces parties, modules locaux ``mirza``). * **Détection du code mort et des variables inutilisées (F841, RUF059)** : Toutes les variables assignées ou déballées doivent être consommées ou préfixées par un underscore (``_``). * **Modernisation syntaxique continue (UP)** : Utilisation des annotations de type modernes et abandon des constructions obsolètes. Résultats d'Analyse ------------------- L'analyse de l'intégralité du code source (``mirza/``, ``tests/`` et ``scripts/tools/``) ne relève **aucune anomalie** : .. code-block:: text $ uv run ruff check mirza tests scripts/tools All checks passed! ---- Architecture Modulaire des Scripts d'Exploitation ================================================= Afin de proscrire toute injection de code Python à la volée (heredocs shell ou commandes inline ``python -c``), l'ensemble de la logique d'automatisation a été découplée au sein du package autonome ``scripts/tools/`` : * **``scripts/tools/generate_test_report.py``** : Module Python autonome responsable de la lecture et de la fusion des rapports JUnit (``test_results.xml``), de couverture (``coverage.json``) et de linting (``ruff_report.json``). Il génère automatiquement le document Markdown consolidé ``test_report.md`` sans dépendre d'interpréteurs shell. * **``scripts/tools/preflight_check.py``** : Module Python d'initialisation et de diagnostic pré-vol appelé par ``scripts/start_mirza.sh`` : * ``--get-local-ip`` : résolution déterministe de l'adresse IP locale LAN. * ``--ensure-ssl`` : validation et émission des certificats TLS avec SAN (LAN et Tailscale). * ``--smoke-test`` : contrôle de cohérence des imports backend et des plafonds de KV Cache. Les scripts shell ``scripts/run_tests.sh`` et ``scripts/start_mirza.sh`` conservent ainsi un rôle strict d'orchestration système en shell POSIX pur. ---- Intégration Continue (GitHub Actions) ===================================== La validation et le déploiement de Mirza sont entièrement automatisés via GitHub Actions : Pipeline d'Intégration Continue (``.github/workflows/ci.yml``) -------------------------------------------------------------- Déclenché à chaque ``push`` et ``pull_request`` sur les branches cibles (``main``, ``optimum``, branches de fonctionnalités ``feat/*``) : 1. **Job ``lint``** (Ubuntu) : Contrôle de conformité rapide du code via ``astral-sh/setup-uv`` et exécution de ``ruff check mirza tests scripts/tools``. 2. **Job ``test``** (macOS Apple Silicon) : Installation de l'environnement virtuel sous ``uv sync``, exécution complète de ``./scripts/run_tests.sh`` et publication des artefacts de test (``test_report.md``, ``test_results.xml``, ``coverage.json``) via ``actions/upload-artifact@v4``. 3. **Job ``docs-check``** (Ubuntu) : Compilation préventive de la documentation Sphinx (``sphinx-build -b html docs docs/_build/html``) pour prévenir toute régression documentaire. Pipeline de Déploiement de la Documentation (``.github/workflows/deploy.yml``) ------------------------------------------------------------------------------ Compile la documentation Sphinx et déploie automatiquement les pages HTML vers le serveur distant o2switch par transfert FTPS sécurisé. Protection de l'Arbre Git (``.gitignore``) ------------------------------------------ Pour garantir la propreté du dépôt, les artefacts de compilation Sphinx (``docs/_build/``, ``docs/.doctrees/``, ``.doctrees/``) ainsi que les rapports intermédiaires du linter (``ruff_report.json``) sont strictement exclus du versionnement Git.