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

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

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

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

### Par test : `config/integration/IT_XXX.json`

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

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

```cmake
add_integration_test(IT_XXX_TestName)

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

3. **Build et test**

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

```bash
#!/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é ✅

- [x] Infrastructure (ITestModule, TestRunnerModule)
- [x] Tests MCP (IT_001-004)
- [x] 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