Stratégie de Tests & Conventions (Agent)

1. Philosophie & Règle générale

L’Agent Berth est un composant critique s’exécutant directement sur les serveurs clients hôtes. Afin de garantir sa robustesse, sa stabilité opérationnelle et l’isolation vis-à-vis du daemon Docker local, une stratégie de tests rigoureuse et multi-niveaux est appliquée.

Fichier source	Fichier de test associé	Description
`internal/config/config.go`	`internal/config/config_test.go`	Validation du chargement YAML, variables d’environnement et règles de validation
`internal/docker/discovery.go`	`internal/docker/discovery_test.go`	Tests de détection et filtrage des conteneurs via mock Docker SDK
`internal/grpc/actions.go`	`internal/grpc/actions_test.go`	Validation de la réception, validation et exécution des commandes gRPC
`internal/metrics/collector.go`	`internal/metrics/collector_test.go`	Tests unitaire des calculs de deltas CPU/RAM/réseau
`internal/resilience/breaker.go`	`internal/resilience/breaker_test.go`	Validation des états et transitions du Circuit Breaker

2. Organisation des tests par couche

L’architecture de l’Agent découple rigoureusement l’accès au daemon Docker, la communication gRPC et la logique locale de buffering / résilience. Les tests reflètent cette séparation :

2.1 Tests unitaires & Logique métier (`internal/metrics/`, `internal/resilience/`, `internal/security/`)

Ces tests s’exécutent en mémoire, sans dépendance externe ni daemon Docker actif :

Couche testée	Fichier cible	Approche & Responsabilités
Collecteurs & Métriques	`metrics/*_test.go`	Teste unitairement les calculs de deltas CPU/RAM/réseau/blkio et le formatage des métriques hôte.
Résilience & Spool	`resilience/*_test.go`	Valide le comportement du backoff exponentiel avec jitter, l’ouverture/fermeture du circuit breaker, ainsi que la politique FIFO et d’éviction du spool local borné.
Sécurité & Enrôlement	`security/*_test.go`	Contrôle la validation des certificats mTLS, le cycle de vie du bootstrap token et les permissions de stockage.
Configuration	`config/config_test.go`	Valide le parsing YAML, la priorité des variables d’environnement et les valeurs par défaut.

2.2 Simulation Docker SDK via Mocks (`internal/docker/`)

La logique métier ne dépend pas directement du client Docker concret (*client.Client), mais d’une interface Go (mock.go) :

Discovery & Lifecycle : simule la détection des conteneurs, les événements Docker Engine et les changements d’état sans démarrer de daemon.
Actions déterministes : vérifie la traduction rigoureuse des erreurs (ex. un ordre stop ou restart sur un conteneur absent doit retourner une erreur déterministe et propre).
Extraction des logs : teste le découpage, le framing et la gestion du contexte d’annulation des flux de logs conteneurs.

2.3 Tests de transport gRPC & mTLS (`internal/grpc/`, `internal/streaming/`)

Pour tester la couche de transport gRPC sans dépendre d’une connexion réseau externe :

bufconn (In-Memory gRPC) : utilisation de google.golang.org/grpc/test/bufconn pour émuler les connexions réseau en mémoire.
Validation mTLS : injection de certificats de test pour valider l’authentification mutuelle client/serveur, le rejet des certificats inconnus ou expirés.
Deadlines & Annulations : vérification de la propagation du contexte context.WithTimeout, de l’annulation d’un stream de logs et de la gestion des metadata.

2.4 Tests d’intégration & Conteneurs éphémères

Les tests d’intégration valident l’interaction réelle avec le daemon Docker :

Docker de test / Testcontainers : démarrage de conteneurs éphémères pour valider les flux Events, Stats, ContainerLogs(Follow), pull et l’exécution de commandes (exec).
Scénarios de résilience : simulation de coupures réseau de l’API Berth ou d’arrêts imprévus du daemon Docker pour vérifier le remplissage du spool, la reconnexion automatique et la déduplication des messages.
Sécurité : vérification de l’application stricte de la liste blanche d’arguments pour les commandes exec et rejet des tokens réutilisés.

3. Exceptions à la règle

Il existe des cas spécifiques où un fichier Go ne nécessite pas de fichier de test unitaire direct :

Périmètre	Fichier concerné	Règle & Justification
Point d’entrée principal `cmd/agent/main.go`	Aucun fichier requis	Ne contient que le câblage de démarrage (lecture de configuration, gestion des signaux OS `SIGINT`/`SIGTERM` et graceful shutdown). La logique sous-jacente est entièrement couverte dans `internal/`.
Modèles purs & DTOs `pkg/model/`	Aucun fichier requis	Structures de données pures sans méthodes ni règles métier complexes.
Code généré Protobuf `proto/*.pb.go`, `internal/grpc/proto/`	Aucun fichier requis	Code auto-généré par le compilateur `protoc` / `buf`, exempté de tests unitaires dédiés.

4. Outils & Bonnes pratiques

Outil / Pratique	Usage	Description & Recommandation
Testify (`require`)	Assertions bloquantes	`require.NoError(t, err)`, `require.NotNil(t, result)` — interrompt immédiatement le test en cas d’échec critique.
Testify (`assert`)	Assertions non bloquantes	`assert.Equal(t, expected, actual)` — enregistre l’échec et poursuit l’exécution du scénario.
gRPC `bufconn`	Transport réseau en mémoire	Permet d’exécuter des tests gRPC ultra-rapides et déterministes sans ouvrir de port TCP réel.
Mocks d’interfaces	Isolation du Docker SDK	Permet d’émuler l’ensemble des réponses et erreurs de l’API Docker sans dépendance matérielle.
Race Detector	Détection de concurrence	Flag `-race` systématiquement activé pour valider la sécurité concurrente des workers (discovery, metrics, streaming).

Commandes utiles

# Exécuter tous les tests unitaires avec détection de concurrence
go test -v -race ./internal/...

# Exécuter les tests d'un package spécifique (ex: résilience)
go test -v -race ./internal/resilience/...

# Exécuter les tests avec calcul de couverture
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

# Exécuter les tests d'intégration nécessitant Docker
go test -v -tags=integration ./...