# 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();
```