Les bases de la rédaction en Gherkin

Issu de la pratique du Behavior Driven Development, le langage Gherkin est très souvent celui associé aux projets agiles car il permet de décrire avec cohérence les comportements d’un utilisateur. Tu peux l'utiliser à la fois en tant que PO (Product Owner),  QA Agile et développeur. Ce langage contribue à la création d’une documentation uniforme en encourageant les équipes qui l’implémentent à suivre des règles de rédaction strictes.

Toutefois, rédiger des user stories, des critères d'acceptation ou des scénarios de test en Gherkin n'est pas toujours aisé. Il peut même rendre la communication moins fluide et plus complexe s’il n’est pas bien maitrisé.

Pour éviter ce biais et maitriser les bases du Gherkin, nous allons revoir ensemble les bases du language Gherkin, les règles à respecter et surtout te donner quelques exemples.  
‍

Qu’est-ce que le langage Gherkin ?

Pourquoi utiliser le langage Gherkin ?

L’un des enjeux majeurs de la gestion de projet dans un environnement agile est d’assurer une communication claire et efficace entre le PO, les développeurs et le QA agile. Si Chacun utilise son propre langage, cela peut générer des interprétations et/ou des incompréhensions.

Pour répondre à cette problématique, tu peux te tourner vers un langage compréhensible et utilisable par tous : le Gherkin.

Ainsi, les communications se font à partir des comportements utilisateurs attendus (parcours utilisateur) plutôt qu’à partir d’une succession de micro-règles qui s’ajoutent les unes aux autres (fonctionnalité isolée).

Dans une organisation agile, le langage Gherkin est utilisé par tous les acteurs du projet :

• Le Product Owner pour écrire ses US‍
• ‍Le QA agile pour écrire ses critères d’acceptation et ses scénarios de test‍
• Le Développeur ou le QA automaticien pour scripter les tests automatisés

Le Gherkin se pose comme un langage universel de la gestion de projet agile.

Comment écrire en Gherkin ?

Le langage Gherkin est structuré par ligne et par mots clés :  

• Une ligne commence par un mot clé
• Un mot clé correspond à une étape du comportement utilisateur  
• Une ligne = un mot clé

Pour rédiger en Gherkin, il est nécessaire de connaitre les principaux mots clés et leur fonction. Les mots clés  "Given”, "When" et “Then" sont les fondamentaux de la rédaction du Gherkin. Ils s’utilisent dans cet ordre et servent à décrire les comportements utilisateurs attendus :

• ‍Given (Etant donné que) : décrit le contexte initial ‍
• When (Lorsque) : décrit l’action faite par l’utilisateur à partir du contexte initial  ‍
• Then (Alors) : décrit le comportement attendu suite à l’action faite par l’utilisateur  

Néanmoins, des mots clés secondaires permettent d’ajouter des éléments de contexte, d’action ou de résultat :

• ‍And (Et) : Ajoute une condition au Given, When ou Then    ‍
• But (Mais) : Exclut une condition au Given, When ou Then    

Enfin, les mots-clés de classement te permettent de classer et reconnaître facilement les user stories/tests lors de la création de ta documentation en Gherkin :

• ‍Fonctionnalité (PO) : correspond à la description de la user story et donc des comportements attendus. ‍
• Scenario (QA agile) : titre clair et concis d’un comportement attendu de la fonctionnalité pour identifier un scenario de test (y compris les cas non passants). Il peut donc y avoir plusieurs scénarios dans ta fonctionnalité.

Si tu souhaites aller plus loin sur l’utilisation des différents mots clés, nous t’invitons à consulter le site de Cucumber.
‍

Les règles à respecter pour la rédaction en langage Gherkin

La règle d’or de la rédaction en Gherkin

Commençons par la règle d’or d’une bonne rédaction en Gherkin.

Toute personne, même celle ne connaissant rien à ton projet, doit pouvoir comprendre le comportement décrit, sans se poser de question, ni avoir de doute sur l’interprétation.

