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.

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 :

Indicateurs d’Assurance Qualité Mirza

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 <result>.

  • 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) :

\[\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

Matrice de Couverture des Modules Principaux

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 :

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

$ 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.