453 lines
11 KiB
Markdown
453 lines
11 KiB
Markdown
## 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
|
||
```bash
|
||
./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
|
||
```bash
|
||
./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é
|
||
```bash
|
||
./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
|
||
```bash
|
||
./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 :
|
||
|
||
```bash
|
||
# 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 :
|
||
```json
|
||
{
|
||
"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
|
||
```bash
|
||
./tests/run_all_tests.sh --verbose
|
||
```
|
||
|
||
#### Mode Debug
|
||
```bash
|
||
./tests/run_all_tests.sh --debug
|
||
```
|
||
|
||
#### Test spécifique avec debug
|
||
```bash
|
||
./tests/integration/test_3_relays.sh --debug
|
||
```
|
||
|
||
## Maintenance
|
||
|
||
### Nettoyage Automatique
|
||
|
||
#### Nettoyer les logs anciens
|
||
```bash
|
||
./tests/cleanup.sh --days 7
|
||
```
|
||
|
||
#### Nettoyer les rapports anciens
|
||
```bash
|
||
./tests/cleanup.sh --reports --days 30
|
||
```
|
||
|
||
#### Nettoyage complet
|
||
```bash
|
||
./tests/cleanup.sh --all --days 7
|
||
```
|
||
|
||
#### Simulation de nettoyage
|
||
```bash
|
||
./tests/cleanup.sh --all --dry-run
|
||
```
|
||
|
||
### Surveillance
|
||
|
||
#### Vérifier l'espace disque
|
||
```bash
|
||
du -sh tests/logs tests/reports
|
||
```
|
||
|
||
#### Lister les fichiers récents
|
||
```bash
|
||
find tests/logs -name "*.log" -mtime -1
|
||
```
|
||
|
||
#### Analyser les échecs
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
#!/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
|
||
|
||
```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 :
|
||
|
||
```yaml
|
||
# Exemple GitHub Actions
|
||
- name: Run Tests
|
||
run: |
|
||
cd tests/
|
||
./run_all_tests.sh --verbose
|
||
```
|
||
|
||
### Surveillance Continue
|
||
|
||
Pour une surveillance continue :
|
||
|
||
```bash
|
||
# 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é
|