aissia/tests/integration/README.md

AISSIA Integration Tests

Système de tests d'intégration modulaires pour valider AISSIA en conditions réelles.

Architecture

Philosophie : "Un module = Un test"

Chaque test d'intégration est un module GroveEngine indépendant (.so) :

• Chargé dynamiquement par le TestRunnerModule
• Exécute un scénario spécifique
• Retourne un résultat (pass/fail + détails)
• Peut être modifié et hot-reload sans tout recompiler

AISSIA --run-tests
  ├─ TestRunnerModule (orchestrateur)
  │   ├─ Découvre tests/integration/IT_*.so
  │   ├─ Pour chaque test:
  │   │   ├─ Charge dynamiquement
  │   │   ├─ Execute via execute()
  │   │   ├─ Collecte résultat
  │   │   └─ Décharge
  │   ├─ Génère rapport console
  │   ├─ Génère rapport JSON
  │   └─ Exit(0|1)
  │
  └─ Tests d'intégration (.so)
      ├─ IT_001_GetCurrentTime
      ├─ IT_002_FileSystemWrite
      ├─ IT_003_FileSystemRead
      ├─ IT_004_MCPToolsList
      ├─ IT_005_VoiceToAI
      ├─ IT_006_AIToLLM
      ├─ IT_007_StorageWrite
      └─ IT_008_StorageRead

Tests Disponibles

Phase 1: Tests MCP (Tools)

Test	Description	Durée
IT_001_GetCurrentTime	Test tool get_current_time via AI	~2s
IT_002_FileSystemWrite	Test tool filesystem_write	~3s
IT_003_FileSystemRead	Test tool filesystem_read	~3s
IT_004_MCPToolsList	Vérification inventaire tools (≥5)	~3s

Phase 2: Tests Flux

Test	Description	Durée
IT_005_VoiceToAI	Communication Voice → AI	~2s
IT_006_AIToLLM	Requête AI → Claude API (réelle)	~5s
IT_007_StorageWrite	AI → Storage (sauvegarde note)	~4s
IT_008_StorageRead	AI → Storage (lecture note)	~4s

Utilisation

Build

# Build complet
cmake -B build -DBUILD_TESTING=ON
cmake --build build -j4

# Build seulement tests d'intégration
cmake --build build --target integration_tests -j4

Exécution

# Lancer tous les tests
cd build && ./aissia --run-tests

# Résultats
# - Console: rapport détaillé avec ✅/❌
# - JSON: test-results.json avec détails complets
# - Exit code: 0 = success, 1 = au moins un échec

Exemple de sortie

========================================
  AISSIA Integration Tests
  Running 8 test(s)...
========================================

[1/8] IT_001_GetCurrentTime............ ✅ PASS (1.8s)
        Tool returned valid time

[2/8] IT_002_FileSystemWrite........... ✅ PASS (2.3s)
        File created with correct content

[3/8] IT_003_FileSystemRead............ ✅ PASS (1.9s)
        Content read correctly

[4/8] IT_004_MCPToolsList.............. ✅ PASS (3.1s)
        Found 9 tools in response

[5/8] IT_005_VoiceToAI................. ✅ PASS (1.5s)
        AI received and processed voice transcription

[6/8] IT_006_AIToLLM................... ✅ PASS (4.7s)
        LLM response received and coherent

[7/8] IT_007_StorageWrite.............. ✅ PASS (3.8s)
        Note saved successfully

[8/8] IT_008_StorageRead............... ✅ PASS (3.2s)
        Note retrieved successfully

========================================
Results: 8/8 passed (100%)
Total time: 22.3s
========================================

Exit code: 0

Configuration

Global : config/test_runner.json

{
    "enabled": true,
    "testDirectory": "tests/integration",
    "globalTimeoutMs": 300000,
    "stopOnFirstFailure": false,
    "verboseOutput": true,
    "jsonOutputPath": "test-results.json"
}

Par test : config/integration/IT_XXX.json

{
    "enabled": true,
    "timeoutMs": 10000,
    "retryCount": 0,
    "description": "Test description",
    "tags": ["mcp", "tools", "quick"]
}

Ajouter un nouveau test

1. Créer le module : tests/integration/IT_XXX_TestName.cpp

#include <shared/testing/ITestModule.h>
#include <grove/JsonDataNode.h>
#include <grove/IIO.h>

