Stratégie de tests par couche

Pas de test = pas de merge. C'est la règle dure du projet (.claude/rules/global.md) : tout nouveau code métier vient avec son test. La pyramide PHPUnit Kohinos suit l'ordre canonique Unit > Integration > Functional, jamais l'inverse : on écrit beaucoup de tests rapides à la base, et très peu de tests de bout en bout au sommet. La cible n'est pas la couverture absolue : c'est l'isolation des invariants financiers et la garantie qu'une régression sur la monnaie locale est détectée par un test avant de toucher la prod.

La pyramide

flowchart TB
  F["Functional (5–10 %)
WebTestCase · KernelBrowser
fixtures réduites · 1 createClient()"]
  I["Integration (20–25 %)
Container Symfony · SQLite in-memory
entités réelles · UnitOfWork réel"]
  U["Unit (65–75 %)
Pure PHP · tout mocké
pas de container · < 10 ms / test"]
  F --> I --> U
    

Couches en pratique

Les testsuites définies dans phpunit.xml.dist permettent de cibler rapidement : ssa, sepa, mlc, unit, functional, command, profile. Préférer un filtre par testsuite à une exécution complète.

Deux outils dédiés aux admins Sonata : tests/Functional/Admin/SonataAdminCoverageTest.php (filet global — toutes les routes list/create des ~46 admins du pool doivent répondre 200 en super_admin, ~90 routes vérifiées) et tests/Admin/AbstractAdminTestCase.php (classe de base des tests fins par admin : adminServiceId() + helper actAs(roles)). Détails : Sonata Admin.

Setup de la base de test

Tests sur SQLite in-memory en CI et par défaut. Le fichier config/packages/test/doctrine.yaml surcharge la configuration et désactive logging / profiling. La DATABASE_URL de test vient de .env.test.local (non commité).

# Setup rapide (recommandé)
./scripts/setup-test-environment.sh

# Profils disponibles
./scripts/setup-test-environment.sh full        # MLC + SSA + SEPA (défaut)
./scripts/setup-test-environment.sh mlc_only    # MLC sans SSA
./scripts/setup-test-environment.sh ssa_only    # SSA isolé
./scripts/setup-test-environment.sh minimal     # MLC sans SSA ni SEPA
./scripts/setup-test-environment.sh sepa_disabled

# Setup manuel
php bin/console doctrine:database:create  --env=test
php bin/console doctrine:migrations:migrate --env=test --no-interaction
php bin/console app:init-test-database     --env=test --purge
php bin/console cache:clear                --env=test

# Réinitialiser
php bin/console doctrine:database:drop   --env=test --force
php bin/console doctrine:database:create --env=test
php bin/console doctrine:migrations:migrate --env=test --no-interaction

Le bootstrap tests/bootstrap.php émet un avertissement si la base utilisée ne contient pas _test dans son nom — garde-fou contre une mauvaise DATABASE_URL.

Conventions Kohinos

Nommage

• Style préféré : it_refuses_transfer_when_balance_is_insufficient — anglais lisible, descriptif, lu par #[TestDox].
• Style legacy accepté : test{Action}{ExpectedResult}[Context], par ex. testProcessRefusesPurchaseWhenBalanceInsufficient.
• Toujours préciser la condition d'échec : pas de testHappyPath().

Attributs PHPUnit 10.5

<?php

declare(strict_types=1);

namespace App\Tests\Service\Sepa;

use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\Attributes\TestDox;
use PHPUnit\Framework\TestCase;

final class SepaMandateValidatorTest extends TestCase
{
    #[Test]
    #[TestDox('rejette un IBAN dont la clé de contrôle est invalide')]
    public function rejects_iban_with_invalid_checksum(): void
    {
        // ...
    }

    #[Test]
    #[DataProvider('provideAmountsThatMustRoundToTwoDecimals')]
    public function rounds_amount_to_two_decimals(string $input, string $expected): void
    {
        // ...
    }

    public static function provideAmountsThatMustRoundToTwoDecimals(): iterable
    {
        yield 'half-up' => ['12.345', '12.35'];
        yield 'half-down' => ['12.344', '12.34'];
    }
}

declare(strict_types=1); est obligatoire en tête de chaque fichier de test, comme pour src/. Préférer final class sur les classes de test (PHPUnit le tolère, et empêche un héritage accidentel).

DataProviders pour les propriétés

Trois propriétés se prêtent particulièrement bien au data-provider :

• Conservation : sumBefore === sumAfter pour tout couple émetteur/récepteur.
• Idempotence : rejouer N fois la même opération ⇒ effet d'une seule.
• Non-négativité : aucun solde < découvertAutorisé.

Voir invariants financiers pour les property-based tests couvrant ces propriétés sur un échantillon généré.

Mocking — qui mocker, qui garder réel

Tests financiers spécifiques

// Exemple — conservation de masse sur un transfert
#[Test]
public function transfer_preserves_total_mass(): void
{
    $alice = $this->makeAccount('100.00');
    $bob   = $this->makeAccount('50.00');

    $totalBefore = bcadd($alice->getBalance(), $bob->getBalance(), 2);

    $this->transferService->transfer($alice, $bob, '12.34');

    $totalAfter = bcadd($alice->getBalance(), $bob->getBalance(), 2);

    self::assertSame($totalBefore, $totalAfter);
}

Tests de webhook

Les webhooks HelloAsso et PayZen sont la principale surface d'entrée non maîtrisée par Kohinos : il faut tester signature, idempotence, et rejeu :

// tests/Service/HelloAssoPaymentServiceTest.php (structure type)
#[Test]
public function processing_same_helloassoid_twice_creates_one_flux_only(): void
{
    $payload = $this->loadFixture('helloasso/payment_success.json');
    $signature = $this->sign($payload, $this->sharedSecret);

    $this->service->handle($payload, $signature);
    $this->service->handle($payload, $signature); // rejeu

    $fluxCount = $this->em->getRepository(Flux::class)
        ->countByHelloAssoId($payload['data']['id']);

    self::assertSame(1, $fluxCount, 'webhook must be idempotent on helloassoid');
}

Pour la signature, mocker HelloAssoSignatureVerifier en Unit, garder réel en Integration. Voir webhooks & idempotence.

Outils qualité

Patron pour un nouveau test

<?php

declare(strict_types=1);

namespace App\Tests\Service\Sepa;

use App\Service\Sepa\SepaCancellationService;
use Doctrine\ORM\EntityManagerInterface;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\Attributes\TestDox;
use PHPUnit\Framework\TestCase;
use Symfony\Component\Mailer\MailerInterface;

final class SepaCancellationServiceTest extends TestCase
{
    private EntityManagerInterface $em;
    private MailerInterface $mailer;
    private SepaCancellationService $service;

    protected function setUp(): void
    {
        $this->em     = $this->createMock(EntityManagerInterface::class);
        $this->mailer = $this->createMock(MailerInterface::class);
        $this->service = new SepaCancellationService($this->em, $this->mailer);
    }

    #[Test]
    #[TestDox('annule atomiquement toutes les requêtes récurrentes liées au mandat')]
    public function cancels_all_recurring_requests_linked_to_mandate(): void
    {
        // arrange — un mandat avec 3 requêtes récurrentes
        // act     — $this->service->cancel($mandate)
        // assert  — wrapInTransaction appelé 1x, toutes requêtes archivées
    }
}

Règles dures

Tests E2E (Playwright)

Les tests E2E tapent un vrai serveur HTTP (≠ PHPUnit in-process). Ils tournent dans un environnement dédié e2e avec une base SQLite fichier isolée (var/kohinos_test_e2e.sqlite) et un jeu de fixtures minimal et média-free (fixtures_e2e/). Doc complète : docs/testing/E2E_ENVIRONMENT.md.

# 1. Seeder la base e2e (idempotent, ~96 Mo de pic mémoire)
bash bin/e2e/seed.sh

# 2. Démarrer le serveur e2e (port 8044, base SQLite dédiée)
bash bin/e2e/serve.sh

# 3. Lancer les tests (toutes les suites)
APP_URL=http://127.0.0.1:8044 npx playwright test \
  --project=chromium-e2e --project=a11y-e2e --project=mobile-e2e --project=tablet-e2e

Un front-controller public/e2e-router.php force APP_ENV/ DATABASE_URL/SECURE_SCHEME à chaque requête : le SAPI cli-server du serveur PHP intégré n'expose pas de façon fiable l'environnement de l'OS à l'application, sans quoi l'app retombe en dev (mauvaise base + redirection HTTPS canonique).

56 tests verts, 0 échec, 0 fixme : authentification 8 rôles, smoke, role-smoke (anti-500 par rôle), les 8 journeys J1–J8, webhooks (retours paiement), visual (capture artefact 9 pages), a11y (axe-core WCAG, 0 violation critical) et responsive (mobile/tablet, anti-overflow). Bout-en-bout : J2 (paiement, conservation prouvée) et J3 (création réelle de mandat SEPA pending + UMR).

J1/J5/J7/J8 vérifient l'accessibilité page/formulaire : leur flux complet a un blocage d'infrastructure (J1 gateway de paiement, J5 commande CLI kohinos:ssa:execute, J7 form Sonata financier à dropdowns dépendants, J8 API BOffice externe) et reste couvert par les golden paths PHPUnit. Mailpit (faux SMTP local) est installé et câblé via MAILER_DSN. Détails et findings : docs/testing/E2E_ENVIRONMENT.md.

Pour aller plus loin