Personne ne lance un projet en se disant « on ne mettra pas de tests ». Mais les contraintes s'accumulent : des deadlines serrées, un MVP à livrer, une équipe réduite, un framework mal maîtrisé. Et un jour, on se retrouve avec une application en production, des centaines de fichiers, zéro test automatisé — et la peur au ventre à chaque mise en production.
C'est une situation courante. Et contrairement à ce qu'on pourrait croire, ce n'est pas une impasse. Il existe des stratégies éprouvées pour introduire des tests automatisés sur un projet existant, sans tout réécrire et sans bloquer les développements en cours.
Pourquoi tester un legacy est plus urgent qu'un projet neuf
Sur un projet neuf, le code est frais, l'architecture est connue, les décisions techniques sont documentées. L'équipe sait ce que fait chaque module parce qu'elle vient de l'écrire. Les tests sont utiles, mais le risque de régression est faible.
Sur un projet legacy, c'est l'inverse. Le code a été écrit par des développeurs qui ne sont plus là. Certains modules n'ont pas été touchés depuis des années. D'autres ont été modifiés des dizaines de fois sans que personne ne comprenne l'ensemble des effets de bord.
Dans ce contexte, chaque changement est un risque. Modifier une requête SQL, refactorer un service, mettre à jour une dépendance — tout peut casser quelque chose d'inattendu. Et sans tests, ces régressions sont invisibles jusqu'à ce qu'un utilisateur les remonte en production.
Le paradoxe est cruel : c'est précisément là où il n'y a pas de tests qu'on en a le plus besoin. Et c'est précisément là où le code est le moins testable qu'il faut trouver un moyen de le tester.
La peur du refactoring
Sans filet de sécurité, les équipes développent un réflexe naturel : ne toucher à rien. On contourne les problèmes plutôt que de les résoudre. On duplique du code plutôt que d'extraire une abstraction. On ajoute des conditions plutôt que de simplifier la logique.
Ce comportement est rationnel — mais il accélère la dégradation du code. C'est un cercle vicieux : moins on teste, moins on refactore ; moins on refactore, plus le code devient difficile à tester. Briser ce cercle est la première étape pour reprendre le contrôle d'un projet legacy.
Les tests de caractérisation : documenter avant de changer
Michael Feathers, dans Working Effectively with Legacy Code, définit le code legacy comme « du code sans tests ». Pas du vieux code. Pas du code mal écrit. Du code dont on ne peut pas vérifier le comportement de manière automatisée.
Sa première recommandation est contre-intuitive : avant de corriger quoi que ce soit, écrire des tests qui capturent le comportement actuel. Même si ce comportement contient des bugs. Même si la logique semble incorrecte.
Le principe
Un test de caractérisation ne vérifie pas que le code fait ce qu'il devrait. Il vérifie que le code fait ce qu'il fait. C'est une photo instantanée du comportement réel.
La méthode est simple :
- Appeler la méthode ou le endpoint avec des données réelles.
- Observer la sortie.
- Écrire une assertion qui valide cette sortie exacte.
Si le test passe, vous avez documenté un comportement. Si vous modifiez le code et que le test échoue, vous savez exactement ce qui a changé — et vous pouvez décider si ce changement est intentionnel ou non.
Le golden master testing
Une variante puissante des tests de caractérisation est le golden master testing (aussi appelé approval testing). Le principe : capturer la sortie complète d'une opération — une réponse HTTP, un rendu HTML, un export CSV — et la stocker comme référence.
À chaque exécution, le test compare la sortie actuelle au fichier de référence. Toute différence est signalée. Si le changement est voulu, on met à jour le golden master. Sinon, on a détecté une régression.
C'est une technique particulièrement efficace sur les projets legacy où la logique est trop complexe pour être testée unitairement : on teste la sortie globale sans avoir besoin de comprendre chaque ligne de code.
Rendre le code testable sans le réécrire
Le principal obstacle aux tests sur un projet legacy n'est pas le manque de temps. C'est que le code n'est pas structurellement testable. Des dépendances codées en dur, des méthodes statiques partout, des classes de 2 000 lignes, des appels directs à la base de données dans les contrôleurs — le code résiste aux tests.
La bonne nouvelle : il n'est pas nécessaire de tout refactorer pour rendre le code testable. Il suffit de créer des coutures.
Le concept de coutures (seams)
Michael Feathers définit une couture comme un point du code où l'on peut changer le comportement sans modifier le code lui-même. C'est un endroit où l'on peut « brancher » un test en substituant une dépendance, en interceptant un appel ou en injectant un double de test.
En PHP, les coutures les plus courantes sont :
- L'injection de dépendance — passer un service en paramètre au lieu de l'instancier dans la méthode.
- Les interfaces — typer sur un contrat plutôt que sur une implémentation.
- L'héritage — redéfinir une méthode dans une sous-classe de test.
Extract and override
C'est la technique la plus rapide pour rendre un morceau de code testable sans le restructurer en profondeur. Le principe :
- Identifier la dépendance qui bloque le test (un appel HTTP, une requête SQL, un accès fichier).
-
Extraire cet appel dans une méthode
protecteddédiée. - Dans le test, créer une sous-classe qui surcharge cette méthode pour retourner une valeur contrôlée.
Ce n'est pas élégant. Ce n'est pas l'architecture cible. Mais ça permet d'écrire un premier test en vingt minutes sur du code qui semblait intestable. Et un test imparfait vaut infiniment mieux que pas de test du tout.
Wrap and delegate
Quand une classe fait trop de choses et qu'on ne peut pas la modifier (dépendance externe, classe générée, code critique en production), on peut la wrapper : créer une nouvelle classe qui délègue au code existant, mais expose une interface testable.
Le wrapper ne change rien au comportement. Il ajoute simplement un point d'injection qui permet de substituer la dépendance dans les tests. C'est une technique classique pour isoler les appels à des APIs tierces ou à des composants système.
L'injection de dépendance minimale
Sur un projet legacy, passer à un container d'injection de dépendance complet peut être un chantier énorme. Mais on n'en a pas besoin pour commencer à tester.
Il suffit souvent d'appliquer une règle simple : toute dépendance externe doit être passée en paramètre du constructeur. Pas besoin d'interface. Pas besoin de container. Juste un paramètre qu'on peut remplacer par un mock dans le test.
Cette approche incrémentale transforme progressivement le code vers une architecture plus testable, sans jamais imposer un arrêt complet des développements.
La stratégie par couche
Une erreur fréquente est de vouloir commencer par des tests unitaires. C'est l'approche naturelle — tester les petites briques en isolation — mais sur un projet legacy, c'est souvent la plus difficile. Le code n'est pas découpé en unités testables. Les dépendances sont entrelacées. L'effort pour isoler une classe peut être disproportionné par rapport à la valeur du test.
Une stratégie plus efficace consiste à commencer par le haut et descendre progressivement.
Tests E2E d'abord : le filet de sécurité large
Les tests end-to-end (E2E) vérifient le comportement de l'application du point de vue de l'utilisateur. Ils traversent toute la pile : contrôleur, service, base de données, rendu.
Leur avantage sur un legacy : ils ne nécessitent aucune modification du code.
On teste l'application telle qu'elle est, via son interface HTTP ou son interface graphique.
Avec un outil comme Playwright ou Codeception,
on peut couvrir les parcours critiques en quelques jours.
Les tests E2E sont lents et fragiles, c'est vrai. Mais sur un projet sans aucun test, ils offrent un ratio effort/sécurité imbattable. Dix tests E2E bien ciblés protègent mieux que cent tests unitaires sur du code non critique.
Tests d'intégration sur les modules critiques
Une fois le filet de sécurité E2E en place, on peut descendre d'un cran et cibler les modules qui concentrent la logique métier. Les tests d'intégration vérifient qu'un module fonctionne correctement avec ses dépendances réelles (base de données, système de fichiers, APIs).
Sur un projet Symfony, cela signifie typiquement :
-
Tester les endpoints API avec le
WebTestCasede Symfony. - Vérifier les requêtes complexes avec une base de test dédiée.
- Valider les workflows métier de bout en bout dans le container de services.
Tests unitaires sur la logique métier
Les tests unitaires viennent en dernier — mais ils sont les plus précieux à long terme. Rapides, fiables, précis, ils documentent le comportement attendu de chaque règle métier.
Pour qu'ils soient possibles, il faut que le code ait été rendu testable grâce aux techniques décrites plus haut (coutures, extract and override, injection). C'est pourquoi cette couche arrive en dernier : elle bénéficie du travail de refactoring progressif réalisé lors de l'ajout des tests d'intégration.
Prioriser : la matrice risque x fréquence de changement
On ne peut pas tout tester d'un coup. Sur un projet legacy de taille significative, atteindre une couverture de 80 % peut prendre des mois. Il faut donc choisir où investir en premier.
La matrice risque x fréquence de changement est un outil simple pour guider cette décision :
- Risque élevé + changements fréquents — priorité maximale. C'est le code critique qui bouge souvent : paiement, authentification, calculs métier. Chaque modification sans test est un incident potentiel.
- Risque élevé + changements rares — à couvrir par des tests E2E. Le code est critique mais stable. Un filet de sécurité large suffit.
- Risque faible + changements fréquents — tests d'intégration. Le code n'est pas critique mais il évolue souvent. Des tests d'intégration évitent les régressions répétées.
- Risque faible + changements rares — dernière priorité. C'est du code stable et non critique. Les tests viendront plus tard, ou jamais — et ce n'est pas un problème.
Cette matrice permet de concentrer les efforts là où ils ont le plus d'impact. Elle évite le piège classique de tester du code trivial pendant que les modules critiques restent sans protection.
Outillage PHP concret
L'écosystème PHP dispose aujourd'hui d'outils matures pour chaque niveau de la pyramide de tests. Voici les incontournables pour un projet legacy.
PHPUnit
Le standard de facto. PHPUnit couvre les tests unitaires
et les tests d'intégration. Sa configuration est simple,
sa documentation exhaustive, et son intégration avec les CI/CD
(GitHub Actions, GitLab CI) est native.
Sur un projet Symfony, le composant symfony/test-pack
fournit tout le nécessaire : WebTestCase pour les tests HTTP,
KernelTestCase pour les tests de services,
et les outils de debug associés.
Codeception
Pour les tests E2E et les tests d'acceptance,
Codeception offre une syntaxe expressive
et des modules préconfigurés pour les applications web.
Il se branche directement sur Symfony
et permet de tester les parcours utilisateur complets.
DAMA DoctrineTestBundle
L'isolation des tests est un problème récurrent sur les projets
qui utilisent une base de données.
DAMA DoctrineTestBundle résout ce problème élégamment :
chaque test s'exécute dans une transaction qui est annulée à la fin.
La base revient à son état initial après chaque test,
sans jamais écrire sur le disque.
Le gain est double : isolation parfaite et performance accrue (pas de purge ni de rechargement de fixtures entre chaque test).
PHPStan comme filet complémentaire
PHPStan n'est pas un outil de test au sens strict,
mais c'est un complément indispensable.
L'analyse statique détecte une catégorie de bugs
que les tests ne couvrent pas toujours :
types incorrects, variables indéfinies, appels de méthodes inexistantes,
violations de contrat.
Sur un projet legacy, activer PHPStan au niveau 1 et monter progressivement est une victoire rapide. Chaque niveau supplémentaire élimine une classe de bugs potentiels sans écrire une seule ligne de test.
Plan d'adoption en 4 sprints
Introduire les tests automatisés sur un projet legacy ne se fait pas en un jour. Mais il ne faut pas non plus en faire un projet à part. L'objectif est d'intégrer la pratique dans le flux de travail existant, sprint après sprint.
Sprint 1 : la fondation
L'objectif du premier sprint est de poser l'infrastructure.
-
Configurer
PHPUnitavec le bootstrap Symfony. - Mettre en place la CI pour exécuter les tests à chaque push.
- Écrire les 5 à 10 premiers tests E2E sur les parcours les plus critiques de l'application.
-
Activer
PHPStanau niveau 1 et corriger les erreurs détectées.
À la fin de ce sprint, l'équipe a un filet de sécurité minimal et une CI qui valide chaque changement. C'est le socle sur lequel tout le reste s'appuie.
Sprint 2 : couvrir le module critique
En utilisant la matrice risque x fréquence, identifier le module le plus critique de l'application. Typiquement : le paiement, la gestion des droits, le calcul de tarification, le workflow de commande.
- Écrire des tests de caractérisation sur ce module.
- Rendre le code testable avec les techniques de coutures (extract and override, injection minimale).
- Ajouter des tests d'intégration couvrant les cas nominaux et les cas d'erreur.
Sprint 3 : tests unitaires et logique métier
Maintenant que le module critique est couvert par des tests d'intégration, il est possible d'extraire la logique métier pure et de la tester unitairement.
- Identifier les règles métier enfouies dans les contrôleurs ou les services.
- Les extraire dans des classes dédiées, testables en isolation.
- Écrire des tests unitaires paramétrisés couvrant l'ensemble des cas.
-
Monter le niveau de
PHPStand'un cran.
Sprint 4 : mutation testing et consolidation
Le mutation testing est une technique avancée
qui vérifie la qualité des tests eux-mêmes.
Un outil comme Infection modifie le code source
(remplace un > par un >=, supprime une condition,
inverse un booléen) et vérifie que les tests détectent le changement.
-
Installer
Infectionet l'exécuter sur le module critique. - Identifier les mutations survivantes (= trous dans la couverture).
- Compléter les tests pour éliminer les survivants.
- Définir une politique : tout nouveau code doit être livré avec ses tests.
À la fin de ces quatre sprints, l'équipe a transformé sa posture. Le projet n'est plus un legacy sans tests — c'est un projet qui a des tests et une stratégie pour en ajouter. La différence est fondamentale.
Les erreurs à éviter
L'introduction de tests sur un legacy peut échouer si l'approche est mal calibrée. Voici les pièges les plus courants.
Viser une couverture de 100 %
C'est un objectif contre-productif. La couverture de code est un indicateur, pas un objectif. Un projet avec 60 % de couverture sur le code critique est bien mieux protégé qu'un projet avec 90 % de couverture concentrée sur des getters et des setters.
Écrire des tests fragiles
Un test qui casse à chaque modification de l'interface graphique ou à chaque changement de libellé n'est pas un filet de sécurité — c'est un frein. Les tests doivent vérifier le comportement, pas les détails d'implémentation.
Reporter les tests à « quand on aura le temps »
Ce moment n'arrivera jamais. Les tests doivent être intégrés dans le flux de développement courant, pas traités comme un chantier à part. La règle la plus efficace : tout nouveau code et toute correction de bug s'accompagnent d'un test.
Reprendre le contrôle
Mettre en place des tests automatisés sur un projet legacy n'est pas un luxe réservé aux grandes équipes. C'est un investissement qui se rentabilise en quelques semaines : moins de régressions, plus de confiance dans les mises en production, capacité retrouvée à refactorer et à faire évoluer le produit.
La clé est de ne pas chercher la perfection. Commencer petit, cibler les zones critiques, automatiser progressivement. Chaque test ajouté réduit le risque. Chaque refactoring sécurisé par un test améliore la qualité du code pour la suite.
Chez x10, j'accompagne régulièrement des équipes dans cette démarche. Mon audit technique permet d'identifier les zones critiques et de définir une stratégie de test adaptée. Et mon service de maintenance applicative inclut la mise en place progressive de tests automatisés pour sécuriser les évolutions futures. Quand le projet arrive d'une agence ou d'un freelance qui n'est plus là, la reprise d'application web commence par ce même filet de tests avant toute modification. Si votre projet legacy vous inquiète, parlons-en.