Stratégie de Tests & Conventions (Server)

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

Afin de garantir la fiabilité, la maintenabilité et la non-régression du serveur Berth, une couverture de tests stricte est appliquée.

Fichier source	Fichier de test associé	Description
`internal/config/config.go`	`internal/config/config_test.go`	Validation du chargement et des valeurs par défaut
`internal/database/postgres.go`	`internal/database/postgres_test.go`	Validation de la connexion et du pool PostgreSQL
`internal/modules/health/handler.go`	`internal/modules/health/handler_test.go`	Tests HTTP du transport Gin pour le module
`internal/modules/health/query/health.go`	`internal/modules/health/query/health_test.go`	Tests unitaire de la logique Query CQRS

2. Organisation des tests par couche

L’architecture du serveur repose sur le découpage modulaire et le pattern CQRS. Les tests suivent cette organisation pour éviter le couplage et permettre une exécution rapide et ciblée.

2.1 Modules métier (`internal/modules/<feature>/`)

C’est ici que se concentre la quasi-totalité des tests de l’application :

Couche testée	Fichier cible	Approche & Responsabilités
Handlers HTTP	`handler_test.go`	Teste la couche de transport HTTP (Gin) avec `net/http/httptest` sans démarrer de serveur réel. • Vérifie le binding / parsing (URL, query, corps JSON), la validation et les headers. • Contrôle les statuts HTTP (`200`, `201`, `400`, `404`, `500`, `503`) et le format JSON. • Isole la logique métier via des mocks / stubs des Command et Query handlers.
Logique métier CQRS	`command/_test.go` `query/_test.go`	Teste unitairement la logique métier, les règles de validation et le flux décisionnel. • Découplé complètement de Gin et du transport HTTP. • Utilise des interfaces mockées (repository, cache, client agent gRPC, checkers) pour tester tous les scénarios (succès, erreurs, cache hit/miss).
Accès aux données & Services	`repository_test.go` `checker_test.go` `cache_test.go`	Teste l’interaction avec les services externes et la base de données. • Utilise Testcontainers (`testcontainers-go`) pour démarrer de véritables instances isolées de PostgreSQL ou Redis lors des tests d’intégration.

2.2 Configuration & Infrastructure (`internal/config/`, `internal/database/`)

Configuration (internal/config/) : valide le chargement des variables d’environnement, les valeurs par défaut et la gestion des erreurs de configuration.
Base de données (internal/database/) : valide la création des connexions et des pools de connexions PostgreSQL et Redis.

3. Exceptions à la règle

Il existe des exceptions explicites où un fichier Go ne nécessite pas de fichier de test dédié ou ne doit pas être testé de manière redondante :

Périmètre	Fichier de test associé	Règle & Justification
Assemblage du routeur `internal/server/routes.go`	`internal/server/routes_test.go`	Ne JAMAIS tester tous les endpoints métier dans `routes_test.go`. • Centraliser tous les tests de routes créerait un goulot d’étranglement et une duplication inutile, chaque endpoint étant déjà testé unitairement dans son module (`handler_test.go`). • `routes_test.go` doit uniquement valider l’initialisation du routeur Gin (`SetupRouter`), les middlewares globaux (CORS, Logger, Recovery, 404) et un éventuel smoke test d’infrastructure.
Points d’entrée `cmd/api/main.go` `cmd/migration/main.go`	Aucun requis	Aucun fichier de test requis dans `cmd/`. • Les fichiers `main.go` ne contiennent que du câblage de démarrage (lecture de configuration, instanciation des dépendances et appel à `Run()` ou `Execute()`). • Toute la logique sous-jacente est testée dans `internal/`. Couverture ultérieure par des tests End-to-End (E2E) si nécessaire.
Modèles de domaine purs `internal/domain/`	Aucun requis	Structures simples sans logique métier. • Les fichiers ne contenant que des structures de données simples sans méthodes ou règles métier complexes ne nécessitent pas de fichier `_test.go` dédié.

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 pour détecter d’autres anomalies.
Testcontainers Go	Conteneurs éphémères	Démarrage d’instances réelles PostgreSQL et Redis pour les tests d’intégration fiables et isolés.
Race Detector	Détection de concurrence	Flag `-race` obligatoire lors de l’exécution pour détecter les accès concurrents non protégés.

Commandes utiles

# Exécuter tous les tests avec détection de race conditions et couverture
go test ./... -race -cover

# Exécuter les tests d'un module spécifique
go test ./internal/modules/health/... -race -cover

# Générer un rapport de couverture détaillé en HTML
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html