Jérémy Munsch 0d2b0124ee docs(architecture): add global architecture documentation for Arcadia API

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

2026-08-21 10:41:07 +02:00

4.9 KiB

Raw Permalink Blame History

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

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

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 :

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

$composition = IncoCompositionTestBuilder::create()
    ->withId('67890')
    ->withNutriScore('A')
    ->build();

4.9 KiB Raw Permalink Blame History