Si cette règle est respectée, c’est que ta rédaction a rempli tous ses objectifs. Cela correspond en quelque sorte à la Definition Of Done de la rédaction en Gherkin.

N’hésitez donc pas à faire relire votre US, vos critères d’acception ou vos scénarios de test à un collègue ou une personne extérieure à votre squad / feature team. Il sera votre meilleur expert qualité sur le sujet ! La cérémonie des 3 Amigos est également un rituel idéal pour procéder à la validation de vos US et critères d’acceptation.

Les 3 règles fondamentales tributaires de la règle d’or

Néanmoins, avant de faire appel à ton beta testeur préféré, le respect de certaines règles devrait te permettre d’atteindre ton objectif.

‍Un découpage clair :

• 1 US (user story) = 1 fonctionnalité : limiter les risques de confusion ou d’interprétation, la user story doit être claire, précise et bien découpée.  
• 1 scénario = 1 comportement de l’US : comme pour les US, les critères d'acceptance et les scénarios de test doivent être clairs et concis. Si ta rédaction contient plus d'un "Given", "When" et/ou "Then ", il est peut-être judicieux de la découper en plusieurs scénarios (voir notre exemple dans la section ‘La rédaction en Gherkin par l’exemple).  

‍Une syntaxe claire et lisible :

• Toujours respecter l’ordre "Given"; "When" ; "Then"  afin que la rédaction en Gherkin suive l’ordre chronologique du comportement utilisateur attendu. Toutefois, il est possible d'ajouter des conditions supplémentaires avec des "And" ou des "But" à chacun de ces 3 mots clés. ‍
• Eviter le langage technique et le code pour se concentrer sur la description du comportement de l’utilisateur. ‍
• Introduire un double espace ou une tabulation entre chaque niveau (Feature ; Scenario ; Steps) pour clarifier la lecture.  

Des titres de scénario clairs et synthétiques :

• Pour vérifier rapidement la pertinence du contenu si tu dois sélectionner, ajuster ou prioriser le scope des tests (TNR, priorisation...) avec ton équipe.
• Pour identifier les tests en double : tu peux ainsi facilement identifier les tests ayant les mêmes objectifs et ne garder que l’essentiel.
• Faciliter la maintenance : en cas de changement de comportement attendu de l’utilisateur, il t'est plus aisé d’identifier les scénarios que tu devras modifier.

Conseil : dans une optique de clarté, et d'identification rapide des scénarios, il est préférable de ne pas dépasser 5 scénarios de test par user story.
‍‍

La rédaction en Gherkin par l’exemple

Le cas de test en langage standard

Prenons l'exemple d'une personne qui veut acheter le tome 1 d'Harry Potter sur un site e-commerce que l'on nommera Fleury&Bott.com.
Dans le cas présent, nous ne sommes pas dans un scénario de test guidé par le comportement utilisateur, mais dans un cas de test qui suit une procédure de test.

Le scénario de test en langage Gherkin

Nous allons donc transformer naturellement le cas de test ci-dessus en scénario de test via le langage Gherkin.

Afin d'être le plus lisible possible, découpons ce cas de test en 2 scénarios distincts :

• Un scénario lié au comportement attendu de la search bar  
• Un scénario lié au comportement attendu pour accéder à la description du produit  

‍

En conclusion, le Gherkin pose les règles de rédaction des tests pour permettre à n’importe quelle partie prenante de comprendre le contexte et attendu d’une user story. Une fois implémenté, le langage Gherkin s’adapte facilement aux besoins de chaque équipe agile et peut être réinterprété au besoin (rédaction des scénarios en français, par exemple) dès lors que les règles d’or sont respectées.

Ce qu’il faut retenir :

Le langage Gherkin, c’est un langage :  

• Universel, pratique, facilement utilisable et compréhensible par tous.  
• Rédigé sur la base du comportement utilisateur attendu.  

Les bonnes pratiques de la rédaction en Gherkin :  

• Un bon découpage des user stories et des scénarios utilisateurs. 
• Des titres de scénario synthétiques, clairs et compréhensibles.  
• Une syntaxe claire, rigoureuse et lisible.