diff --git a/README.md b/README.md index fc0c954..d0b5ce8 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,14 @@ Arcadia API est une application construite en respectant les principes de la **Clean Architecture** et du **Domain-Driven Design (DDD)**. +## Sommaire + +- [Architecture](#architecture) +- [Principes d'implémentation](#principes-dimplémentation) +- [Tests & Assurance Qualité](#tests--assurance-qualité) + +--- + ## Architecture ![Arcadia API Architecture](resources/architecture.jpg) @@ -19,3 +27,8 @@ L'application est découpée en couches strictes respectant la règle de dépend - **API Read-only** : Pour l'instant, l'API ne fait qu'exposer des données. Nous utilisons donc le pattern `Directory` (lecture seule) plutôt que `Repository` (lecture/écriture) dans nos Ports de Domaine. - **Pattern Presenter** : Les Use Cases (dans `Application`) retournent un `Output` agnostique. La couche `Presentation` utilise ensuite des `Presenters` spécifiques (ex: API) pour transformer cet `Output` en une vue exploitable par l'interface finale (JSON). - **Validation** : La validation stricte du format (ex: HTTP) est gérée dans la couche `Presentation` (via les `FormRequest`). La validation des règles métier est garantie au coeur du `Domain` par les `Value Objects`, qui lèvent des exceptions de type `InvalidArgumentException` traduites en HTTP 422 par le gestionnaire d'erreurs global. + +## Tests & Assurance Qualité + +Consulter le document [TEST.md](TEST.md) pour la stratégie de test en pyramide (Unit, Integration, Feature, Arch) et les commandes d'exécution avec couverture de code. + diff --git a/TEST.md b/TEST.md new file mode 100644 index 0000000..38a8471 --- /dev/null +++ b/TEST.md @@ -0,0 +1,86 @@ +# Tests — Arcadia API + +Ce document récapitule la stratégie et l'organisation des tests dans **Arcadia API**. + +## Sommaire + +- [Tests — Arcadia API](#tests--arcadia-api) + - [Sommaire](#sommaire) + - [1. Commandes](#1-commandes) + - [2. Pyramide de Tests](#2-pyramide-de-tests) + - [3. Structure des Dossiers](#3-structure-des-dossiers) + - [4. Conventions de Code](#4-conventions-de-code) + - [Principes F.I.R.S.T.](#principes-first) + - [Pattern GWT (Given - When - Then)](#pattern-gwt-given---when---then) + +--- + +## 1. Commandes + +```bash +# Exécuter l'ensemble de la suite de tests +composer test + +# Exécuter les tests avec couverture de code (seuil minimal 85%) +composer test:coverage +``` + +## 2. Pyramide de Tests + +``` + . + / \ + / \ 1. FEATURE TESTS (Contrat OpenAPI & E2E) + / \ ---------------------------------------- + / Feature\ - Respect du contrat OpenAPI (openapi.yaml) + /----------\ - Codes statut HTTP (200, 404, 422, 429) & Auth HMAC + / \ - Validation de bout en bout des réponses JSON + / Integration \ + /----------------\ 2. INTEGRATION TESTS (Infra & Laravel) + / \ ---------------------------------------- + / \- Adaptateurs Eloquent (requêtes BDD réelles) + / Unit \- Service Providers & Bindings Laravel + / \- Clients & adaptateurs de services externes + /--------------------------\ + / \ 3. UNIT TESTS (Domaine & Use Cases) + / \------------------------------------ + / \- Entités DDD, Value Objects, règles métier + / \- Use Cases (avec Mocks de Ports) +/____________________________________\- Pure PHP (sans instanciation de Laravel) +``` + +## 3. Structure des Dossiers + +L'arborescence `tests/` reproduit en miroir la structure de `src/` : + +- `tests/Architecture/` : Tests de règles d'architecture DDD, dépendances inter-couches et conventions (Pest Arch). +- `tests/Unit/` : Tests unitaires purs (sans conteneur Laravel, sans BDD, exécution instantanée). +- `tests/Integration/` : Tests des adaptateurs d'infrastructure (BDD, services). +- `tests/Feature/` : Tests de bout en bout des endpoints API (requêtes HTTP, middleware, réponses JSON). + +## 4. Conventions de Code + +### Principes F.I.R.S.T. +Chaque test rédigé dans ce projet doit obligatoirement respecter les principes **F.I.R.S.T.** : + +- **Fast** (Rapide) : Les tests (en particulier unitaires) doivent s'exécuter en quelques millisecondes pour un feedback immédiat. +- **Isolated / Independent** (Isolé) : Les tests ne doivent jamais dépendre les uns des autres ni de l'ordre d'exécution. Chaque test initialise son propre état et le nettoie. +- **Repeatable** (Répétable) : Le test produit exactement le même résultat dans tous les environnements (machine locale, CI GitLab, conteneur Docker). +- **Self-validating** (Auto-validant) : Le test passe ou échoue de façon binaire (`OK` / `FAIL`), sans nécessiter d'analyse manuelle des logs. +- **Timely** (Opportun) : Les tests sont écrits au bon moment (en TDD ou simultanément avec le code de production). + +### Pattern GWT (Given - When - Then) +Tous les tests doivent utiliser des blocs de commentaires explicites `// GIVEN`, `// WHEN`, `// THEN` et déclarer un namespace sous `Tests\...` : + +```php +it('validates an employee id', function (): void { + // GIVEN + $id = '12345678'; + + // WHEN + $entityId = new ArcadiaEmployeeId($id); + + // THEN + expect($entityId->value)->toBe($id); +}); +```