TDD avec tests intégrés

Ce que nous attendons des tests dans une CI est qu'ils soient parfaitement reproductibles, extrêmement rapides, faciles à tourner n'importe où.

Ce que nous attendons des tests lorsque nous développons du nouveau code en TDD est que les tests soient représentatifs de la réalité, que la différence avec la production soit faible, que l'on puisse démarrer en TDD au plus vite (pour écrire le minimum de tests après-coup) et qu'on puisse appliquer le TDD sur une partie importante du code.

Ce sont des besoins très différents, qui de plus nous importe à des phases séparées! Pourtant nous nous efforçons de répondre aux deux besoins avec les mêmes tests en même temps. Mais qui a eu une idée pareille? 

Que se passerait-il si nous commencions les stories avec des tests intégrés et si on isolait uniquement "au besoin"? Si à la fin de la story on s'assurait d'avoir les tests maintenables et adaptés à tourner dans une CI personne ne saurait qu'on fait des tests sales entre temps. Peut-être qu'on en tirerait une grande valeur?

L'approche classique

Typiquement pour répondre aux besoins de maintenabilité des tests nous nous isolons des dépendances externes tels que apis externes, bases de données etc. Ce qui implique que nous introduisons une couche d'isolation de ces dépendances, en simulant ces dépendances avec des mocks ou des simulateurs fait main. Du côté framework qui nous appelle, on va plutôt ignorer le framework dans nos tests en appelant directement notre code.

Imaginons la situation où nous devons écrire une fonction lambda ou cloudfunction pour modifier une valeur persisté en bdd. Nous devons décrire la fonction, ses paramètres, les ressources auxquelles elle a droit, faire de la validation des droits utilisateur, extraire des données de la requête, récupérer une valeur en bdd, récupérer une autre valeur dans une api externe, sauver une nouvelle valeur en bdd et qq part dans tout ça faire un petit calcul. A quel moment faisons nous du TDD avec tests unitaires? 

Probablement assez tardivement, une fois que nous avons réussi à mettre en place tout le reste et ce uniquement sur la partie calcul - le moins risqué de tout. On comprend bien que l'apport du TDD dans l'ensemble de la story semble dérisoire! Certes au bout d'un moment la complexité grandit et les tests unitaires changent tout, mais le problème est qu'il faut attendre un certain temps et pendant ce temps les tests et le TDD semblent apporter peu, donc ne sont pas faits.

La bonne volonté de faire des tests de bonne qualité, notamment en termes d'isolation, nous contraint de ne les utiliser que pour une petite partie du problème, après avoir presque terminé la tâche. Pas étonnant qu'on commence pas avec les tests!

La bonne question à se poser serait plutôt; Comment puis-je faire pour que les tests me donnent un feedback de qualité le plus tôt possible? Quand je dis "feedback de qualité" je pense à rapide et proche de la réalité sur le code en construction.

Par exemple, il est tout à fait possible de lever temporairement les contraintes de besoins tel que la répétabilité, la rapidité et tout autre aspect de la maintenabilité. Des tests qui prennent 1 seconde à tourner, voire plus, ne poseront pas de problème pendant qq heures. Des tests qui ne tournent pas sur la machine de mes collègues ne poseront pas de problème tant que je ne les mets pas dans le pipeline. Même des tests que je suis le seul à comprendre (avec mon pair) suffisent amplement tant que personne d'autre ne travaille dessus. Je pourrais alors faire du TDD avec des tests très haut niveau en totale intégration avec toute dépendance externe....

TDD en totale intégration avec toute dépendance

Cette approche est le mieux illustré par le workflow d'une story lorsqu'il n'existe aucun code existant. Mon workflow dans ce cas est de commencer avec un test très haut niveau, au niveau de l'api, sans rien mocker, ni même des prestataires externes. En pur TDD je vais faire passer ce test en faisant du code sale, dans cet exemple en faisant tout le code dans mon contrôleur. Mon code ne sera pas très gros, car il n'aura pas de branches, pas de validation, pas de configurabilité, ce sera pour plus tard grâce à d'autres tests (justement TDD), ainsi j'aurai fait passer le test assez rapidement. Je passe ensuite à un deuxième test aussi haut niveau, je le fais passer rapidement, et ainsi de suite.

Au bout d'un moment, typiquement au bout de 3-5 tests la logique commence à se cristalliser. Le comportement d'un service aura été découvert, les interactions avec la BDD stabilisés. Il y aura aussi de la logique pure de transformation de données et validation. C'est un bon moment pour concevoir une interface mockable pour s'isoler de la dépendance externe, concevoir l'interface d'une classe repository, une classe de service et peut-être des value objects. Ces extractions rendent possible l'isolation des dépendances et je peux ainsi continuer avec d'une part des tests haut niveau mais cette fois-ci sans dépendances, soit des tests haut niveau de l'hexagone, et d'autre part des tests bas niveau de mes adapteurs (le code qui invoke des services externes) si j'ai besoin de les explorer davantage.

