ldc-arcadia-api/TEST.md

# 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).

### Declaration covers() et Pattern GWT
Tous les tests unitaires (`tests/Unit`) et d'intégration (`tests/Integration`) doivent obligatoirement déclarer la classe ciblée via `covers(NomDeLaClasse::class);`, utiliser des blocs de commentaires explicites `// GIVEN`, `// WHEN`, `// THEN` et appartenir à un namespace `Tests\...` (vérifié par test d'architecture) :

```php
namespace Tests\Unit\Domain\Models\ValueObjects;

use Domain\Models\ValueObjects\Entities\ArcadiaEmployeeId;

covers(ArcadiaEmployeeId::class);

it('validates an employee id', function (): void {
    // GIVEN
    $id = '12345678';

    // WHEN
    $entityId = new ArcadiaEmployeeId($id);

    // THEN
    expect($entityId->value)->toBe($id);
});
```