sdk_client/docs/TESTING.md

Guide des tests — sdk_client

Ce guide décrit la stratégie de tests pour sdk_client (Rust et WASM), l’organisation et les critères d’acceptation, sans exemples exécutables.

Vue d'Ensemble

Catégories cibles:

• Tests unitaires Rust (fonctions pures, conversions, sérialisation, erreurs)
• Tests d’intégration (parcours API api.rs en environnement contrôlé)
• Tests WASM (frontière wasm_bindgen/serde_wasm_bindgen)
• Tests de non‑régression (contrats/structures stables)

Arborescence des tests

Répertoires fournis:

• tests/unit, tests/integration: tests Rust selon le périmètre du SDK.
• tests/logs, tests/reports: traces et rapports standardisés.
• tests/cleanup.sh: nettoyage reproductible.

Exécution des tests

Exécution standard: unité, intégration, puis front WASM. Les seuils et critères sont définis ci‑dessous.

Prérequis tests WASM (Windows)

• Outils: wasm-pack et LLVM/Clang installés.

  • LLVM via winget install -e --id LLVM.LLVM --accept-package-agreements --accept-source-agreements --silent.
  • Variables d’environnement (utilisateur) à définir une seule fois, puis ouvrir un nouveau PowerShell:
    • CC = C:\\Program Files\\LLVM\\bin\\clang.exe
    • TARGET_CC = C:\\Program Files\\LLVM\\bin\\clang.exe
    • CC_wasm32-unknown-unknown = C:\\Program Files\\LLVM\\bin\\clang.exe
    • AR_wasm32-unknown-unknown = C:\\Program Files\\LLVM\\bin\\llvm-ar.exe
    • NM_wasm32-unknown-unknown = C:\\Program Files\\LLVM\\bin\\llvm-nm.exe

• Runner wasm-bindgen:

  • Le script scripts/run-wasm-tests.ps1 télécharge automatiquement wasm-bindgen (0.2.100) si absent et exporte WASM_BINDGEN_TEST_RUNNER.
  • En cas d’échec de téléchargement automatique, placer manuellement le binaire wasm-bindgen-test-runner.exe dans C:\\Users\\<USER>\\AppData\\Local\\.wasm-pack\\wasm-bindgen-<hash>\\.

Exécution des tests WASM

• Automatisé: ./scripts/run-wasm-tests.ps1
  • Tente Node en priorité, puis navigateurs si nécessaire.
  • Purge/recale le cache .wasm-pack si requis.
• Manuel: wasm-pack test --node (ou --headless --chrome, --headless --firefox).

Options disponibles :

• --verbose : Mode verbose avec affichage détaillé
• --debug : Mode debug complet
• --skip-unit : Ignorer les tests unitaires
• --skip-integration : Ignorer les tests d'intégration
• --skip-connectivity : Ignorer les tests de connectivité
• --skip-external : Ignorer les tests externes

Tests par catégorie

Tests Unitaires

./tests/run_unit_tests.sh [--verbose] [--debug]

Tests inclus :

• test_healthcheck.sh : Test du healthcheck de sdk_relay
• test_docker.sh : Test de la configuration Docker
• test_simple.sh : Test simple de sdk_relay
• test_final.sh : Test final de sdk_relay

Prérequis : chaîne Rust opérationnelle, configuration WASM selon docs/CONFIGURATION.md.

Tests d'Intégration

./tests/run_integration_tests.sh [--verbose] [--debug]

Tests inclus :

• test_3_relays.sh : Test de 3 instances sdk_relay
• test_final_sync.sh : Test complet de synchronisation
• test_sync_logs.sh : Test des logs de synchronisation
• test_messages.sh : Test des messages entre relais

Prérequis : dépendances de test disponibles, mocks si nécessaires.

Tests de Connectivité

./tests/run_connectivity_tests.sh [--verbose] [--debug]

Tests inclus :

