Aller au contenu

Exécuter les tests

Vous êtes développeur·se sur Kirexo et vous voulez lancer la suite de tests pour vérifier que vos modifications n'ont rien cassé.

Prérequis

  • La stack Docker est démarrée (castor docker:up).
  • Les dépendances sont installées (castor install).

Préparation automatique de la BDD

À chaque démarrage de PHPUnit — quel que soit le chemin d'exécution (castor test:unit, castor test:e2e, castor test:coverage, ou même un vendor/bin/phpunit direct depuis le conteneur) — tests/bootstrap.php enchaîne trois commandes Doctrine avant que le premier test ne tourne :

  1. doctrine:database:create --if-not-exists — crée la base app_test si elle n'existe pas (idempotent, ne touche à rien sinon).
  2. doctrine:migrations:migrate --allow-no-migration — applique les migrations en attente, tolère l'absence de migration sur une base neuve.
  3. doctrine:fixtures:load — purge la base puis recharge toutes les fixtures auto-tagguées doctrine.fixture.orm (les classes de src/DataFixtures/ étendant Doctrine\Bundle\FixturesBundle\Fixture sont enregistrées automatiquement comme services).

Conséquence pratique : vous n'avez plus à charger les fixtures à la main avant de lancer les tests. Le bootstrap garantit un état déterministe à chaque session PHPUnit.

Articulation avec DAMADoctrineTestBundle

DAMADoctrineTestBundle enveloppe chaque test dans une transaction roll-backée à la fin du test. Les fixtures chargées par le bootstrap sont committées hors transaction (avant que la machinerie de PHPUnit ne démarre), donc elles restent visibles pour tous les tests de la session. Toute mutation faite par un test est annulée avant le suivant — pas besoin de recharger les fixtures entre deux tests.

Et castor fixtures:load alors ?

La cible castor fixtures:load reste utile en dehors du contexte des tests : rejouer manuellement les fixtures sur la base de dev (app, pas app_test) pour repartir d'un état propre lors d'une exploration locale. Pas besoin de l'appeler avant castor test:unit ni castor test:e2e.

Tests unitaires et d'intégration

castor test:unit

Cette cible lance PHPUnit sur les suites unit et integration. Elle s'exécute dans le conteneur php — vous n'avez rien à installer côté hôte. La BDD app_test est préparée automatiquement (voir Préparation automatique de la BDD).

Pour filtrer sur un test précis, passez un --filter :

castor test:unit --filter=AnalyzeArticleHandlerTest

Tests E2E

castor test:e2e

Les tests E2E utilisent Panther, qui pilote un vrai navigateur headless. Ils sont nettement plus lents que les tests unitaires — lancez-les après que le reste de la suite est passée.

Ce que testent les tests E2E

Panther ne teste que le rendu et la navigation : est-ce que la page se charge, est-ce que le formulaire se soumet, est-ce que le Live Component se met bien à jour. La logique métier est couverte par les tests unitaires et d'intégration — dupliquer cette logique dans des tests navigateur serait lent et fragile.

Tests bats des libs shell

castor test:bash
castor test:bash --filter <motif>     # restreint à un test ou un pattern

La cible exécute bats --recursive tests/Bash/ sur les fonctions pures des libs shell du projet (supervisor, worktree, proxy, allowlist, hooks Claude, scripts de skills…). Aucun privilège n'est requis : ces libs ne font que du texte. Si bats manque dans le conteneur, la cible le dit et donne le remède plutôt que d'échouer sur un command not found.

Tout enchaîner

castor test        # test:unit → test:bash → test:e2e
castor all         # la checklist complète avant clôture

castor all fait précéder ces trois suites de la validation Composer et des vérifications de qualité — composer:validate, cs:fix, phpstan, lint, ts:check, doctrine:schema:validate — soit neuf étapes en tout. C'est la séquence que la CI GitLab rejoue avant merge.

Couverture

Pour un rapport de couverture textuel :

castor test:coverage

Par défaut, la cible couvre les suites unit + integration. Ajoutez --with-e2e pour inclure la suite Panther dans la mesure, ou --html pour générer un rapport HTML dans var/coverage/ (cf. castor test:coverage).

La cible de couverture attendue est de 100 % sur les controllers, handlers, services, repositories, voters et composants Twig/Live (voir CLAUDE.md).

Un seul gate de couverture en CI : les lignes

En local, castor test:coverage ne fait qu'afficher la couverture. C'est la pipeline GitLab qui bloque, sur un seul seuil : le job test:unit mesure les suites unit + integration et fait échouer la pipeline si la ligne Lines: du résumé PHPUnit n'est pas exactement à 100.00 (.gitlab/ci/quality.yml).

Les branches ne sont plus mesurées dans ce job : pathCoverage a été retiré du run global (phpunit.dist.xml), parce que l'instrumentation lignes + branches + chemins sur tout src/ sature la mémoire dès qu'un test charge le kernel Symfony UX. Elles se vérifient en local, fichier par fichier (voir ci-dessous).

Détail du job : Pipeline GitLab CI — Tests et gate de couverture.

