Aller au contenu

Automatisation avec Cucumber JVM

Compatibilité avec Cucumber JVM 5 ou postérieur

Si votre projet intègre une version 4 de Cucumber JVM, sélectionnez la technologie de test Cucumber 4. S'il intègre une version supérieure ou égale à Cucumber JVM 5, sélectionnez la technologie de test Cucumber 5+.

Référence du test dans Squash TM

En fonction de la précision du rapport de test que vous souhaitez, vous pouvez affiner votre référence de test à une feature (si votre fichier .feature contient plusieurs features, ce qui n'est pas conseillé mais est rendu possible par Cucumber) ou à un scénario en particulier.

Pour lier un cas de test Squash TM à un test automatisé Cucumber, le champ Référence du test automatisé du bloc Automatisation du cas de test doit avoir la forme suivante :

[dépôt]/[projet]#[fichier_feature]#[nom_feature]#[scénario]
ou
[dépôt]#[fichier_feature]#[nom_feature]#[scénario]
(La référence contient toujours trois caractères #.)

avec :

  • [dépôt] : Nom du dépôt Git.

  • [projet] : Chemin vers le projet Cucumber (c'est-à-dire le dossier contenant le fichier pom.xml).
    Ce paramètre est optionnel, c'est-à-dire que si le fichier pom.xml est à la racine du dépôt, ce chemin sera absent.

  • [fichier_feature] : Chemin et nom du fichier de test Cucumber à partir du dossier précédent (avec son extension .feature).

  • [nom_feature] : Nom de la feature tel que renseigné dans le fichier de test Cucumber.
    Ce paramètre est optionnel, c'est-à-dire que la chaîne de caractères [nom_feature] peut être vide.

  • [scénario] : Nom du scénario tel que renseigné dans le fichier de test Cucumber.
    Ce paramètre est optionnel, c'est-à-dire que la chaîne de caractères [scénario] peut être vide.

Exemple : dépôt/chemin/vers/projet/cucumber#chemin/vers/test.feature#nom_de_feature#nom_de_scénario

Ancienne syntaxe

Les anciennes versions de Squash Orchestrator utilisaient la forme suivante :
[dépôt]/[fichier_feature]#[nom_feature]#[scénario]
ou
[dépôt]/[fichier_feature]#[nom_feature]
ou
[dépôt]/[fichier_feature]
avec :

  • [dépôt] : Nom du dépôt Git.
  • [fichier_feature] : Chemin et nom du fichier de test Cucumber à partir de la racine du projet (avec son extension .feature).
  • [nom_feature] : Nom de la feature tel que renseigné dans le fichier de test Cucumber.
    Ce paramètre est optionnel, c'est-à-dire que les deux derniers composants de la référence du test peuvent être absents.
  • [scénario] : Nom du scénario tel que renseigné dans le fichier de test Cucumber.
    Ce paramètre est optionnel, c'est-à-dire qu'il peut être absent.

Exemple : mon_dépôt/chemin/vers/mon/test.feature#nom_de_ma_feature#nom_de_mon_scénario

Cette syntaxe est dépréciée et ne devrait plus être utilisée. Elle est cependant encore supportée.
Cette syntaxe ne supportait pas les tests Cucumber situés ailleurs qu'à la racine du dépôt de source.

Référence du test automatisé et exécution

La précision de la feature [nom_feature] et du scénario [scénario] dans la référence du test n'influe pas sur l'exécution, mais sur la détermination du résultat du test.
Ainsi, même en définissant une granularité à l'échelle d'une feature ou d'un scénario, la totalité des tests contenus dans le fichier .feature sera exécutée (ce qui signifie, par exemple, que si plusieurs cas de test Squash TM pointent vers le même fichier mais vers des features ou scénarios différents, tous les tests du fichier seront exécutés plusieurs fois).
Les rapports de test contiennent les traces de tous les scénarios exécutés. Par contre, seuls les statuts Error / Failed / Success correspondant à cette granularité fine seront considérés pour définir le résultat du cas de test.

Détermination du résultat du cas de test

Si un nom de feature [nom_feature] et/ou un nom de scénario [scénario] n'est pas spécifié, le résultat du cas de test Squash TM est calculé en prenant en compte les résultats individuels de chaque scénario Cucumber exécuté :

  • Si au moins un scénario est en statut Error (dans le cas d'un problème technique), l'exécution sera en statut Blocked.
  • Si au moins un scénario a échoué fonctionnellement et qu'aucun scénario n'est en statut Error, l'exécution sera en statut Failed.
  • Si tous les scénarios ont réussi, l'exécution sera en statut Success.

Non support de cucumber-junit-platform-engine

L'implémentation courante de Squash Orchestrator utilise l'option mvn -Dcucumber.features=path/to/mytest.feature pour indiquer le fichier .feature à exécuter.
Cette option n'est pas prise en compte par cucumber-junit-platform-engine. Ceci a pour effet qu'en lançant, dans l'orchestrateur, un test Cucumber avec ce moteur, tous les tests du projet Maven seront lancés. Pour éviter ce problème, il faut utiliser le moteur junit-vintage-engine.

Si vos tests utilisent cucumber-junit-platform-engine, vous pouvez les modifier de la façon suivante pour passer à junit-vintage-engine :

  • dans le fichier pom.xml 
    <dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-junit-platform-engine</artifactId>
    <version>7.2.3</version>
    <scope>test</scope>
</dependency>
    doit être remplacé par 
    <dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-junit</artifactId>
    <version>7.2.3</version>
    <scope>test</scope>
</dependency>   
<dependency>
    <groupId>org.junit.vintage</groupId>
    <artifactId>junit-vintage-engine</artifactId>
    <version>5.8.2</version>
    <scope>test</scope>
</dependency>
  • dans le fichier racine des tests 
    import org.junit.platform.suite.api.IncludeEngines;
import org.junit.platform.suite.api.SelectClasspathResource;
import org.junit.platform.suite.api.Suite;

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("path/to/my-feature-files")
public class RunCucumberTest {
}
    doit être remplacé par 
    import org.junit.runner.RunWith;
import io.cucumber.junit.Cucumber;

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

Nature des paramètres Squash TM exploitables

Les paramètres Squash TM exploitables vont différer suivant si vous utilisez les composants Community/Premium ou Ultimate de Squash.

Voici le tableau des paramètres exploitables (ces paramètres sont transmis en tant que paramètres de test, voir ci-dessous, Squash TM ne génère pas de paramètres globaux) :

Nature Clé Community/Premium Ultimate
Nom du jeu de données DSNAME ✅ ✅
Paramètre d'un jeu de données DS_[nom] ✅ ✅
Référence du cas de test TC_REFERENCE ✅ ✅
UUID interne du cas de test TC_UUID ✅ ✅
Champ personnalisé du cas de test TC_CUF_[code] ✅ ✅
Champ personnalisé de l'itération IT_CUF_[code] ❌ ✅
Champ personnalisé de la campagne CPG_CUF_[code] ❌ ✅
Champ personnalisé de la suite de tests TS_CUF_[code] ❌ ✅

Légende :

  • [code] : valeur renseignée dans le champ “Code” d’un champ personnalisé
  • [nom] : nom du paramètre tel que renseigné dans Squash TM

Comme indiqué, Squash TM ajoute un préfixe au code du champ personnalisé transmis. Assurez-vous de le prendre en compte.

Voir la documentation de Squash TM pour plus d'information sur les champs personnalisés.

Utilisation de paramètres

Il est possible lors de l’exécution d’un test Cucumber d’exploiter des paramètres au sein de celui-ci. Un paramètre peut être un paramètre de test ou un paramètre global. Squash TM ne transmet que des paramètres de test. Des paramètres de test et des paramètres globaux peuvent être utilisés dans le cas d'un lancement à partir d'un pipeline CI/CD avec les actions cucumber/params et cucumber5/params.

Pour cela, il faut suivre les étapes suivantes :

  • Importer la libraire opentestfactory-java-param-library dans le projet Maven contenant les tests à exécuter en ajoutant au fichier pom.xml :

    • le dépôt Maven suivant :
    <repositories>
    <repository>
        <id>org.squashtest.repo.release</id>
        <name>Squashtest repository for releases</name>
        <url>https://nexus.squashtest.org/nexus/repository/maven-squashtest-public-releases/</url>
    </repository>
</repositories>
    • la dépendance Maven suivante :
    <dependencies>
    <dependency>
        <groupId>org.opentestfactory.util</groupId>
        <artifactId>opentestfactory-java-param-library</artifactId>
        <version>1.1.0</version>
    </dependency>
</dependencies>

  • Vous pouvez ensuite récupérer la valeur d’un paramètre du type souhaité en utilisant la syntaxe suivante :

    ParameterService.INSTANCE.getString("paramName");
ParameterService.INSTANCE.getInt("paramName");
ParameterService.INSTANCE.getFloat("paramName");
ParameterService.INSTANCE.getDouble("paramName");
ParameterService.INSTANCE.getBoolean("paramName");

    Les méthodes ci-dessus recherchent le paramètre souhaité dans les paramètres de tests ; si elles ne le trouvent pas, elles le cherchent ensuite dans les paramètres globaux.
    Ces méthodes propagent une ParameterNotFoundException si le paramètre n'est pas trouvé. Si le paramètre est trouvé mais ne peut être converti dans le type souhaité, une ParameterFormatException est propagée. Pensez à gérer ces exceptions dans vos classes de tests.
    Attention : la conversion de données booléennes renvoie true lorsque la chaîne de caractères à convertir est égale à "true" (quelqu'en soit la casse), false dans tous les autres cas ; mais elle ne propage jamais d'exception.

  • Il est aussi possible de définir une valeur par défaut dans le cas où le paramètre n'est pas trouvé en utilisant la syntaxe suivante :

    ParameterService.INSTANCE.getString("paramName", defaultValue);
ParameterService.INSTANCE.getInt("paramName", defaultValue);
ParameterService.INSTANCE.getFloat("paramName", defaultValue);
ParameterService.INSTANCE.getDouble("paramName", defaultValue);
ParameterService.INSTANCE.getBoolean("paramName", defaultValue);

    Les méthodes ci-dessus ne propagent donc pas de ParameterNotFoundException quand le paramètre recherché n'est pas trouvé mais propagent une ParameterFormatException si le paramètre est bien trouvé, mais ne peut être converti dans le type souhaité.

  • Il est également possible de cibler un paramètre de test ou un paramètre global avec des méthodes spécifiques. Comme pour les méthodes précédentes, elles sont disponibles dans des versions avec et sans valeur par défaut. En voici quelques exemples :

    ParameterService.INSTANCE.getTestString("paramName");
ParameterService.INSTANCE.getGlobalInt("paramName");
ParameterService.INSTANCE.getTestFloat("paramName", defaultValue);
ParameterService.INSTANCE.getGlobalBoolean("paramName", defaultValue);

Utilisation du nom d'un jeu de paramètres Squash TM en tant que tag

En complément de l'exploitation des paramètres décrite ci-dessus, Squash est capable d'exploiter le nom d'un jeu de données Squash TM d'un cas de test comme valeur d'un tag, permettant ainsi de n'exécuter qu'un jeu de données particulier d'un scénario Cucumber.

Pour cela, il faut suivre les étapes suivantes :

  • Renseigner des jeux de données dans l'onglet Paramètres du cas de test dans Squash TM.

  • Créer au sein de son scénario Cucumber autant de tableaux exemples que de jeux de données et annoter ces tableaux d'un tag correspondant au nom d'un jeu de données Squash TM.

  • Créer une seule ligne d'éléments dans chaque tableau exemple afin de fixer une valeur pour les différents paramètres du scénario.

Exemple

Ci-dessous un exemple d'un fichier de test Cucumber et l’automatisation du cas de test Squash TM associé :

Exemple Cucumber

Exemple Cucumber

Exemple Cucumber

Ajout de paramètres sur la ligne de commande de lancement d'un test

Il est possible de passer des paramètres supplémentaires à la commande mvn test en utilisant la variable d'environnement CUCUMBER_EXTRA_OPTIONS. La définition d'une variable d'environnement dans Squash TM et son association à l'orchestrateur sont exemplifiées ici.

Certains paramètres sont déjà définis dans la commande mvn test utilisée pour lancer un test :

Note

La syntaxe à utiliser pour passer les paramètres additionnels est -Dcucumber.[module].[param]=[value] (par exemple, -Dcucumber.ansi-colors.disabled=true). 

mvn test \
  -f "{POM_path}" -Dmaven.test.failure.ignore=true \
  -Dcucumber.features="{feature_path}" \
  -Dcucumber.plugin="html:{html_report_path},junit:{junit_report_path}" \
  -Dcucumber.filter.tags="{Squash_TM_tags}" $CUCUMBER_EXTRA_OPTIONS

Note

La variable d'environnement CUCUMBER_EXTRA_OPTIONS ne peut être utilisée que pour définir une option de Cucumber JVM, pas une option de Maven.

mvn test \
  -f "{POM_path}" -Dmaven.test.failure.ignore=true \
  -Dcucumber.options="{feature_path} --plugin html:{html_report_path} \
  --plugin junit:{junit_report_path} --tags {Squash_TM_tags} $CUCUMBER_EXTRA_OPTIONS"

Il faut éviter de passer, via la variable d’environnement CUCUMBER_EXTRA_OPTIONS, des paramètres sur la ligne de commande qui sont en conflit avec ceux déjà utilisés ou qui impactent la création ou la localisation des rapports attendus par l’orchestrateur (voir la liste des rapports pour Cucumber JVM 4 et pour Cucumber JVM 5 ou postérieur).

Non support du caractère espace sur Linux

Squash Orchestrator ne supporte aujourd'hui pas le caractère espace () dans la variable d’environnement CUCUMBER_EXTRA_OPTIONS pour les tests exécutés dans un environnement d'exécution Linux.

Génération des rapports Allure avec les actions cucumber/cucumber et cucumber5/cucumber

Dans le cas de l'utilisation des actions cucumber/cucumber et cucumber5/cucumber dans un workflow, si vous voulez que les résultats du test Cucumber soient pris en compte dans le rapport Allure généré pour le workflow, vous devez utiliser le reporter JUnit (possiblement avec d'autres reporters).

Amélioration des performances

Il est possible d'utiliser Maven Daemon, un wrapper de Maven, pour accélérer les exécutions des tests Cucumber : voir les détails techniques. Maven Daemon est utile dans le cas où les tests exécutés sont courts et nombreux. Pour les tests qui durent, chacun, au-delà de quelques minutes, il n'a pas d'intérêt réel.

Versions supportées

Squash a été validé avec Cucumber-JVM 4.2.6, 5.7.0, 6.11.0 et 7.0.0. Toute version récente devrait fonctionner.