Tutoriel de prise en main de Cucumber pour coder des tests Behavior Driven Development avec Java : recette aux concombres pour débutant

Créez un projet maven que vous appellerez, par exemple, cucumber_demo.

Mettre à jour votre pom.xml avec les trois dépendances suivantes :

• la première pour pouvoir utiliser Cucumber. Nous avons choisi une dépendance classique : cucumber-java (pas d'utilisation de lambda dans ce tutoriel) comme indiqué dans la partie Installation de la documentation Cucumber spécifique à Java ;
• les deux dépendances suivantes cucumber-junit et junit pour pouvoir exécuter les scénarios Cucumber dans JUnit à l'aide du JUnit Runner comme indiqué dans la partie Checking Assertions de la documentation de Cucumber. Chaque étape de scénario, considérée alors comme un test spécifique, pourra ainsi être directement visualisée dans la vue JUnit de l'IDE.

<dependencies>
    <dependency>
        <groupId>io.cucumber</groupId>
        <artifactId>cucumber-java</artifactId>
        <version>3.0.2</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.cucumber</groupId>
        <artifactId>cucumber-junit</artifactId>
        <version>3.0.2</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.12</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Une fois, le pom.xml modifié, n'oubliez pas de relancer Maven -> Update Project…

Créez un nouveau Source Folder que vous appellerez src/test/resources. Créez un fichier cocktail.feature dans un package dojo de src/test/resources.

Le plug-in Cucumber-Eclipse reconnaît l'extension .feature et vous remplit automatiquement ce fichier en vous montrant différentes manières d'écrire un scénario.

Effacez le contenu de ce fichier, ne gardez que la première ligne dans laquelle vous pouvez ajouter vos noms et prénoms, par exemple #Author: Isabelle BLASQUEZ

Recopiez ensuite dans ce fichier le récit de la story suivante et enregistrez-le :

Feature: Cocktail Ordering

  As Romeo, I want to offer a drink to Juliette so that we can discuss together (and maybe more).
  
  Scenario: Creating an empty order  
  Given Romeo who wants to buy a drink  
  When  an order is declared for Juliette  
  Then  there is no cocktail in the order

Dans Cucumber, une story est composée de scénarios et chaque scénario est composé d'étapes. La story est (d)écrite en Gherkin dans un fichier .feature dans lequel on trouve :

• le titre de la story introduit par le mot clé Feature ; Feature: <Titre de la fonctionnalité>
• Un descriptif (optionnel) (qui ne sera pas interprété par Cucumber) permettant par exemple, de résumer la story à l'aide du template As..., I want to..., so that... et/ou de noter toute autre information utile à connaître ;

• les scénarios de la story :

  • Chaque scénario est introduit par le mot clé Scenario. Ce mot clé peut être suivi ou non d'un titre qui décrit explicitement le critère d'acceptation de la story associée à ce scénario,

  • Un scénario étant un exemple concret qui illustre une règle métier, il est composé de plusieurs étapes. Les différentes étapes d'un scénario sont décrites à partir des trois principaux mots clés : Given, When et Then suivant la place et le rôle qu'elles occupent dans le scénario :

    • Given décrit les conditions initiales du scénario, c.-à-d. le contexte dans lequel va se dérouler le scénario,
    • When décrit une action effectuée par un utilisateur, c.-à-d. un événement qui va réellement déclencher le scénario,
    • Then décrit le comportement attendu, ce qui devrait se produire lorsque les conditions initiales sont remplies et l'action est effectuée.

Pour en savoir plus, la documentation de Cucumber propose deux rubriques sur les étapes (steps) Given-When-Then consultables ici et là.

Cucumber propose quelques mots clés supplémentaires comme Background, And, But, Scenario Outline et Examples que nous verrons un peu plus loin.

Remarque : une présentation complète de la grammaire utilisée par Cucumber est consultable dans la rubrique Gherkin Syntax de la documentation de Cucumber.

Le lanceur de test permet de configurer l'environnement de test des scénarios.

II-D-1. Création d'un fichier RunCucumberTest.java dans un package dojo de src/test/java▲

package dojo;  

import cucumber.api.junit.Cucumber;  
import org.junit.runner.RunWith;  

@RunWith(Cucumber.class)  
public class RunCucumberTest { }

II-D-2. Exécution du lanceur de test (RunCucumberTest.java)▲

Créer un fichier CocktailSteps.java dans un package dojo de src/test/java.

II-E-1. Le squelette des steps issu du rapport de tests de la console▲

package dojo;  

import cucumber.api.PendingException;  
import cucumber.api.java.en.Given;  
import cucumber.api.java.en.Then;  
import cucumber.api.java.en.When;  

public class CocktailSteps {
    @Given("Romeo who wants to buy a drink")
    public void romeo_who_wants_to_buy_a_drink() {
        // Write code here that turns the phrase above into concrete actions
        throw new PendingException();
    }
    @When("an order is declared for Juliette")
    public void an_order_is_declared_for_Juliette() {
        // Write code here that turns the phrase above into concrete actions
        throw new PendingException();
    }
    @Then("there is no cocktail in the order")
    public void there_is_no_cocktail_in_the_order() {
        // Write code here that turns the phrase above into concrete actions
        throw new PendingException();
    }
}

II-E-2. La configuration du lanceur de test pour une step dite PENDING (option strict)▲

@RunWith(Cucumber.class) 
@CucumberOptions(strict = true) 
public class RunCucumberTest { }

II-E-3. L'implémentation des steps en Java pour produire le comportement attendu▲

public class CocktailSteps {
    private Order order;
    @Given("Romeo who wants to buy a drink")
    public void romeo_who_wants_to_buy_a_drink() {
         order = new Order();
         order.declareOwner("Romeo");
    }
    //...
}

public class CocktailSteps {
    //...
    @When("an order is declared for Juliette")  
           public void an_order_is_declared_for_juliette() {  
            order.declareTarget("Juliette");
    }
    //...
}

import static org.junit.Assert.*;
import java.util.List;

public class CocktailSteps {
    //...
    @Then("there is no cocktail in the order")
    public void there_is_no_cocktail_in_the_order() {
        List<String> cocktails =  order.getCocktails();
        assertEquals(0, cocktails.size());
    }
}

L'idéal dans un développement agile est bien sûr d'implémenter le code métier en TDD.

Pour ce tutoriel, contentez-vous de recopier l'implémentation suivante pour votre classe Order :

package dojo;

import java.util.ArrayList;
import java.util.List;

public class Order {
    private String from;
        private String to;
        private List<String> contents = new ArrayList<String>();

        public void declareOwner(String romeo) {
            this.from = romeo ;
        }

        public void declareTarget(String juliette) {
            this.to = juliette ;
        }
    public List<String> getCocktails() {
            return contents;
        }
}

Exécutez le fichier RunCucumberTest. Que constatez-vous ? La step @Then est au VERT : le Scenario: Creating an empty order est exécuté par le programme Java avec succès.
Ce scénario est donc devenu une spécification exécutable, puisque l'exécuter revient maintenant à tester automatiquement (et donc à exécuter) le code métier.

En résumé : la mise en place de votre premier projet Cucumber s'est faite en plusieurs étapes reprises visuellement sur la figure suivante (anciennement disponible sur le site cukes.info devenu depuis cucumber.io)

Ainsi, outre créer un projet MavenCréer un projet Maven et configurer le pom.xml pour CucumberConfigurer le pom.xml pour Cucumber, la mise en place de tests fonctionnels automatisés a nécessité :

1. De décrire le comportement en langage naturel (.feature)Décrire le comportement en langage naturel (.feature dans src/test/resources) ;
2. D'implémenter le code de test des steps (méthodes java)Implémenter le code de test des steps (méthodes java) (dans src/test/java) ;
3. D'implémenter le code métier de l'applicationImplémenter le code métier de l'application ;
4. et 5. D'exécuter les tests jusqu'à ce qu'ils passent au VERT ! sans oublier bien sûr de configurer le lanceur de tests (RunCucumberTest.java)Configurer le lanceur de tests (dans src/test/java).

III-A-1. Paramétrer la step @Given▲

@Given("(.*) who wants to buy a drink")  
public void romeo_who_wants_to_buy_a_drink(String romeo) {
    order = new Order();
    order.declareOwner(romeo);  
}

III-A-2. Paramétrer la step @When▲

@When("an order is declared for (.*)")  
public void an_order_is_declared_for_Juliette(String juliette) {
    order.declareTarget(juliette);  
}

III-A-3. Paramétrer la step @Then▲

@Then("there is (\\d+) cocktails in the order")
public void there_is_nb_cocktails_in_the_order(int nbCocktails) {
    List<String> cocktails =  order.getCocktails();
           assertEquals(nbCocktails, cocktails.size());
}

Le plug-in Cucumber-Eclipse propose via Ctrl+Espace une autocomplétion dans l'éditeur de scénarios (pour les .feature). La documentation peut être consultée ici et nous allons maintenant tester cette autocomplétion en ajoutant un nouveau scénario au fichier cocktail.feature.

Placez-vous en fin de fichier cocktail.feature sur une nouvelle ligne vide. Un appel à Ctrl+Espace propose une liste de mots clés utilisables à cet emplacement.
Choisir Scenario et compléter la ligne par l'intitulé du scénario, par exemple Scenario: Creating another new empty order.

Cette fois-ci l'exemple de ce nouveau scénario concernera Tom et Jerry.

III-B-1. Première étape du scénario (Given)▲

III-B-2. Deuxième étape du scénario (When)▲

III-B-3. Troisième étape du scénario (Then)▲

Comme nous avons utilisé des steps (paramétrées) déjà implémentées dans le fichier CocktailSteps.java, il est possible de passer directement à l'exécution de ce nouveau scénario.

Exécutez le fichier RunCucumberTest. La vue JUnit vous indique maintenant que les deux scénarios passent bien au VERT !

Reprendre l'ensemble des scénarios du fichier cocktail.feature :

  Scenario: Creating an empty order  
    Given Romeo who wants to buy a drink  
    When an order is declared for Juliette  
    Then there is 0 cocktails in the order  

  Scenario: Creating another new empty order  
    Given Tom who wants to buy a drink  
    When an order is declared for Jerry  
    Then there is 0 cocktails in the order  

  Scenario: Sending a message with an order  
    Given Romeo who wants to buy a drink  
    When an order is declared for Juliette  
    And a message saying "Wanna chat?" is added  
    Then the ticket must say "From Romeo to Juliette: Wanna chat?"

La lecture des deux premiers scénarios montre une duplication dans le descriptif des étapes. Il est possible de factoriser ces descriptions et de les regrouper au sein d'un même scénario dit paramétré, grâce au mot clé Examples pour en faciliter la lecture.

Remplacer les deux premiers scénarios par le scénario paramétré suivant et indenter correctement le fichier .feature (via un clic droit et le menu Pretty Format) :

    Scenario Outline: Creating an empty order  
     Given <from> who wants to buy a drink  
     When an order is declared for <to>  
     Then there is <nbCocktails> cocktails in the order  

     Examples: 
       | from  | to       | nbCocktails |
       | Romeo | Juliette |           0 |
       | Tom   | Jerry    |           0 |

Le scénario paramétré commence par le mot clé Scenario Outline.
Il est rédigé comme un scénario classique avec, dans les étapes, des paramètres notés entre < et > : c'est une sorte de template de scénario.

Lors de l'exécution, les paramètres seront remplacés par les valeurs présentes dans les lignes de la table introduite par le mot clé Examples.
Lors de l'exécution, il y aura donc autant de scénarios exécutés que d'exemples (lignes « valuées ») présents dans la table Examples.

Exécutez RunCucumberTest.java et constatez que tous les scénarios passent au VERT !
Consultez la console qui vous indique bien que 3 Scenarios et 10 Steps ont été exécutés.
Consultez la vue JUnit pour vérifier que tous les scénarios passent au VERT ! De plus, en déroulant et ouvrant complètement toute la vue JUnit, vous verrez bien apparaître les 3 scénarios…

Un petit test pour bien s'en assurer tout de même… Changer un 0 de la colonne nbCocktails de la table Examples en 1.
Relancer les tests via RunCucumberTest.java.
Constater via la console et la vue JUnit que tous les tests ne passent plus.

Pour continuer le tutoriel, ne remettre que des 0 dans la colonne nbCocktails et exécuter RunCucumberTest.java afin de s'assurer que tous les tests passent au VERT !

Et si on paramétrait maintenant le dernier scénario, le fichier cocktail.feature pourrait ressembler à :

    Feature: Cocktail Ordering  
  
      As Romeo, I want to offer a drink to Juliette so that we can discuss together (and maybe more).  

      Scenario Outline: Creating an empty order  
        Given <from> who wants to buy a drink  
        When an order is declared for <to>  
        Then there is <nbCocktails> cocktails in the order  

        Examples: 
          | from  | to       | nbCocktails |
          | Romeo | Juliette |           0 |
          | Tom   | Jerry    |           0 |

      Scenario Outline: Sending a message with an order  
        Given <from> who wants to buy a drink  
        When an order is declared for <to>  
        And a message saying "<message>" is added  
        Then the ticket must say "<expected>"  

        Examples: 
          | from  | to       | message     | expected                            |
          | Romeo | Juliette | Wanna chat? | From Romeo to Juliette: Wanna chat? |
          | Tom   | Jerry    | Hei!        | From Tom to Jerry: Hei!             |

Transformez votre fichier cocktail.feature de manière qu'il contienne désormais ces deux Scenario Outline, indentez-le correctement (via un clic droit et Pretty Format) et exécutez RunCucumberTest.java pour vous assurer que tous les tests passent au VERT !

Remarque : la console indique désormais 4 Scenarios et 14 Steps.

Pour en savoir plus, une documentation en ligne sur Scenario Outline est disponible dans la partie Gherkin Reference de la documentation Cucumber.

Peut-être, au cours de ce tutoriel, vous êtes-vous demandé pourquoi les fichiers .feature avaient été enregistrés dans le dossier src/test/resources dans un package de même nom que celui du lanceur de test ?

Lorsqu'on travaille avec un projet maven, il est d'usage d'enregistrer les fichiers .feature dans le dossier src/test/resources. En effet, les ressources de ce dossier src/test/resources sont copiées par maven dans le répertoire target/test-classes. Ainsi, si le lanceur de test se trouve dans un dossier src/test/java, son byte code (fichier .class) se retrouvera dans le répertoire target/test-classes. Donc le lanceur et les stories se retrouveront dans le même répertoire maven target/test-classes.

Par défaut, il est donc d'usage d'enregistrer les .feature dans le dossier src/test/resources dans un package identique à celui du lanceur de test.

Cependant, il est possible grâce à l'option feature d'indiquer précisément où sont enregistrées les features à tester.

L'option feature permet donc d'indiquer au lanceur de test où sont enregistrés les scénarios.
Par exemple, créez un package dojo2 dans src/test/resources et déplacez-y cocktail.feature. Exécutez RunCucumberTest : la console affiche 0 Scenario - 0 Step : le lanceur n'a pas trouvé de scénario à exécuter.

Paramétrez le lanceur de test de la manière suivante : @CucumberOptions(features="src/test/resources",strict = true) . Exécutez-le à nouveau.

La console affiche cette fois-ci 3 Scenarios - 11 Steps, le lanceur de test est allé chercher tous les .feature du dossier src/test/resources et de ses sous-dossiers.
Remarque : on aurait également pu aussi écrire features="src/test/resources/dojo2" pour plus de précision.

Avant de continuer, remettre cocktail.feature dans le package dojo et laisser comme options de configuration : @CucumberOptions(features="src/test/resources",strict = true).
Exécuter RunCucumberTest et s'assurer dans la console que 3 Scénarios ont été testés et qu'ils passent bien au VERT !

Exécutez RunCucumberTest.

Le résultat de l'exécution des scénarios donne dans la console un affichage similaire au suivant :

    3 Scenarios (�[32m3 passed�[0m)  
    11 Steps (�[32m11 passed�[0m)  
    0m0,092s

Activer l'option monochrome permet d'améliorer la lisibilité dans la console des résultats liés à l'exécution des scénarios.
Paramétrez le lanceur de test de la manière suivante : @CucumberOptions(features="src/test/resources",strict = true, monochrome=true)
Exécutez-le à nouveau.

La console propose désormais un affichage similaire au suivant :

    3 Scenarios (3 passed)  
    11 Steps (11 passed)  
    0m0,087s

L'option plug-in permet de formater et générer un rapport afin de mettre en forme les résultats issus de l'exécution des scénarios selon ses préférences dans la console ou aux formats natifs html,xml ou json.

VII-C-1. Formater avec pretty▲

@RunWith(Cucumber.class)
@CucumberOptions(features = "src/test/resources", strict = true, monochrome = true, plugin = { "pretty" })
public class RunCucumberTest {
}

@RunWith(Cucumber.class)    
@CucumberOptions(features = "src/test/resources", strict = true, monochrome = true, plugin = { "pretty", "html:target/site/cucumber" })    
public class RunCucumberTest {    
}

@RunWith(Cucumber.class)
@CucumberOptions(features = "src/test/resources", strict = true, monochrome = true, plugin = {"pretty", "junit:target/cucumber.xml"})
public class RunCucumberTest {
}

@RunWith(Cucumber.class)  
@CucumberOptions(features = "src/test/resources", strict = true, monochrome = true, plugin = {"pretty", "json:target/cucumber.json"})  
public class RunCucumberTest {  
}

Pour pouvoir utiliser ce plug-in, il faut ajouter la dépendance suivante dans votre pom.xml :

<dependency>
    <groupId>net.masterthought</groupId>
    <artifactId>cucumber-reporting</artifactId>
    <version>3.20.0</version>
</dependency>

Mettez à jour Maven pour que cette nouvelle dépendance soit bien prise en compte dans votre projet.

Pour utiliser le plug-in cucumber-reporting et générer les différents rapports graphiques qu'il propose, nous allons reprendre et adapter le code proposé dans la rubrique Usage sur le site de ce plug-in. Jetez un petit coup d'œil à ce code ici.

VIII-B-1. S'assurer de générer un fichier json▲

@RunWith(Cucumber.class)  
@CucumberOptions(features = "src/test/resources", strict = true, monochrome = true, plugin = {"pretty", "json:target/cucumber.json"}) 
public class RunCucumberTest {  
}

public class GenerateReport {
    public static void main(String[] args) {
        // Faire un copier/coller ici du code proposé dans la partie Usage de https://github.com/damianszczepanik/cucumber-reporting
    }
}

File reportOutputDirectory = new File("target");
List<String> jsonFiles = new ArrayList<>();
jsonFiles.add("target/cucumber.json");

import java.util.List;
import java.io.File;
import java.util.ArrayList;

import net.masterthought.cucumber.Configuration;
import net.masterthought.cucumber.ReportBuilder;
import net.masterthought.cucumber.Reportable;

public class GenerateReport {
    public static void main(String[] args) {
        File reportOutputDirectory = new File("target");
        List<String> jsonFiles = new ArrayList<>();
        jsonFiles.add("target/cucumber.json");

        String buildNumber = "1";
        String projectName = "cucumberProject";
        boolean runWithJenkins = false;

        Configuration configuration = new Configuration(reportOutputDirectory, projectName);
        // optional configuration - check javadoc
        configuration.setRunWithJenkins(runWithJenkins);
        configuration.setBuildNumber(buildNumber);

        // addidtional metadata presented on main page
        configuration.addClassifications("Platform", "Windows");
        configuration.addClassifications("Browser", "Firefox");
        configuration.addClassifications("Branch", "release/1.0");

        ReportBuilder reportBuilder = new ReportBuilder(jsonFiles, configuration);
        Reportable result = reportBuilder.generateReports();
        // and here validate 'result' to decide what to do
        // if report has failed features, undefined steps etc
    }
}

Exécuter RunCucumberTest pour pouvoir exécuter les scénarios. Une fois l'exécution terminée, lancer GenerateReport pour visualiser les rapports générés par le plug-in cucumber-reporting.

Ces rapports seront automatiquement générés dans le répertoire cucumber-html-reports (Ce paramètre est fixé dans la classe ReportBuilder.java du plug-in cucumber-reporting dont le code est consultable ici si vous le souhaitez).

Allez dans le répertoire target du workspace de votre projet, vous pouvez constater :

• qu'il existe bien un fichier cucumber.json ;
• qu'un répertoire cucumber-html-reports est désormais disponible dans target.

VIII-C-1. Accéder aux rapports générés (cucumber-html-reports)▲

Le Gherkin, la classe ! : pour découvrir le Gherkin, rien de tel que de le modéliser et de mettre les yeux dans le code !

Par défaut, les mots clés du Gherkin sont en anglais. Or, la réussite d'un projet BDD est fortement liée à l'écriture des stories de manière collaborative dans un langage naturel et compris de tous.

Si vous souhaitez écrire des scénarios en français, vous pouvez paramétrer le langage de votre fichier .feature en utilisant l'instruction #langage:fr en début de fichier.

Les mots clés utilisables en français peuvent être consultés dans la partie Gherkin Dialects Languages de la rubrique Gherkin de la documentation en ligne de Cucumber ou directement dans le fichier gherkin-languages.json disponible sous Github dans l'implémentation Gherkin de Cucumber. Cette documentation montre bien que Cucumber propose les mots clés Gerkhin dans de nombreuses langues : une internationalisation du Gherkin est donc possible avec Cucumber.

Des exemples de scénarios en français pour tester la version française du Gherkin peuvent être consultés ici.

Maintenant que vous êtes familier avec Cucumber, n'hésitez pas à aller voir comment sont écrites les features et implémentées les steps dans de vrais projets utilisant Cucumber. Pour lire les scénarios (fichiers .feature), rendez-vous dans les répertoires features.

Un récent podcast entre Aslak Hellesøy, Matt Wynne, et Steve Tooke s'est intéressé aux antipatterns autour des outils BDD de type Cucumber, car contrairement aux idées reçues ce n'est pas si facile d'écrire du bon Gherkin.

• Ce podcast est disponible sur : https://cucumber.io/blog/2016/05/09/cucumber-antipatterns
  Son contenu a été repris dans les articles suivants :

  • http://www.thinkcode.se/blog/2016/06/22/cucumber-antipatterns ;
  • https://cucumber.io/blog/2016/07/01/cucumber-antipatterns-part-one ;
  • https://cucumber.io/blog/2016/08/31/cucumber-antipatterns-part-two.