4NK_node/docs/TESTING.md

# Guide de Tests - 4NK Node

Ce guide documente l'ensemble des tests disponibles pour l'infrastructure 4NK Node, leur organisation et leur utilisation.

## Vue d'Ensemble

L'infrastructure 4NK Node 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
 - `scripts/test_ui.sh` : Build UI, déploiement reverse proxy et vérifications HTTPS (headers, index, modules JS)

**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
- `test_storage_proxy.sh` : Test de l’API sdk_storage via le reverse proxy (`/storage/*`)
 - Tests externes reverse proxy :
```bash
curl -kI https://<IP_VM>/
curl -kI https://<IP_VM>/api/
npx wscat -c wss://<IP_VM>/ws --no-check
```

**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épannage Tor/Bitcoin (signet custom)

#### Vérifier Tor
```bash
# État du conteneur Tor
sudo docker compose ps tor

# Derniers logs Tor
sudo docker logs tor-proxy --tail=60

# Test du port SOCKS interne
sudo docker exec tor-proxy nc -z 127.0.0.1 9050 && echo SOCKS:OK
```

#### Bridges obfs4 et diagnostics

- Les bridges obfs4 peuvent être ajoutés dans `tor/torrc` (cf. docs/CONFIGURATION.md). Après ajout, redémarrer le service Tor.
- En cas d’échec « general SOCKS server failure », remplacer/ajouter des bridges et re‑tester.
- Valider la différence entre :
  - `nc -vz -w 10 -x 127.0.0.1:9050 -X 5 duckduckgogg42xjoc72x3sjasowoarfbgcmvfimaftt6twagswzczad.onion 80` (référence onion publique)
  - `nc -vz -w 10 -x 127.0.0.1:9050 -X 5 <onion_signet> 38333` (pair signet cible)

#### Vérifier Bitcoin Core côté réseau
```bash
# Connexions réseau
sudo docker exec bitcoin-signet bitcoin-cli -signet getnetworkinfo | jq '.connections,.connections_in,.connections_out'

# Pairs et nombre total
sudo docker exec bitcoin-signet bitcoin-cli -signet getpeerinfo | wc -l
```

#### Forcer une tentative de pair (onion existant)
```bash
ONION=$(awk -F= '/^addnode=/{print $2}' bitcoin/bitcoin.conf | head -n1)
sudo docker exec bitcoin-signet bitcoin-cli -signet addnode ${ONION}:38333 onetry
sleep 5
sudo docker exec bitcoin-signet bitcoin-cli -signet getconnectioncount
```

#### Boucle de retry signet (optionnelle)

Un script dédié permet de tenter automatiquement l’ajout du pair signet `.onion` et de redémarrer `sdk_relay_1` une fois des connexions établies :

```bash
./scripts/retry_signet_sync.sh
```

Les logs sont conservés sous `tests/logs/signet_sync_*.log`.

#### Vérifier l’ouverture des ports du relais et l’API
```bash
# Ports 8090/8091 dans sdk_relay_1
sudo docker exec sdk_relay_1 sh -lc 'ss -lntp 2>/dev/null || netstat -tlnp 2>/dev/null' | grep -E ':8090 |:8091 ' || echo no-listen

# Test /api via reverse proxy
curl -k -I https://localhost/api/
```

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