Jérémy Munsch
0d2b0124ee
docs(architecture): add request lifecycle documentation for Arcadia API docs(architecture): add execution, transactions, and domain events documentation for Arcadia API docs(architecture): add guide for creating a new use case in Arcadia API docs(exceptions): summarize exception handling and HTTP status codes in Arcadia API docs(tests): outline testing strategy and conventions for Arcadia API style(openapi): correct description formatting in OpenAPI documentation chore: remove outdated exceptions documentation test: remove obsolete tests documentation
120 lines
4.9 KiB
Markdown
120 lines
4.9 KiB
Markdown
# Conventions de Tests - Arcadia API
|
|
|
|
Ce document récapitule la stratégie, l'organisation et les conventions strictes applicables à la suite de tests dans **Arcadia API**.
|
|
|
|
---
|
|
|
|
## 🚀 1. Commandes
|
|
|
|
```bash
|
|
# Exécuter l'ensemble de la suite de tests (Pest 4)
|
|
composer test
|
|
|
|
# Exécuter les tests avec couverture de code (seuil minimal 85%)
|
|
composer test:coverage
|
|
|
|
# Exécuter uniquement les tests d'architecture
|
|
vendor/bin/pest tests/Architecture
|
|
```
|
|
|
|
---
|
|
|
|
## 🏔️ 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
|
|
/ \- Exécuteur transactionnel & Dispatcher d'événements
|
|
/--------------------------\
|
|
/ \ 3. UNIT TESTS (Domaine & Use Cases)
|
|
/ \------------------------------------
|
|
/ \- Entités DDD, Value Objects, règles métier
|
|
/ \- Use Cases (avec InMemory Directories & Mocks)
|
|
/____________________________________\- Pure PHP (sans conteneur Laravel, instantané)
|
|
```
|
|
|
|
---
|
|
|
|
## 📁 3. Structure des Dossiers
|
|
|
|
L'arborescence `tests/` reproduit en miroir la structure de `src/` :
|
|
|
|
- `tests/Architecture/` : Tests de conformité 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 (Eloquent, événements, base SQLite de test).
|
|
- `tests/Feature/` : Tests de bout en bout des endpoints API et validation OpenAPI (`openapi.yaml`).
|
|
- **`tests/Support/`** : Utilitaires de test partagés (**Test Data Builders & Object Mothers**).
|
|
|
|
---
|
|
|
|
## 💎 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 unitaires doivent s'exécuter en quelques millisecondes.
|
|
- **Isolated / Independent** (Isolé) : Les tests ne doivent jamais dépendre les uns des autres ni de l'ordre d'exécution.
|
|
- **Repeatable** (Répétable) : Le test produit le même résultat sur toutes les machines et en CI.
|
|
- **Self-validating** (Auto-validant) : Le résultat est binaire (`OK` / `FAIL`), sans vérification manuelle.
|
|
- **Timely** (Opportun) : Les tests sont écrits au bon moment (en TDD ou simultanément avec le code).
|
|
|
|
### Déclaration `covers()` et Structure GWT
|
|
Tous les tests unitaires et d'intégration doivent obligatoirement déclarer la classe ciblée via `covers(NomDeLaClasse::class);` et structurer leur logique avec les blocs `// GIVEN`, `// WHEN`, `// THEN` :
|
|
|
|
```php
|
|
namespace Tests\Unit\Presentation\Api\V1\Presenters\Employees;
|
|
|
|
use Presentation\Api\V1\Presenters\Employees\EmployeeShowPresenter;
|
|
use Presentation\Api\V1\Presenters\Employees\EmployeeShowView;
|
|
use Tests\Support\Mothers\EmployeeMother;
|
|
|
|
covers(EmployeeShowPresenter::class, EmployeeShowView::class);
|
|
|
|
it('transforms Output into EmployeeShowView', function (): void {
|
|
// GIVEN
|
|
$employee = EmployeeMother::create('12345678', 'Dupont', 'Jean');
|
|
$output = new Output($employee);
|
|
$presenter = new EmployeeShowPresenter();
|
|
|
|
// WHEN
|
|
$view = $presenter->present($output);
|
|
|
|
// THEN
|
|
expect($view)->toBeInstanceOf(EmployeeShowView::class)
|
|
->and($view->employee)->toBe($employee);
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## 🏗️ 5. Test Data Builders & Object Mothers (`tests/Support/`)
|
|
|
|
Pour éviter la fragilité des tests face aux modifications de constructeurs complexes du Domaine (ex: `IncoComposition` et ses 16 Value Objects), **utilisez toujours les Test Data Builders ou Object Mothers** :
|
|
|
|
### Object Mothers (`tests/Support/Mothers/`)
|
|
Fournissent des instances prêtes à l'emploi et nommées pour les scénarios standards :
|
|
```php
|
|
// Instancie un objet valide avec des valeurs par défaut réalistes
|
|
$composition = IncoCompositionMother::create();
|
|
$incoSheet = IncoSheetMother::pouletRoti();
|
|
$employee = EmployeeMother::create('12345678');
|
|
```
|
|
|
|
### Test Data Builders (`tests/Support/Builders/`)
|
|
Permettent de surcharger précisément les propriétés pertinentes pour le test sans se soucier du reste du graphe :
|
|
```php
|
|
$composition = IncoCompositionTestBuilder::create()
|
|
->withId('67890')
|
|
->withNutriScore('A')
|
|
->build();
|
|
```
|