C'est à ce moment du workflow que les tests commencent à devenir maintenables. C'est donc qu'à partir d'un certain moment que je fais mes choix de design interne et ça c'est clé! Certes on peut faire ces choix au début, mais cela implique de prendre des décisions avec moins d'informations, donc plus souvent sous-optimales. Si on doit revenir sur un choix de design cela coûtera plus cher si des tests sont déjà écrits contre ces choix! Cerise sur le gâteau, ces tests ne pourront pas protéger le refactoring. Mon choix par défaut est donc de commencer avec des tests intégrés afin de retarder la prise de décisions, avoir le maximum de feedback proche de la réalité et assurer la refactorabiltié de l'ensemble le cas échéant. 

Mais là où je trouve l'isolation "d'office" néfaste c'est pour les débutants en TDD, soit presque la totalité des devs… Les inciter à résoudre les problèmes de maintenabilité des tests avant même de commencer à les écrire leur rend la tâche plus dure. Le tout pour un bénéfice discutable, ou inexistant, voire même négatif quand cela, comme souvent, résulte dans des tests pas écrits du tout! Pour apprendre à travailler avec des tests il faut déjà en faire. 

Conclusion

Ce n'est pas parce qu'on veut des tests maintenables qu'on dois s'infliger cette obligation dès le 1er test.

En particulier il peut y avoir un certain nombre d'avantages à faire autrement :

• Dans la phase TDD (construction) les tests totalement intégrés peuvent nous apporter plus que des tests isolés.
• En terme de fidélité avec la réalité
• En terme de couverture
• Il est plus facile de commencer en TDD avec des tests intégrés.
• Plus les tests sont haut niveau, plus ils permettent des refactorings

Pour être clair je ne transige pas sur les qualités des tests à la fin de la story. Simplement j'utilise souvent des tests intégrés au début et pendant une story. Je pense aussi que c'est plus facile d'en tirer un bénéfice dans la phase de construction, ce qui inciterait plus de gens à essayer le TDD sur du vrai code.

Surtout, n'hésite pas à essayer.

Notes de fin

En pratique je fais des variantes dans le workflow ci-dessus, plus classiques comme approche. Par exemple, pour intégrer un service externe on peut très bien directement explorer l'api avec des tests bas niveau. Un autre exemple c'est lorsque le code d'intégration avec une dépendance externe existe déjà j'utilise directement son simulateur, au lieu d'intégrer avec le service externe. 

Encore un autre exemple est lorsque la story ne concerne pas les dépendances alors évidemment on utilise pas de test intégré.

Configure XDebug for code coverage in PhpStorm

A frequent problem when running TDD or legacy testing workshops is to get code coverage for PHP to work within PhpStorm. In fact XDebug is needed and it can be a bit tricky to install on some configurations. This post shows how to make it work any time, by running it within a docker container.

PhpStorm has the ability to run the php executable, for testing or for debugging using a docker container. While that's easy and well documented we also need a docker image with xdebug installed and we also need to configure the code coverage to NOT try to code cover the whole "vendor" directory which would be slow to say the least. So let's dive into how it's done

Configure a php cli to run in docker

Open settings and click on the "three dots"

Click "+"

Choose "From docker, Vagrant, ..."

Enter the full image name. 

At this stage your tests should run, the debugger should work. You might have to configure the "Test Framework" in the settings, and in particular the autoloader to use. For instance 

Note for PHP > 7.3 : PhpStorm produced images up until PHP7.3. But if you need 7.4 or above you'll have to make your own. For instance here's the whole Dockerfile you need for 7.4

FROM php:7.4
RUN pecl install xdebug-3.1.0
RUN docker-php-ext-enable xdebug

Configure the code coverage to exclude vendor

It boils down to use the option of "whitelist" or the more recent "coverage" to tell phpunit which source code to instrument for code coverage.

While it should work to pass options to phpunit to ignore vendor, it seems that PhpStorm makes this impossible. I've never been able to configure this without an xml file. On the other hand with the xml file it's easy.

 

Add a section "filter" or "coverage" with your source code directory.

Now you're ready to run the tests with code coverage

On premature optimisation

Dev: this code is more optimal, i.e. better

Senior dev: most performance problems appear where we don't expect them, let's wait and measure

Senior dev: Besides most code optimizes one thing, it can be CPU-time, but also readability (i.e. developer time), but rarely more one thing. If we have to choose, which is the best optimisation in this case?

Dev: we need to optimise before it is too late

Senior dev: most perf problems I've had to deal with, were very simple to solve. Just limit the number of round-trips to the db, if not possible parallelize, if not possible maintain a read-model. Let's wait and measure.

