4NK_template/docs/TESTING.md

# Guide de Tests - <PROJECT_NAME>

Ce guide documente l'ensemble des tests disponibles pour l'infrastructure <PROJECT_NAME>, leur organisation et leur utilisation.

## Vue d'Ensemble

L'infrastructure <PROJECT_NAME> dispose d'une suite de tests complète organisée en plusieurs catégories :

- **Tests Unitaires** : Tests individuels des composants
- **Tests d'Intégration** : Tests d'interaction entre services
- **Tests de Connectivité** : Tests réseau et WebSocket
- **Tests Externes** : Tests avec des nœuds externes
- **Tests de Performance** : Tests de charge et performance (à venir)

## Structure des Tests

```
tests/
├── README.md                    # Documentation principale des tests
├── run_all_tests.sh            # Exécution de tous les tests
├── run_unit_tests.sh           # Tests unitaires uniquement
├── run_integration_tests.sh    # Tests d'intégration uniquement
├── run_connectivity_tests.sh   # Tests de connectivité uniquement
├── run_external_tests.sh       # Tests externes uniquement
├── cleanup.sh                  # Nettoyage des logs et rapports
├── logs/                       # Logs des tests
├── reports/                    # Rapports de tests
├── unit/                       # Tests unitaires
│   ├── test_healthcheck.sh
│   ├── test_docker.sh
│   ├── test_simple.sh
│   └── test_final.sh
├── integration/                # Tests d'intégration
│   ├── test_3_relays.sh
│   ├── test_final_sync.sh
│   ├── test_sync_logs.sh
│   └── test_messages.sh
├── connectivity/               # Tests de connectivité
│   ├── test_connectivity.sh
│   └── test_websocket_messages.py
├── external/                   # Tests externes
│   ├── test_dev3_simple.py
│   ├── test_dev3_connectivity.py
│   └── test_integration_dev3.sh
└── performance/                # Tests de performance (à créer)
```

## Exécution des Tests

### Test Complet

Pour exécuter tous les tests :

```bash
cd tests/
./run_all_tests.sh
```

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 :**
- Docker installé et fonctionnel
- Image sdk_relay disponible

#### 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 :**
- Tous les services Docker démarrés (bitcoin, blindbit, sdk_relay)
- Infrastructure complète opérationnelle

#### 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 :**
- Services Docker démarrés
- Python3 avec websockets installé

#### 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

### Tests de Connectivité

#### test_connectivity.sh
- **Objectif** : Vérifier la connectivité entre services
- **Méthode** : Test de connectivité réseau entre conteneurs
- **Critères de succès** : Tous les services accessibles

#### test_websocket_messages.py
- **Objectif** : Tester les messages WebSocket
- **Méthode** : Connexion WebSocket et échange de messages
- **Critères de succès** : Communication WebSocket fonctionnelle

### Tests Externes

#### test_dev3_simple.py
- **Objectif** : Test simple de dev3.4nkweb.com
- **Méthode** : Connexion WebSocket simple
- **Critères de succès** : Connexion établie

#### test_dev3_connectivity.py
- **Objectif** : Test complet de connectivité dev3
- **Méthode** : Tests de protocole et handshake
- **Critères de succès** : Tous les protocoles supportés

#### test_integration_dev3.sh
- **Objectif** : Test d'intégration avec dev3
- **Méthode** : Test complet d'intégration
- **Critères de succès** : Intégration fonctionnelle

## 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
```

### Garde de release

Avant toute publication (push/tag), le job CI `release-guard` et le script local `scripts/release/guard.sh` exigent des tests verts. Exécution locale:

```bash
RELEASE_TYPE=ci-verify scripts/release/guard.sh
```

## 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é