Conséquence du choix de mesurer la couverture sur unit + integration uniquement : un controller invokable trivial couvert seulement par son E2E (cas autorisé par CLAUDE.md) doit aussi être couvert en integration (un test WebTestCase), sinon il fait tomber test:unit sous 100 %.

Couverture de branches : en local, fichier par fichier

En fin de développement, sur chaque fichier de production modifié ou créé :

castor test:path-coverage --filter AnalyzeArticleHandlerTest src/MessageHandler/AnalyzeArticleHandler.php

Le --filter est indispensable en pratique, et la cible vous avertit quand il manque : sans lui, le --path-coverage s'applique à toute la suite et sature la mémoire. Lisez la colonne Branches (jamais « Paths », qui compte les combinaisons de chemins) ; le seuil attendu est ≥ 80 %. Il n'est pas à 100 % parce que certaines branches sont structurellement inatteignables — l'UnhandledMatchError d'un match exhaustif sur enum, par exemple.

La règle complète (seuils, périmètre, ce qui bloque une clôture) vit dans .claude/skills/_shared/tests-couverture-quota.md.

Ne pas désactiver native_function_invocation dans PHP-CS-Fixer

Depuis PHP 8.4, chaque appel à une fonction interne (trim, preg_match, implode, str_starts_with…) émis dans un namespace non global compile en opcode JMP_FRAMELESS avec un fast path (la fonction interne attendue) et un slow path (une fonction de même nom redéfinie dans le namespace courant). Le slow path est compté comme une branche non couverte — sans intervention, le seuil de branches devient inatteignable dès qu'un fichier appelle quelques fonctions internes.

La parade est portée par PHP-CS-Fixer dans .php-cs-fixer.dist.php :

'native_function_invocation' => ['include' => ['@internal']],

Le preset @internal couvre toutes les fonctions internes (≈ 1 700, contre ≈ 40 pour @compiler_optimized). À chaque castor cs:fix, les appels sont préfixés par \ (\trim(...), \preg_match(...)…) ; le compilateur PHP les résout alors statiquement en FRAMELESS_ICALL direct et le slow path disparaît du bytecode — donc du rapport branches.

À retenir :

  • Vous n'écrivez jamais \trim() à la main. C'est cs-fixer qui s'en charge au prochain castor cs:fix.
  • Ne pas retirer la règle native_function_invocation du fichier de config : la couverture de branches tomberait avec.
  • Si vous voyez la couverture branches chuter brutalement après un refactor, lancez castor cs:fix avant d'investiguer plus loin.

Organisation des tests

L'arborescence tests/ reflète celle de src/ pour les suites PHPUnit :

tests/
  Unit/        # Tests unitaires — symétrique de src/
  Integration/ # Tests d'intégration — flows multi-fichiers, base réelle
  E2E/         # Tests Panther — parcours navigateur uniquement
  Bash/        # Tests bats des libs shell d'infra/ et des hooks Claude

Un fichier src/MessageHandler/AnalyzeArticleHandler.php est testé par tests/Unit/MessageHandler/AnalyzeArticleHandlerTest.php. Cette symétrie rend la navigation triviale et permet de repérer instantanément un fichier non testé. Elle vaut aussi pour les plugins : src/Plugin/Web/src/MessageHandler/WebArticlePublishedHandler.php a son test en tests/Unit/Plugin/Web/MessageHandler/WebArticlePublishedHandlerTest.php.

tests/Bash/ échappe à cette symétrie : les tests bats y sont rangés par lib (supervisor/, worktree/, proxy/, allowlist/, dod/, skills-lot/…), et non par chemin de fichier.

Ce que tests/Bash/skills-lot/ couvre

Les scripts des skills de lot et de clôture (.claude/skills/{implementer-lot,cloturer-etape,_shared}/bin/) décident à la place du modèle : sur quelle branche il travaille, quels fichiers partent dans un commit, si une étape peut être clôturée. 88 cas y portent sur la résolution de la branche parente, la validation de la liste de fichiers de ship.sh, la garde de complétude de check-etape-complete.sh et add-lot.sh. Aucun ne crée de MR, ne pousse ni n'audite : le PATH de test ne contient que les binaires nécessaires pour atteindre la garde mesurée, plus des stubs, et le dépôt git manipulé est jetable. Les précautions à respecter pour ajouter un cas sont dans tests/Bash/skills-lot/README.md ; le quoi de chaque garde est en référence, Skill implementer-lot.

Ce que tests/Bash/dod/ couvre — et ce qu'il ne peut pas couvrir

Les sondes de Definition of Done (infra/dod/) pilotent Docker et détruisent des worktrees : rien de cela n'est exécutable dans le conteneur où tourne bats. Ces cas portent donc sur les gardes qui décident avant toute action (quels noms castor dod:clean accepte, quelle forme --wt-a refuse) et sur les fonctions pures de infra/dod/lib.sh. check.sh y est invoqué avec un PATH réduit à bash, dirname, git et sed : un test ne peut pas atteindre docker, même par accident. Le pourquoi de ce périmètre : Une preuve non versionnée n'est pas une preuve.

Voir aussi

  • Commandes Castor — inventaire complet des cibles disponibles.
  • Architecture — la séparation CQRS a un impact direct sur la manière d'organiser les tests.