Dev: but some problems require a completely different paradigm

Senior dev: True, and most often the business never scales that much. Let's wait (building a working system), validating that we actually have that problem! And read up on the CALM theorem, CRDT's*, CQRS etc

PS: Both devs are me. Just separated by two decades of experience 

* CRDT is a basically a data-structure that allows parallel writes

Hexagonal architecture vs Functional core / Imperative shell

There's been some comparison about theese two architectural styles recently. To me they address totally very different concerns and are by no means mutually exclusive. Let's review that visually.

Let's take the example of some user calling a rest-service with some request for modification. A typical application will have the workflow of 

• Validation 
• Load state from db 
• Compute new state
• Save state to db

Hexagonal architecture

I assume you have basic knowledge about this architecture. If not you might want to have a look at this. In this paradigm we'd distribute the steps of the given use case in the following way.

Inside the "hexagon" everything except what talks to the outside world

We have separated the blue parts from the yellow because those are the parts that talk to the outside world. The boundaries that we create by separating the repository from the rest are useful for testability (and a few other things that I won't go into in this post). We can test the whole logic by simply mocking the repository. So here the emphasis is on creating boundaries from the outside world. All the rest is considered inside the hexagon.

Functional core / imperative shell

In this paradigm we focus on what is pure and impure. A pure function is a function that needs nothing else than values as inputs and that does nothing else than returning a result. No side effects, no loading data from the file-system etc. A pure function always returns the same values given the same inputs. The properties of a pure function make them very nice to work with. For one thing they can be tested without any mocks, they don't surprise us, results can be cached(!) and so on. Because they have these nice properties we want to separate them from the rest, and possibly maximize the scope of them.

Let's look at the same application from the point of view of what is functional core and what is the imperative shell. 

The adapters and all the coordination logic is in the imperative shell. This shell delegates as much as possible to the functional core through calls to pure functions.

There is no change! The only difference is how we classify things. Admittedly this is because I already separated the pure parts from the rest. Note that the diagram is simplified in the sense that the validate and compute stages do not actually call the next stages. Both are pure functions that just return some value. 

Although in this case the architecture is both hexagonal and functional core / imperative shell, it is seldom the case. Often what we do in traditional applications is a lot of validation and computational logic in the middle of our service classes, just next to where we load and save state. Even worse we load state and save state in several steps with computational logic intermingled so there is very little to extract. 

Functional islands

What is called functional core is actually more like functional islands. It only makes sense if we can make them big enough so that at-least it makes sense to test them in isolation. That is, we tend to mould the architecture to increase the size of the functional islands. To get the most out of functional core we will tend to load everything beforehand and save everything afterwards, limiting the round-trips to the DB while risking loading data that is not used. One of the architectures that gives us the greatest opportunity for functional islands is EventSourcing, a though I detail here.

Personally I tend to extract pure functions a lot. It's easy to edge towards this in legacy apps and I find it a better trade-off for new apps because it makes testing a breeze, tests are blazing fast, they are easier to read without mocks and it is easier to write them in a manner that minimizes test maintenance. I tend not to do it when the islands are too small.

For more on this paradigm, here's a good collection of links. 

Conclusion

The two patterns are not mutually exclusive, in fact a lot of the goodness that both strive for is common, like testability and separation of concerns. As a result we get changeability.

Comment éviter un piège avec les systèmes "EventSourced"

Dans ce type de système apparaît un problématique pour laquelle nous sommes mal armées car elle n'existe pas dans des systèmes traditionnels. Certes il n'est pas compliqué de l'éviter si on le connaît, mais il est possible de le découvrir tard et ainsi de payer cher la correction.

TLDR; l'état perceptible d'un système est un cache. Quand on vide ce cache pour le re-calculer, il va être calculé avec la dernière version du code et donc le résultat pourrait être différent. Pour s'en prémunir il y a une invariante à respecter

Quelques bases pour comprendre

Pour comprendre la problématique, revoyons d'abord les bases de l'approche EventSourcing. Visuellement, ca va être simple. Si jamais mon résumé en 10 lignes ne suffit pas, il a y a ceci.

Quand une commande arrive par le biais d'un utilisateur ou d'une autre application, elle se fait transformer en un event (ou plusieurs) qui est persisté. Ces évènements sont utilisés pour calculer l'état (state) actuel du système. La fonction decide transforme la commande en event et la fonction evolve transforme un event en état qui est incrémenté avec chaque nouvel évènement. Certes les deux fonctions ont aussi besoin  de l'état actuel pour ce calcul, mais j'ai omis ce détail dans le dessin. 

On pourrait faire sans l'état mais pour des raisons de performance on fait un (ou plusieurs) états. A n'importe quel moment cet état peut être réinitialisé, c'est pas grave on sait tout recalculer à partir des évents. 

C'est ce recalcul qui présente un piège de temporalité.

Le piège

De temps en temps on livre de nouvelles versions de l'application. En particulier la fonction evolve, comme ceci

Ici les deux premières itérations d'état ont été calculées avec la première version d'evolve et les deux derniers avec evolve'. Dans le cas  d'un recalcul c'est différent car tous les évènements sont processés avec evolve'.  Si la dernière version de evolve traite un évent différemment alors il y a une différence, on n'a plus s4 comme état final mais s4'.

Mais quel est le problème? C'est pas ce qu'on veut? Eh ben pas toujours. Cela pourrait être un bug. Imaginons qu'on calcule la taxe sur des évènements d'achat et qu'à un moment donné la taxe a changé. On veut que ce calcul donne le même résultat qu'il soit fait maintenant ou au fil de l'eau. L'utilisateur ne doit pas être impacté par quand on a calculé l'état. Imaginons l'utilisateur qui a travaillé dur pour attendre un niveau sur StackOverflow. Il serait bien content s'il perd des points suite à une livraison.

L'invariant à respecter

Une nouvelle version de la fonction evolve doit toujours donner le même résultat pour un événement donné.

Si on choisit de le respecter, les états, les caches du système, sont toujours cohérents et n'ont pas besoin d'être recalculés. Par contre dans le cas d'un bug dans la fonction evolve on aurait un état incorrect, alors il est probable qu'on souhaite recalculer l'état pour avoir un résultat différent justement. Dans les deux cas c'est un choix intentionnel, le pire serait de ne pas avoir les idées claires sur ce mécanisme et de se retrouver surpris devant des changements d'état d'apparence aléatoires.

Mais comment fait-on pour résoudre ce dilemme de ne pas pouvoir changer le comportement actuel, tout en introduisant de nouvelles fonctionnalités ou des changements de règles métier? 

Les solutions

La seule axe de solution, à ma connaissance, se trouve dans la fonction decide qui décide quel événement créer suite à la commande. Elle peut changer, une même commande qui arrive maintenant n'est pas obligé de produire le même événement. Pourquoi donc? Simplement parce que la fonction decide s'exécute toujours au moment de l'arrivée de la commande, jamais de façon rétroactive. Cette fonction décide comment interpréter la commande en créant un événement, qui est persisté. A partir de là je connais trois approches, créer un nouveau type d'évènement, créer un nouvelle version ou se baser sur la date.

Un nouveau type d'événement

Si on change decide pour émettre une nouvelle version de l'événement alors evolve peut le traiter en cas "special". Puisque ce évènement n'existait pas avant alors on a pas cassé l'invariant. Par exemple pour un achat à 5% de TVA au lieu de 20%, au lieu d'émettre Purchased on peut émettre PurchasedVAT5-5. Toute la nouvelle logique se trouve dans le traitement de ce nouvel événement. On a pas touché à l'ancien car pour un évènement Purchase on applique toujours l'ancien taux.

Evolve reste ouvert à l'extension de nouveaux types, mais fermé à la modification sur les types existantes

Une nouvelle version d'un event existant

Si on a plus besoin de l'événement d'avant. Genre il n'existe plus de TVA à 20% alors on peut utiliser l'ancienne type. Le fait d'annoter l'événement avec une version +1 permet d'appliquer un traitement différent et donc préserver l'invariant. 

Se baser sur la date

Une autre possibilité est de se baser sur la date. L'invariant nous interdit de changer l'algo pour un même évènement, mais finalement les évènements récentes ont une date différente. Donc il suffit de préserver le fonctionnement pour les évènements antérieures à une certaine date.

Utiliser une date semble intéressant car c'est légèrement plus facile et c'est peut-être justifié dans certains cas. L'inconvénient est que dans cette approche le code n'exprime pas bien le concept métier qui a changé. La règle métier sera enfouie dans un simple if quelque part. Alors qu'en introduisant un nouveau type cela devient plus visible dans la structure du code, même dans la base de données. Avec un nouveau type, le code communique mieux le métier.

Conclusion

Pour un changement de fonctionnalité, ajouter un nouvel type/variante d'évènement en changeant decide. Étendre la fonction evolve pour le traiter, sans changer l'existant.

Une façon de résumer est de dire que 

Tant qu'une nouvelle version de evolve est une extension de la version précédente alors on n'a pas besoin de recalculer les caches du système 

accessoirement on est aussi certain de ne pas surprendre l'utilisateur - il verra toujours un état cohérent avec le passée.

Bref, c'est un piège qui peut causer bien des maux de tête, mais il est facile de s'en prémunir, dès lors que l'on sait s'en méfier.

Merci à Jérémie Chassaing de m'avoir expliqué le problème, et à Arnaud Bailly pour son aide.