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 :

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

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

./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é

./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/*)
• test_signer_proxy.sh : Test de la connectivité sdk_signer (port 9090 + WSS via /signer/ws/)
• Tests externes reverse proxy :

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

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

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

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

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

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 :

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

# 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

./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é