• test_connectivity.sh : Test de connectivité des services
• test_websocket_messages.py : Test des messages WebSocket

Prérequis : environnement headless supporté pour l’exécution WASM (si applicable).

Tests Externes

./tests/run_external_tests.sh [--verbose] [--debug]

Tests inclus :

• test_dev3_simple.py : Test simple de dev3.4nkweb.com
• test_dev3_connectivity.py : Test de connectivité dev3
• test_integration_dev3.sh : Test d'intégration dev3

Prérequis :

• Connectivité internet
• Python3 avec websockets installé
• Services locaux optionnels

Test Individuel

Pour exécuter un test spécifique :

# Test shell
./tests/integration/test_3_relays.sh

# Test Python
python3 tests/external/test_dev3_simple.py

Interprétation des résultats

Codes de Sortie

• 0 : Test réussi
• 1 : Test échoué
• 2 : Test ignoré (prérequis non satisfaits)

Logs

Les logs détaillés sont écrits dans tests/logs/ avec le format :

YYYY-MM-DD_HH-MM-SS_category_tests.log

Exemples :

• 2024-12-19_14-30-25_unit_tests.log
• 2024-12-19_14-35-12_integration_tests.log

Rapports

Les rapports JSON sont générés dans tests/reports/ avec le format :

test_report_YYYY-MM-DD_HH-MM-SS.json

Structure du rapport :

{
    "timestamp": "2024-12-19_14-30-25",
    "summary": {
        "total_tests": 10,
        "successful_tests": 8,
        "failed_tests": 2,
        "success_rate": 80.0
    },
    "log_file": "tests/logs/test_run_2024-12-19_14-30-25.log",
    "options": {
        "verbose": false,
        "debug": false,
        "skip_unit": false,
        "skip_integration": false,
        "skip_connectivity": false,
        "skip_external": false,
        "skip_performance": true
    }
}

Détail des tests

Tests Unitaires

test_healthcheck.sh

• Objectif : Vérifier le fonctionnement du healthcheck de sdk_relay
• Méthode : Test du script healthcheck.sh dans un conteneur
• Critères de succès : Healthcheck retourne un code de sortie approprié

test_docker.sh

• Objectif : Vérifier la configuration Docker de sdk_relay
• Méthode : Test de la construction et du démarrage du conteneur
• Critères de succès : Conteneur démarre correctement

test_simple.sh

• Objectif : Test simple de sdk_relay
• Méthode : Démarrage et test basique de sdk_relay
• Critères de succès : Service répond aux requêtes de base

test_final.sh

• Objectif : Test final complet de sdk_relay
• Méthode : Test complet avec toutes les fonctionnalités
• Critères de succès : Toutes les fonctionnalités opérationnelles

Tests d’intégration

test_3_relays.sh

• Objectif : Tester 3 instances sdk_relay en parallèle
• Méthode : Démarrage de 3 relais et vérification de leur interaction
• Critères de succès : Les 3 relais communiquent correctement

test_final_sync.sh

• Objectif : Test complet de la synchronisation
• Méthode : Test de tous les types de synchronisation
• Critères de succès : Synchronisation fonctionnelle entre tous les relais

test_sync_logs.sh

• Objectif : Vérifier les logs de synchronisation
• Méthode : Analyse des logs de synchronisation
• Critères de succès : Logs cohérents et sans erreurs

test_messages.sh

• Objectif : Tester l'échange de messages entre relais
• Méthode : Envoi et réception de messages de test
• Critères de succès : Messages correctement transmis

Frontière WASM

• Objectif: valider la sérialisation/desérialisation et la robustesse des erreurs à la frontière.

Tests externes

Si des environnements externes sont utilisés, documenter explicitement les prérequis et jeux de données.

Dépannage

Problèmes Courants

Services non démarrés

Symptôme : Erreur "Service non trouvé" Solution : Démarrer les services avec ./restart_4nk_node.sh

Connectivité réseau

