docs(README): update table of contents and add testing section
docs(TEST): add testing strategy and organization document
This commit is contained in:
parent
84e59314a0
commit
8c0d139ad3
GPG key ID:
D7EFE2F5CB6CC0E4
2 changed files with 99 additions and 0 deletions
13
README.md
13
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
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
86
TEST.md
Normal file
86
TEST.md
Normal file
|
|
@ -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);
|
||||
});
|
||||
```
|
||||
Loading…
Add table
Reference in a new issue