ldc-arcadia-api/documentation/Tests.md

Tests — Arcadia API

Ce document récapitule la stratégie et l'organisation des tests dans Arcadia API.

Sommaire

• Tests — Arcadia API
  • Sommaire
  • 1. Commandes
  • 2. Pyramide de Tests
  • 3. Structure des Dossiers
  • 4. Conventions de Code
    • Principes F.I.R.S.T.
    • Pattern GWT (Given - When - Then)

---

1. Commandes

# 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 et de conformité des endpoints API :
  • tests/Feature/Api/V1/{Context}/ : Tests fonctionnels des endpoints HTTP et de leurs query parameters.
  • tests/Feature/OpenApi/V1/{Context}/ : Tests de conformité au contrat OpenAPI (openapi.yaml).

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) :

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);
});