Symptôme : Timeout ou erreur de connexion Solution : Vérifier les ports et pare-feu

Certificats SSL

Symptôme : Erreur SSL dans les tests externes Solution : Vérifier les certificats et la configuration SSL

Dépendances Python

Symptôme : ModuleNotFoundError Solution : Installer les dépendances avec pip install websockets

Debug

Mode Verbose

./tests/run_all_tests.sh --verbose

Mode Debug

./tests/run_all_tests.sh --debug

Test spécifique avec debug

./tests/integration/test_3_relays.sh --debug

Maintenance

Nettoyage Automatique

Nettoyer les logs anciens

./tests/cleanup.sh --days 7

Nettoyer les rapports anciens

./tests/cleanup.sh --reports --days 30

Nettoyage complet

./tests/cleanup.sh --all --days 7

Simulation de nettoyage

./tests/cleanup.sh --all --dry-run

Surveillance

Vérifier l'espace disque

du -sh tests/logs tests/reports

Lister les fichiers récents

find tests/logs -name "*.log" -mtime -1

Analyser les échecs

grep -r "ERROR\|FAILED" tests/logs/

Ajout de nouveaux tests

Structure Recommandée

Pour ajouter un nouveau test :

1. Créer le fichier de test dans le répertoire approprié
2. Ajouter le test au script d'exécution correspondant
3. Documenter le test dans ce guide
4. Tester le test pour s'assurer qu'il fonctionne

Template de Test Shell

#!/bin/bash
# Test: Description du test
# Auteur: Nom
# Date: YYYY-MM-DD

set -e

# Configuration
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
LOG_FILE="tests/logs/$(date +%Y-%m-%d_%H-%M-%S)_test_name.log"

# Fonctions
log() {
    echo "[$(date +%Y-%m-%d\ %H:%M:%S)] $1" | tee -a "$LOG_FILE"
}

# Test principal
main() {
    log "Début du test"

    # Vérifications préliminaires
    check_prerequisites

    # Exécution du test
    run_test

    # Vérification des résultats
    verify_results

    log "Test terminé avec succès"
}

# Exécution
main "$@"

Template de Test Python

#!/usr/bin/env python3
"""
Test: Description du test
Auteur: Nom
Date: YYYY-MM-DD
"""

import asyncio
import json
import logging
from datetime import datetime

# Configuration du logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

async def test_function():
    """Fonction de test principale"""
    logger.info("Début du test")

    try:
        # Logique de test
        result = await run_test()

        # Vérification
        if result:
            logger.info("Test réussi")
            return True
        else:
            logger.error("Test échoué")
            return False

    except Exception as e:
        logger.error(f"Erreur lors du test: {e}")
        return False

async def main():
    """Fonction principale"""
    success = await test_function()
    exit(0 if success else 1)

if __name__ == "__main__":
    asyncio.run(main())

Intégration continue

Automatisation

Les tests peuvent être intégrés dans un pipeline CI/CD :

# Exemple GitHub Actions
- name: Run Tests
  run: |
    cd tests/
    ./run_all_tests.sh --verbose

Surveillance Continue

Pour une surveillance continue :

# Cron job pour tests quotidiens
0 2 * * * cd /path/to/4NK_node/tests && ./run_all_tests.sh >> /var/log/4nk_tests.log 2>&1

Support

Pour obtenir de l'aide :

1. Consulter les logs : tests/logs/
2. Vérifier la documentation : tests/README.md
3. Utiliser le mode debug : --debug
4. Consulter les rapports : tests/reports/

Évolution

Tests de Performance (À venir)

• Tests de charge
• Tests de latence
• Tests de débit
• Tests de stress

Tests de Sécurité (À venir)

• Tests de vulnérabilités
• Tests de pénétration
• Tests de configuration

Tests d'Interface (À venir)

• Tests d'API REST
• Tests d'interface WebSocket
• Tests de compatibilité