namespace aissia::testing {

class IT_XXX_TestName : public ITestModule {
public:
    std::string getTestName() const override {
        return "IT_XXX_TestName";
    }

    std::string getDescription() const override {
        return "Description du test";
    }

    // Implémenter les méthodes virtuelles de IModule
    void setConfiguration(...) override { ... }
    void process(...) override {}
    void shutdown() override {}
    const IDataNode& getConfiguration() override { ... }
    std::unique_ptr<IDataNode> getHealthStatus() override { ... }
    std::unique_ptr<IDataNode> getState() override { ... }
    void setState(...) override {}
    std::string getType() const override { return "IT_XXX_TestName"; }
    int getVersion() const override { return 1; }
    bool isIdle() const override { return true; }

    // Logique du test
    TestResult execute() override {
        TestResult result;
        result.testName = getTestName();

        try {
            // 1. Envoyer requête IIO
            auto request = std::make_unique<JsonDataNode>("request");
            request->setString("query", "...");
            m_io->publish("topic:name", std::move(request));

            // 2. Attendre réponse
            auto response = waitForMessage("topic:response", timeout);

            // 3. Valider
            result.passed = /* validation */;
            result.message = "...";

        } catch (const std::exception& e) {
            result.passed = false;
            result.message = e.what();
        }

        return result;
    }

private:
    std::unique_ptr<IDataNode> waitForMessage(
        const std::string& topic, int timeoutMs) {
        // Polling avec timeout
    }

    IIO* m_io = nullptr;
};

} // namespace aissia::testing

extern "C" {
    grove::IModule* createModule() {
        return new aissia::testing::IT_XXX_TestName();
    }

    void destroyModule(grove::IModule* module) {
        delete module;
    }
}

2. Ajouter au CMakeLists.txt : tests/CMakeLists.txt

add_integration_test(IT_XXX_TestName)

add_custom_target(integration_tests
    DEPENDS
        ...
        IT_XXX_TestName
    ...
)

3. Build et test

cmake --build build --target integration_tests
cd build && ./aissia --run-tests

Notes Importantes

Conditions Réelles

Les tests utilisent de vraies ressources :

• Claude API : Requêtes réelles (coût tokens)
• Fichiers : Écriture dans data/ (cleanup auto)
• Réseau : Requêtes HTTP réelles

⚠️ Les tests peuvent échouer si :

• API Claude down ou clé invalide
• Problèmes réseau
• Disk plein

Timeouts

• Tests MCP simples : 5-10s
• Tests LLM : 30s (Claude peut être lent)
• Test complet (IT_009) : 60s

Isolation

Chaque test :

• Ne pollue pas les autres
• Cleanup automatique des fichiers temporaires
• ConversationId unique pour éviter les collisions

CI/CD

#!/bin/bash
# ci-test.sh

cmake -B build -DBUILD_TESTING=ON
cmake --build build --target integration_tests -j4

./build/aissia --run-tests --json-output results.json

# Exit code: 0 = success, 1 = failure
exit $?

Développement

Structure du code

tests/
├── integration/
│   ├── IT_001_GetCurrentTime.cpp
│   ├── IT_002_FileSystemWrite.cpp
│   └── ...
├── CMakeLists.txt
└── README.md (ce fichier)

src/
├── shared/
│   └── testing/
│       └── ITestModule.h         # Interface de base
└── modules/
    └── TestRunnerModule.{h,cpp}  # Orchestrateur

config/
├── test_runner.json
└── integration/
    ├── IT_001.json
    └── ...

Bonnes pratiques

1. Nommage : IT_XXX_DescriptiveName (XXX = numéro séquentiel)
2. Taille : ~150-200 lignes par test max
3. Timeout : Toujours utiliser un timeout raisonnable
4. Cleanup : Supprimer les fichiers/données temporaires
5. Logs : Utiliser spdlog::info pour debugging
6. Erreurs : Toujours catcher les exceptions

Roadmap

Implémenté ✅

• Infrastructure (ITestModule, TestRunnerModule)
• Tests MCP (IT_001-004)
• Tests Flux (IT_005-008)

À venir 📋

• Test end-to-end (IT_009_FullConversationLoop)
• Tests modules (IT_010-013: Scheduler, Notification, Monitoring, Web)
• Tests avancés (hot-reload, charge, récupération d'erreur)
• Dashboard web pour visualisation des résultats

---

Auteur : Claude Code Date : 2025-11-28 Version : 1.0.0