Générer une documentation vivante grâce au Gherkin en dotnet
N’est ce pas un rêve d’avoir une documentation à jour sur tous nos projets? Aujourd’hui je vais vous montrer que ce rêve peut rapidement devenir une réalité (et c’est aussi soumis à plein de débats, mais ce n’est pas le lieu 😋)
Sur une majeure partie des projets où je passe, on utilise de plus en plus de Gherkin pour écrire nos tests, que ce soit des tests unitaires ou de comportement.
Ce langage a surtout l’avantage d’être compréhensible par tous les acteurs du projet, et c’est justement ça qui nous intéresse. Après tout, on fait des ateliers 3 Amigos, avec le PO, le Testeur et le Dev, on y extrait les règles et exemples, on définit avec le testeurs les scénarios automatisables, et ceux qui ne le sont pas, mais que fait on des scénarios automatisables ?
J’abordais le sujet de la lecture des pull requests dans cet autre article, et le Gherkin a également un rôle dans la relecture car en effet j’ai souvent constaté qu’on passait moins de temps à relire du code de tests plutôt que du code fonctionnel. Et pourtant ce code de test c’est ce qui est censé garantir le fonctionnement de l’application. En l’écrivant en Gherkin, j’ai pu constater que les autres développeurs s’attardaient sur la relecture des tests et comprenaient mieux le contexte.
Déjà rien que là c’est un avantage que d’avoir écrit les tests avec ce langage. Mais maintenant que ces scénarios sont écrits, pourquoi ne pas aller encore plus loin ?
Puisqu’ils sont la référence du fonctionnement, qu’ils expliquent les règles métier, je me disais que cela pouvait être top de les partager à plus large échelle. Déjà avec les testeurs, pour faire valider un pair test et lui faire gagner du temps de test lors de la recette car ce cas est déjà automatisé, mais aussi à un Business Analyst ou un Product Owner pour tous être en phase sur ce qui est réellement produit et valider que la demande du métier correspond à l’implémentation qui en a été faite. Je vous parlerai plus tard aussi de l’intérêt de ce langage sur des tests de comportement, mais là c’est pas non plus le sujet 😋
Bon du coup j’y arrive à cette Livedoc !
Puisqu’on à les scénarii en Gherkin, exploitons les, et pour cela il existe tout un tas d’outils pour générer de la documentation vivante. Ici je vais vous parler d’un outil en .net qui est SpecFlowPlusLivingDoc, rien que ça !
Cet outil peut faire pas mal de choses avec le Gherkin, notamment quand il est utilisé avec du .net et une testing library. Mais ce que j’aime encore plus c’est que nous ne sommes pas forcement obligés de faire du .net pour avoir une belle documentation vivante et parlante! Car oui, si elle est belle et fonctionnelle, elle a plus de chance d’être regardée !
Alors comment ça fonctionne ?
Déjà il faut des scénarios Gherkin (nan t’es sérieux Geo ?! …) Voilà un exemple “ésspré” pour vous ❤ ! (je mettrai un vrai exemple d’un vrai scénario tout beau tout propre et surtout qu’on utilise vraiment dans le prochain article #teasing…)
Installation et génération
Pour utiliser SpecFlowPlusLivigDoc, il vous faut un manifest dotnet, et pour avoir ça, il vous suffit de lancer cette commande :
dotnet new tool-manifest
maintenant on peut installer des plugin dotnet, et donc pour installer celui qui nous intéresse :
dotnet tool install SpecFlow.Plus.LivingDoc.CLI
Bon voilà c’est bon, vous êtes prêts ! En théorie à ce stade vous devez avoir un nouveau fichier dans votre projet : .config/dotnet-tools.json
Sur un projet dotnet, vous pouvez simplement installer un Nuget.
Cela vous donne accès à la commande livingdoc et donc à la génération d’une documentation sur base de vos Gherkin. Personnellement je les organise dans un dossier “features” ou un projet de tests en dotnet, et du coup il me suffit de lancer cette commande :
dotnet livingdoc feature-folder ./features --title “Ma doc générée” --output ./madoc.html
Ici j’ai joué le mode “feature-folder”, c’est ce mode qui est utile pour tous les projets non dotnet, car il va simplement chercher tous les “.feature” du répertoire pour en générer la documentation vivante. Et sans surprise, les autres options de la commande me permettent de donner un joli nom au site généré et de définir également la sortie. Ici un fichier html qui porte toute la documentation.
Le rendu
Avec notre exemple, cela donne une page web qui ressemble à ça :
Un truc génial avec cet outil, c’est que la documentation générée, en plus d’être jolie, peut-être conditionnée avec les valeurs présentes dans les tables, comme ici quand je sélectionne une valeur présente dans la table d’exemples de mon scénario :
Je choisis l’exemple que je veux et ça vient positionner les valeurs dans mon scénario et ainsi augmenter la compréhension de celui-ci par tous ceux qui ne sont pas forcement à l’aise avec le Gherkin à la base.
Autres tips
Je vous invite à parcourir également les autres options de la commande, notamment la partie test-assembly qui permet de brancher les résultat des tests à la livedoc générée :
La commande ressemble à :
dotnet livingdoc test-assembly .\tests\Monptojet.Tests.dll -t .\tests\TestExecution.json --title “Ma doc générée” --output .\index.html
Il vous faudra fournir la dll de test et le fichier d’exécution de test qui est généré après les avoir exécutés.
Voila un lien vers un repo Github si vous voulez tester chez vous, en faisant, au préalable, un petit “dotnet tool restore”
et pour finir, moi j’automatise cela via une build sur Azure DevOps, cela permet de générer la documentation dès que le code change et ainsi d’avoir toujours la dernière version des règles métiers sur l’application qui est installée. Pour cela j’utilise une tâche “command line” avec le script suivant :
echo LivingDoc Generation for $system.teamProject
cd $(build.sourcesdirectory)
dotnet tool restore
dotnet livingdoc feature-folder .\__features__\ --title “Mon titre de fou” --output $(Build.ArtifactStagingDirectory)\index.html
echo Done !
Attention à bien faire un “dotnet tool restore” et ne pas installer le package en global sur la PIC 😊
Merci pour la lecture ! 💘
