Thucydides: manuel de référence

La façon la plus simple de démarrer un nouveau projet Thucydides est d’utiliser l’archétype Maven. Trois archétypes sont actuellement disponibles: un pour utiliser Thucydides avec JUnit, un autre si vous voulez également écrire vos tests de recette (ou une partie d’entre eux) en utilisant easyb et enfin un supplémentaire pour vous aider à écrire vos tests de recette avec jBehave. Dans cette section, nous créerons un nouveau projet Thucydides en utilisant l’archétype Thucydides, puis nous aborderons les fonctionnalités essentielles de ce projet.

En ligne de commandes, vous pouvez exécuter mvn archetype:generate puis choisir l’archétype net.thucydides.thucydides-easyb-archetype dans la liste des archétypes proposés. Ou bien, vous pouvez utiliser votre IDE préféré pour générer un nouveau projet Maven en utilisant un archétype.

Ceci va créer un projet Thucydides simple complété d’un objet page, d’une bibliothèque d'étapes et de deux cas de tests, l’un utilisant JUnit et l’autre easyb. Les tests effectifs sont exécutés sur le dictionnaire en ligne Wiktionary.org. Avant d’aller plus loin, faisons un tour dans notre projet. Mais avant, nous devons ajouter net.thucydides.maven.plugins à nos groupes de plugin dans notre fichier settings.xml:

Ceci va nous permettre d’appeler le plugin Maven Thucydides à partir de la ligne de commandes sous la forme abrégée montrée ici. Maintenant, allons dans le répertoire généré pour notre projet, lançons les tests et générons le rapport:

Ceci doit lancer des tests web et générer un rapport dans le répertoire target/site/thucydides (ouvrez le fichier index.html).

Si vous descendez dans les rapports de tests individuels, vous verrez un récit illustré pour chaque test comme celui montré ici [fig-test-report]

Maintenant les détails. La structure projet est montrée ici:

Ce projet est conçu pour fournir un point de départ à vos tests de recette Thucydides et pour illustrer certaines des fonctionnalités de base. Les tests sont fournis dans deux styles: easyb et JUnit. easyb est une bibliothèque BDD (Behaviour Driven Development) reposant sur Groovy qui fonctionne bien pour ce type de tests. L’histoire exemple easyb se trouve dans le fichier LookupADefinition.story et ressemble à quelque chose comme ça:

Un coup d’oeil rapide à cette histoire montre qu’elle se rapporte à un utilisateur cherchant la définition du mot apple. Seul le "quoi" est exprimé à ce niveau - les détails sont masqués dans les étapes du test, voire plus profondément, dans les objets page.

Si vous préférez des tests en pur Java, l'équivalent JUnit se trouve dans le fichier LookupADefinitionStoryTest.java:

Comme vous pouvez le voir, c’est un petit peu plus technique mais cela reste à très haut niveau.

Les bibliothèques d'étapes contiennent l’implémentation de chacune des étapes utilisées dans les tests de haut niveau. Pour des tests complexes, ces étapes peuvent à leur tour faire appel à d’autres étapes. La bibliothèque d'étapes utilisée dans cet exemple peut être trouvée dans EndUserSteps.java:

Les objets Page sont un moyen d’encapsuler les détails d’implémentation d’une page donnée. Selenium 2 possède un particulièrement bon support pour les objets page et ThucydidesRunner en tire parti. L’objet page d’exemple se trouve dans la classe HomePage.java:

La pièce finale du puzzle est la classe Application.java qui est un moyen de représenter la structure de vos exigences sous forme Java de telle sorte que vos tests easyb et JUnit puissent être reliés aux exigences qu’ils testent:

C’est ce qui permet à Thucydides de générer un rapport global concernant les fonctionnalités et les histoires.

Dans les sections suivantes, nous verrons plus en détails les différents aspects de l'écriture des tests automatiques avec Thucydides.

Vous pouvez configurer des capacités personnalisées pour le pilote web en passant une liste de capacités séparées par des points virgules dans la propriété thucydides.driver.capabilities. Par exemple,

Pour tirer le meilleur de vos tests automatisés dans Thucydides, vous devez dire à Thucydides quelles fonctionnalités de votre application vous testez dans chaque test. Bien que cette étape soit facultative, elle est fortement recommandée.

La version actuelle de Thucydides utilise une organisation simple à trois niveaux pour structurer les tests de recette en morceaux plus facilement gérables. Au plus haut niveau, une application est divisée en fonctionnalités (feature), qui est une fonction de haut niveau ou un groupe de fonctions en rapport. Une fonctionnalité contient un certain nombre d’histoires (stories, correspondant aux histoires utilisateur, cas d’utilisation, etc.). Chaque histoire est validée par un certain nombre d’exemples, ou critères d’acceptation, qui sont automatisés sous forme de tests web (parfois appelés scénarios). Chaque test, à son tour, est implémenté en utilisant un certain nombre d'étapes.

Bien sûr cette structure et ces termes sont principalement des commodités pour permettre une vision haut niveau de vos tests de recette. Cependant, ce type d’abstraction à 3 niveaux semble être assez commune.

Dans la version actuelle de Thucydides, vous définissez cette structure à l’intérieur du code de test sous forme de classes Java (très légères)
[Les futures versions de Thucydides offriront d’autres façons de définir vos exigences utilisateur.]
. Ceci facilite la refactorisation et le renommage des histoires utilisateur et des fonctionnalités à l’intérieur des tests, et donne un point de référence central dans la suite de tests illustrant quelles fonctionnalités sont en cours de test. Un exemple simple est donné ici. La classe Application est simplement un moyen pratique de regrouper dans un seul fichier les fonctionnalités et les histoires utilisateur. Les fonctionnalités sont repérées avec l’annotation @Feature. Les histoires utilisateur sont déclarées sous forme de classes internes à l’intérieur d’une classe @Feature.

Easyb (http://easyb.org) est un outil BDD basé sur Groovy. Il facilite l'écriture d’histoires et de scénarios légers en utilisant la structuration classique du style BDD "given-when-then" ("étant donné-lorsque-alors") et en les implémentant en Groovy. Le plugin easyb de Thucydides est conçu pour faciliter l'écriture des tests Thucydides en utilisant easyb.

Thucydides s’intègre facilement avec les tests JUnit 4 ordinaires en utilisant le lanceur de tests ThucydidesRunner et quelques annotations spécialisées. C’est une des manières les plus simples pour commencer avec Thucydides, et cela est très bien adapté aux tests de non régression où la communication et les clarifications avec les différentes parties prenantes n’est pas une exigence.

Voici un exemple de test web JUnit Thucydides:

Examinons ceci section par section. La classe commence par l’annotation @RunWith pour indiquer qu’il s’agit d’un test Thucydides. Nous utilisons également l’annotation @Story pour indiquer quelle histoire utilisateur est testée (définie comme classe imbriquée des classes @Feature vues plus haut). Ceci est utilisé pour générer des rapports globaux.

Ensuite arrivent deux annotations essentielles pour tous les tests web. Tout d’abord, votre cas de test a besoin d’un champ public Webdriver annoté avec @Managed. Ceci permet à Thucydides de prendre soin pour vous de l’ouverture et de la fermeture du pilote WebDriver et d’utiliser ce pilote dans les pages et les étapes de test quand les tests sont exécutés:

Le second champ essentiel est une instance de la classe Pages, annotée avec @ManagedPages. Il s’agit essentiellement d’une fabrique de page que Thucydides utilise pour vous fournir des objets page instanciés. L’attribut defaultUrl vous permet de définir une URL à utiliser à l’ouverture de vos pages si aucune autre URL de base n’a été définie. Ceci est utile pour les tests dans l’IDE:

Notez que ces annotations ne sont nécessaires que pour les tests web. Si votre test Thucydides n’utilise pas de tests web, vous pouvez les ignorer en toute sérénité.

Pour des tests haut niveau de recette ou de non régression, c’est une bonne habitude de définir les tests de haut niveau comme une suite d'étapes de haut niveau. Cela rendra vos tests plus lisibles et plus faciles à maintenir si vous déléguez les détails d’implémentation de votre test (le "comment") à des méthodes réutilisables d'étape. Nous verrons comment définir ces méthodes d'étape plus tard. Cependant, vous devez au minimum définir la classe dans laquelle les étapes seront définies, en utilisant l’annotation @Steps. Cette annotation demande à Thucydides d'être à l'écoute des appels de méthodes de cet objet et (pour les tests web) d’injecter l’instance WebDriver et la fabrique de page dans la classe Steps de telle sorte qu’elles puissent être utilisées dans les méthodes d'étapes.

vous pouvez ajouter des étiquettes arbitraires à vos tests à la fois pour JUnit et easyb. Les étiquettes fournissent un contexte aux tests. Une étiquette comporte deux parties - un type et un nom. Les rapports Thucydides catégorisent les tests en se basant sur les types d'étiquettes indiqués.

Les types d'étiquettes sont arbitraires et vous pouvez ajouter autant de types que vous le souhaitez. Par défaut, un type d'étiquette story est automatiquement ajouté à chaque test. Un exemple d'étiquettes dans les rapports Thucydides figure dans [fig-tags-in-reports]

Thucydides gère tous les pilotes WebDriver de navigateurs, i.e. Firefox, Internet Explorer et Chrome ainsi que HTMLUnit. Par défaut, il utilisera Firefox. Cependant, vous pouvez passer outre cette option en utilisant la propriété système webdriver.driver. Pour l’utiliser en ligne de commandes, vous pouvez procéder comme suit:

Si vous n’utilisez pas Firefox par défaut, il vous sera utile de définir cette variable en tant que propriété dans votre fichier Maven pom.xml, par exemple:

Cependant, pour que ceci fonctionne avec JUnit, vous devez passer cette propriété webdriver.driver à JUnit. JUnit s’exécute dans une JVM dédiée et n’aura donc pas connaissance des propriétés système définies dans le build Maven. Pour y remédier, vous devez la passer explicitement à JUnit en utilisant l’option de configuration systemPropertyVariables, par exemple:

L’annotation @Managed vous permet également d’indiquer le pilote que vous voulez utiliser pour un cas de test particulier, via l’attribut driver. Les valeurs gérées actuellement sont "firefox", "iexplorer", "chrome" et "htmlunit". L’attribut driver vous permet de surcharger le pilote par défaut du système pour des exigences spécifiques. Par exemple, le cas de test suivant s’exécutera sous Chrome, quelle que soit la valeur de la propriété système webdriver.driver utilisée:

Avec easyb, vous pouvez utiliser la directive use_driver comme illustré ici:

Avec JUnit, vous pouvez également utiliser l’annotation @WithDriver pour indiquer un pilote pour un test individuel. Ceci surchargera à la fois le pilote système et l’attribut pilote de l’annotation @Managed s’il y en a. Par exemple, le test suivant s’exécutera toujours avec Firefox:

JBehave est un framework BDD open source initialement écrit par Dan North, l’inventeur du BDD. Il est fortement intégré dans le monde JVM et largement utilisé par les équipes de développement en Java qui veulent implémenter les pratiques BDD dans leurs projets.

Avec JBehave, vous écrivez vos critères de recette en écrivant des histoires utilisateur et des scénarios en utilisant la notation BDD habituelle "étant "given-when-then" ("étant donné-quand-alors"), comme montré dans l’exemple suivant:

Les scénarii comme celui-là vont dans des fichiers .story: un fichier histoire est conçu pour contenir toues les scénarii (critères de recette) d’une histoire utilisateur donnée. Un fichier d’histoires peut également contenir une section descriptive au début qui donne des informations de contexte concernant les histoires testées:

Vous implémentez habituellement une histoire JBehave en utilisant des classes et des méthodes écrites en Java, en Groovy ou en Scala. Vous implémentez les étapes de l’histoire en utilisant des méthodes annotées pour représenter les étapes des scénarii textuels, comme montré dans l’exemple suivant:

Thucydides et JBehave fonctionnent bien ensembles. Thucydides utilise de simples conventions pour débuter plus facilement dans l'écriture et l’implémentation d’histoires JBehave et de rapports à la fois pour les étapes JBehave et Thucydides qui peuvent être combinées de manière totalement transparente dans la même classe ou placées dans des classes séparées, selon ce que vous préférez.

Pour démarrer, vous aurez besoin d’ajouter le plugin JBehave Thucydides à votre projet. Avec Maven, ajoutez simplement les dépendances suivantes à votre fichier pom.xml:

De nouvelles versions sortent régulièrement, assurez-vous de contrôler le dépôt central Maven (http://search.maven.org) pour connaître les derniers numéros de version pour chacune des dépendances.

JBehave est un outil hautement configurable. L’inconvénient de ceci est que, d’origine, JBehave nécessite du code de lancement pour démarrer. Thucydides essaie de simplifier ce processus en utilisant une approche convention plutôt que configuration qui réduit significativement le volume de travail nécessaire pour démarrer avec vos tests de recette. En fait, vous pouvez vous en débarrasser avec rien de plus qu’un cas de test JUnit vide et une structure de répertoire judicieusement organisée pour vos histoires JBehave.

Un archétype jBehave est disponible pour vous aider à démarrer un nouveau projet. Comme d’habitude, vous pouvez exécuter mvn archetype:generate depuis la ligne de commande puis choisir l’archétype net.thucydides.thucydides-jbehave-archetype dans la liste des archétypes proposés. Ou bien, vous pouvez utiliser votre IDE favori pour générer un nouveau projet Maven en utilisant un archétype.

Cette archétype crée une structure de répertoires du projet semblable à celle montrée ici :

Tous les tests web peuvent être exécutés dans une seule fenêtre du navigateur en configurant la propriété système thucydides.use.unique.browser ou via programmation en utilisant runThucydides().inASingleSession() dans le lanceur JUnit.

Les étapes de test sont des méthodes Java classiques annotées avec @Step. Vous rangez les étapes et les groupes d'étapes dans des bibliothèques d'étapes. Une bibliothèque d'étapes n’est qu’une classe Java classique. Si vous exécutez des tests web, votre bibliothèque d'étapes devra soit posséder une variable membre Pages soit, plus simplement, hériter de la classe ScenarioSteps, par exemple:

Notez que les méthodes d'étapes peuvent attendre des paramètres. Ces paramètres passés à la méthode d'étape seront enregistrés et apparaîtront dans les rapports Thucydides, ce qui en fait une excellente technique pour rendre vos tests davantage maintenables et modulaires.

Les étapes peuvent également appeler d’autres étapes, ce qui est très utile pour des scénarios de tests plus compliqués. Le résultat sera la sorte de structure imbriquée que vous pouvez voir dans [fig-test-report].

Lorsque vous avez besoin d’utiliser un objet page dans l’une de vos étapes, vous vous contentez d’en demander une à la fabrique Page (Page factory) qui vous le fournira, par exemple:

Si vous voulez être sûr que vous êtes sur la bonne page, vous pouvez utiliser la méthode currentPageAt(). Celle-ci va chercher dans la classe Page Object toutes les annotations @At présentes et, s’il y en a, vérifiera que l’URL actuelle correspond au motif d’URL indiqué dans l’annotation. Par exemple, lorsque vous l’appelez en utilisant currentPageAt(), l’objet page suivant va vérifier que l’URL actuelle est précisément http://www.apache.org.

L’annotation @At gère également les jokers et les expressions rationnelles. L’objet page suivant correspondra à tout sous-domaine Apache:

Toutefois, dans le cas général, vous serez davantage intéressé par ce qui vient après le nom d’hôte. Vous pouvez utiliser le mot clef spécial #HOST pour que tout nom de serveur convienne. C’est pour cette raison que l’objet page suivant correspondra à la fois à http://localhost:8080/app/action/login.form et à http://staging.acme.com/app/action/login.form. Les paramètres seront également ignorés, donc http://staging.acme.com/app/action/login.form?username=toto&password=oz correspondra également.

Un objet page est habituellement conçu pour fonctionner avec une page web donnée. Quand la méthode open() est invoquée, le navigateur va s’ouvrir sur l’URL par défaut de la page.

L’annotation @DefaultUrl indique l’URL que ce test doit utiliser quand il est exécuté de manière isolée (par exemple depuis votre IDE). Généralement, cependant, la partie hôte de l’URL par défaut sera remplacée par la propriété webdriver.base.url ce qui vous permet de définir l’URL de base pour tous vos tests et de faciliter l’exécution de vos tests sur différents environnements, simplement en changeant cette valeur de propriété. Par exemple, dans la classe de test ci-dessus, définir webdriver.base.url à https://staging.mycompany.com fera que la page s’ouvrira à l’URL https://staging.mycompany.com/somepage.

Vous pouvez également définir des URL nommées qui peuvent être utilisées pour ouvrir la page web, assorties facultativement de paramètres. Par exemple, dans le code suivant, nous définissons une URL nommée open.issue qui accepte un unique paramètre:

Vous pouvez alors ouvrir cette page sur l’URL http://jira.mycompany.org/issues/ISSUE-1 comme illustré ici:

Vous pouvez également omettre totalement l’URL de base dans la définition de l’URL nommée en vous reposant sur les valeurs par défaut:

Et naturellement, vous pouvez faire des définitions multiples:

Vous ne devriez jamais essayer d’implémenter la méthode open() vous-même. En fait, elle est final. Si vous avez besoin que votre page fasse quelque chose au chargement, comme attendre l’apparition d’un élément dynamique, vous pouvez utiliser l’annotation @WhenPageOpens. Les méthodes de PageObject dotées de cette annotation seront appelées (dans un ordre quelconque) après que l’URL aura été ouverte. Dans cette exemple, la méthode open() ne rendra pas la main tant que l'élément web dataSection ne sera pas visible:

Les pages asynchrones sont celles dont les champs ou les données ne sont pas tous affichés quand la page est chargée. Parfois, vous devez attendre que certains éléments apparaissent ou disparaissent pour lancer vos tests. Thucydides fournit certaines méthodes pratiques dans la classe PageObject pour faciliter la gestion de tels scénarios. Elles sont principalement conçues pour être utilisées dans les méthodes métier de vos objets page, mais dans les exemples, nous les utiliserons par appel externe sur un PageObject pour la clarté de la démonstration.

Il y a des situations dans lesquelles vous pourriez trouver utile d’exécuter un peu de Javascript directement dans le navigateur pour que le travail soit fait. Vous pouvez utiliser la méthode evaluateJavascript() de la classe PageObject pour faire cela. Par exemple, vous pourriez avoir besoin de calculer une expression et d’utiliser le résultat dans vos tests. La commande suivante va évaluer le titre du document et le renvoyer au code Java appelant:

Alternativement, vous pourriez simplement vouloir exécuter une commande Javascript localement dans le navigateur. Dans le code suivant, par exemple, nous positionnons le focus sur le champ de saisie firstname:

Et, si vous êtes familier avec JQuery, vous pouvez également faire appel aux expressions JQuery:

Ceci est souvent une stratégie utile si vous avez besoin de déclencher des événements tels que des survols de souris qui ne sont actuellement pas gérés par l’API WebDriver.

Envoyer des fichiers est facile. Les fichiers à envoyer peuvent soit être placés dans un emplacement codé en dur (pas bien) ou enregistrés dans le chemin d’accès (mieux). Voici un exemple simple:

Quand on écrit des tests de recette, on est souvent amené à exprimer des attentes relatives à des objets du domaine ou à des ensembles d’objets du domaine. Par exemple, si vous testez une fonctionnalité de recherche multi-critères, vous voulez savoir si l’application trouve les enregistrements que vous attendez. Vous pourriez être capable de faire cela d’une manière très précise (par exemple en sachant exactement les valeurs des champs que vous attendez) ou bien vous pourriez vouloir rendre vos tests davantage flexibles en exprimant les plages de valeurs qui seraient acceptables. Thucydides fournit quelques fonctionnalités qui facilitent l'écriture des tests de recette dans ce type de cas.

Dans le reste de cette section, nous étudierons quelques exemples basés sur des tests du site de recherche Maven Central (voir [maven-search-report]). Ce site vous permet de rechercher des artefacts Maven dans le dépôt Maven et de consulter les détails d’un artefact donné.

Nous allons utiliser quelques tests imaginaires de non régression pour ce site afin d’illustrer comment les comparateurs (matchers) de Thucydides peuvent être utilisés pour écrire des tests plus expressifs. Le premier scénario que nous allons envisager consiste à simplement chercher un artefact par son nom et à s’assurer que seuls les artefacts correspondant à ce nom apparaissent dans la liste des résultats. Nous pourrions énoncer informellement ce critère de validation de la manière suivante:

Avec JUnit, un test Thucydides correspondant à ce scénario pourrait ressembler à celui-ci:

Voyons comment le test est implémenté dans cette classe. Le test should_find_the_right_number_of_artifacts() peut être explicité comme suit:

L’implémentation de ces étapes est illustrée ici:

Les deux premières étapes sont implémentées par des méthodes relativement simples. Cependant, la troisième étape est plus intéressante. Regardons-la de plus près:

Ici, nous passons un nombre arbitraire d’expression à la méthode. Ces expressions sont en fait des matchers, des instances de la classe BeanMatcher. Vous n’avez normalement pas à vous soucier de ce niveau de détail - vous créez ces expressions de correspondance en utilisant un ensemble de méthodes statiques fournies par la classe BeanMatcher. Aussi vous ne devriez typiquement passer que des expressions relativement lisibles telles que the("GroupId", startsWith("net.thucydides")) ou each("ArtifactId").isDifferent().

La méthode shouldMatch() de la classe BeanMatcherAsserts attend soit un unique objet Java, soit un ensemble d’objets Java et vérifie qu’au moins certains de ces objets correspondent aux contraintes indiquées par les matchers. Dans le cas du test web, ces objets sont typiquement des POJOs fournis par l’objet page pour représenter des objets du domaine ou des objets affichés à l'écran.

Il existe un certain nombre d’expressions différentes de matchers parmi lesquelles choisir. Le matcher le plus communément utilisé vérifie simplement la valeur d’un champ dans un objet. Par exemple, supposons que vous utilisez l’objet domaine montré ici:

Vous pourriez écrire un test pour vous assurer que la liste des personnes contienne au moins une personne appelée "Bill" en utilisant la méthode statique "the", comme montré ici:

Le second paramètre de la méthode the() est un matcher Hamcrest qui vous donne une grande marge de flexibilité dans vos expressions. Par exemple, vous pourriez également écrire ce qui suit:

Vous pouvez également passer des conditions multiples:

Thucydides fournit également la classe DateMatchers qui vous permet d’appliquer les matchers Hamcrest aux objets Java standard Dates et aux Datetimes JodaTime. Les exemples de code suivant illustrent la façon dont cela peut être utilisé:

Vous avez également parfois besoin de vérifier des contraintes qui s’appliquent à tous les éléments considérés. Le plus simple de ces cas de figure consiste à vérifier que toutes les valeurs prises par un champ particulier sont uniques. Vous pouvez faire cela en utilisant la méthode each():

Vous pouvez également vérifier que le nombre d'éléments qui correspondent est conforme à ce que vous attendiez. Par exemple, pour vérifier qu’il n’y a qu’une seule personne dont le prénom est Bill, vous pourriez faire cela:

Vous pouvez également vérifier les valeurs minimum et maximum en utilisant les méthodes min() et max(). Par exemple, si la classe Person possède une méthode getAge(), nous pourrions nous assurer que chaque personne a plus de 21 ans et moins de 65 en faisant ce qui suit:

Ces méthodes fonctionnent avec les objets Java normaux mais aussi avec Maps. C’est pourquoi le code suivant fonctionne également:

L’autre chose sympathique avec cette approche est que les matchers s’intègrent harmonieusement avec les rapports Thucydides. Ainsi, quand vous utilisez la classe BeanMatcher comme paramètre de vos étapes de test, les conditions exprimées dans l'étape seront affichées dans le rapport du test, comme montré dans [fig-maven-search-report].

Il existe deux canevas utilisés habituellement lors de la construction d’objets pages et d'étapes qui utilisent ce type de matcher. Le premier consiste à écrire une une méthode d’objet de page qui retourne la liste des objets du domaine (par exemple, les personnes) affichées dans la table. Par exemple, la méthode getSearchResults() utilisée dans l'étape should_see_artifacts_where() pourrait être implémentée comme suit:

Le second consiste à accéder directement au contenu de la table HTML sans explicitement modéliser les données qui y sont contenues. Cette approche est plus rapide et plus efficace si vous ne prévoyez pas de réutiliser l’objet du domaine dans d’autres pages. Nous verrons comment faire ceci après.

Parfois, faire appel au navigateur peut être coûteux. Par exemple, si vous testez des tables avec un grand nombre d'éléments web (par exemple un élément web pour chaque cellule), les performances peuvent être basses et l’utilisation mémoire élevée. Normalement Thucydides va demander la page (et créer un objet Page) à chaque fois que vous appelez Pages.get() ou Pages.currentPageAt(). Si vous êtes certain que la page ne va pas changer (i.e vous n’allez exécuter que des opérations de lecture sur la page) vous pouvez utiliser la méthode onSamePage() de la classe ScenarioSteps pour vous assurer que tous les appels suivants à Pages.get() ou Pages.currentPageAt() renverront le même objet page:

La classe PageObject offre une méthode, switchToPage(), pour faciliter le retour vers un nouvel objet Page après avoir navigué depuis une méthode d’une classe PageObject. Par exemple,

Si vous avez besoin de configurer votre propre profil Firefox personnalisé, vous pouvez le faire en utilisant la méthode Thucydidies.useFirefoxProfile() avant de lancer vos tests. Par exemple :

Pour faire cela dans Maven, vous devez passer la propriété système à JUnit en utilisant le plugin maven-surefire-plugin comme montré ici:

Thucydides fournit également un support spécial pour l’outil de suivi de bug JIRA de Atlassian. Si vous fournissez la propriété système jira.url au lieu de jira.url thucydides.issue.tracker.url, vous n’avez besoin de fournir que l’URL de base de votre instance JIRA et pas le chemin complet:

Vous devez fournir le numéro d’entrée. Vous pouvez le mettre dans le titre du test en le préfixant avec le caractère #. Pour les tests easyb, cela implique simplement de mentionner le numéro d’entrée (toujours en commençant par un caractère #) quelque part dans le nom du scénario. Pour les tests JUnit, vous utiliserez l’annotation @Title comme illustré ici:

Une autre façon d’indiquer les entrées dans JUnit consiste à utiliser les annotations @Issue ou @Issues. Vous pouvez utiliser l’annotation @Issue pour associer un test donné avec une entrée particulière.

Vous pouvez également mettre l’annotation @Issue au niveau de la classe, auquel cas l’entrée sera associée à chaque test de la classe:

Si un test doit être associé à plusieurs entrées, vous pouvez utiliser à la place l’annotation @Issues:

Lorsque vous faites cela, les entrées apparaîtront dans les rapports ThucydidesRunner avec un hyperlien vers l’entrée correspondante de votre système de suivi de bugs.

## Remplacer le répertoire par défaut des rapports

Par défaut, Thucydides génère ses rapports dans le répertoire target/site/thucydides. Il existe deux façons de surcharger ça, si c’est nécessaire. Avant tout, si vous remplacez le répertoire de sortie par défaut de Maven, vous pouvez remplacer l'élément <directory> dans la section <build> de votre fichier pom.xml. Cependant, puisque le plugin Maven Surefire exécute les tests dans une JVM forkée par défaut, vous devrez également passer la propriété project.build.directory aux tests unitaires en utilisant l'élément de configuration <systemPropertyVariables>, comme illustré ici:

Ceci aura pour résultat que les rapports Thucydides seront générés dans ‘build/site/thucydides` au lieu de `target/site/thucydides’.

Si vous voulez seulement remplacer le répertoire de sortie de Thucydides, vous pouvez utiliser les propriétés thucydides.outputDirectory et thucydides.sourceDirectory, soit dans le fichier pom.xml, soit à partir de la ligne de commandes. Par exemple, les propriétés suivantes généreront le rapport Thucydides dans le répertoire build/thucydides-reports:

Les étiquettes Thucydides sont faciles à intégrer avec d’autres applications, telles que les systèmes de suivi d’incidents ou de gestion de projets agiles. Dans cette section, nous verrons comment écrire un plugin qui permet à Thucydides d’affecter automatiquement des étiquettes à vos tests en se basant sur vos propres exigences.

Dans Thucydides, les étiquettes sont des couples arbitraires de valeurs de chaînes de caractères (nom et type) représentés par la classe TagType. Vous pouvez créer une étiquette en utilisant la méthode TagTest.withName(), comme montré ici:

Tous les types de fonctionnalité que vous fournissez seront affichés dans des onglets distincts en haut de l'écran des rapports et fourniront toutes les fonctionnalités d’agrégation et de filtrage qu’on trouve avec les rapports standards.

Pour définir vos propres étiquettes, vous devez écrire votre propre fournisseur d'étiquette en implémentant l’interface TagProvider, comme illustré ci-dessous:

L’unique méthode de cette interface, getTagsFor(), prend un objet TestOutcome et renvoie un ensemble d'étiquettes associée avec ce compte-rendu de tests. La classe TestOutcome fournit un grand nombre de champs décrivant le test et ses résultats. Par exemple, pour obtenir la liste des incidents indiqués pour ce test, utiliser la méthode getIssues(). Le code suivant est un exemple de fournisseur d'étiquette qui fournit une liste d'étiquettes en se basant sur les incidents associés (indiqués par les annotations @Issue and @Issues).

Vous devez également fournir une définition de service dans le répertoire /META-INF/services dans le classpath, de telle sorte que Thucydides puisse enregistrer et utiliser votre plugin. Un moyen simple de faire ceci est de créer un projet Maven avec un fichier appelé net.thucydides.core.statistics.service.TagProvider dans le répertoire src/resources/META-INF/services. Ce fichier est un fichier texte contenant le nom pleinement qualifié de votre fournisseur d'étiquette, par exemple:

Maintenant, incluez simplement le fichier JAR généré dans vos dépendances et Thucydides l’utilisera automatiquement pour inclure vos étiquettes personnalisées dans vos rapports.

Une stratégie habituelle pour les organisations utilisant JIRA consiste à représenter les cartes d’histoire (story cards) et/ou les critères de validation associés comme des entrées JIRA. Il est utile de savoir quels tests automatisés ont été exécutés pour une story card JIRA et quelle histoire est testée par un test donné.

Vous pouvez ajouter ces deux fonctionnalités à votre projet Thucydides en utilisant le thucydides-jira-plugin. D’abord, vous devez ajouter le thucydides-jira-plugin à vos dépendances Maven. Les dépendances dont vous aurez besoin (incluant les dépendances normales de Thucydides) sont listées ici:

Notez que l’intégration du cycle de vie JIRA requiert Groovy version 1.8 ou supérieure pour fonctionner correctement.

Vous aurez également besoin d’une implémentation de slf4j, par exemple ‘slf4j-log4j12′ (si vous utilisez Log4j) ou ‘logback-classic’ (si vous utilisez LogBack) (voir http://www.slf4j.org/codes.html#StaticLoggerBinder pour plus de détails). Si vous êtes bloqués, ajoutez simplement slf4j-simple:

Dans Thucydides, vous pouvez vous référer à une entrée JIRA en plaçant une référence au numéro correspondant de l’entrée JIRA soit dans le nom du test (en utilisant l’annotation @Title, par exemple) ou, plus simplement, en utilisant les annotations @Issue ou @Issues comme montré ici:

Dans cet exemple, le test sera associé avec l’entrée WIKI-1.

Alternativement, vous pourriez vouloir associer une entrée (telle qu’une story card) avec toutes les histoires d’un cas de test en plaçant une annotation @Issue (ou @Issues) au niveau de la classe:

Thucydides peut utiliser ces annotations pour s’intégrer avec les entrées de JIRA. L’intégration la plus simple avec JIRA implique d’ajouter des liens vers les entrées correspondantes de JIRA dans les rapports Thucydides. Pour activer ceci, vous avez simplement à fournir l’option de ligne de commandes jira.url. Vous avez cependant à passer cette option à JUnit en utilisant le maven-surefire-plugin comme montré ici:

Pour une intégration plus fine et avec aller-retours, vous pouvez également utiliser le plugin thucydides-jira-plugin. Celui-ci n’inclura pas seulement les liens vers JIRA dans les rapports Thucydides mais il mettra également à jour les entrées JIRA avec les liens vers les pages des histoires correspondantes dans les rapports Thucydides. Pour configurer cela, ajoutez la dépendance thucydides-jira-plugin à votre projet.

Vous devez également fournir un nom d’utilisateur et un mot de passe pour la connexion à JIRA ainsi que l’URL à laquelle les rapports Thucydides seront publiés (par exemple, sur votre serveur d’intégration continue). Vous ferez cela en passant les paramètres systèmes jira.username, jira.password et thucydides.public.url.

Thucydides génère également des rapports agrégés regroupant les résultats des histoires et des fonctionnalités. Pour inclure les liens JIRA dans ces rapports, vous devez renseigner l’option de configuration jiraUrl dans maven-thucydides-plugin, comme illustré ici:

Si vous ne souhaitez pas que Thucydides mette à jour les entrées JIRA pendant une exécution donnée (par exemple à des fins de test ou de débogage), vous pouvez également positionner thucydides.skip.jira.updates à true, par exemple:

Vous pouvez également configurer le plugin pour mettre à jour l'état des entrées JIRA. Ceci est désactivé par défaut: pour utiliser cette option, vous devez positionner l’option thucydides.jira.workflow.active à ‘true’, par exemple:

La configuration par défaut fonctionnera avec le cycle de vie JIRA par défaut: les entrées ouvertes ou en cours associées avec des tests réussis seront résolues, et les entrées fermées ou résolues associées à des tests en échec seront réouvertes. Si vous utilisez un cycle de vie personnalisé, ou si vous voulez modifier la façon dont les transitions se comportent, vous pouvez écrire votre propre configuration de cycle de vie. La configuration de cycle de vie utilise un simple DSL Groovy. Ce qui suit est un exemple de fichier de configuration utilisé pour le cycle de vie par défaut:

Vous pouvez écrire votre propre fichier de configuration et le mettre dans le classpath de votre projet de test (par exemple, dans le répertoire src/test/resources). Ensuite, vous pouvez surcharger la configuration par défaut en utilisant la propriété thucydides.jira.workflow dans le fichier pom.xml ou directement en ligne de commandes, par exemple:

Alternativement, vous pouvez simplement créer un fichier appelé jira-workflow.groovy et le placer quelque part dans votre classpath. Thucydides utilisera alors ce cycle de vie. Dans les deux cas, vous n’avez pas besoin de renseigner explicitement la propriété thucydides.jira.workflow.active.

Vous pouvez également intégrer les entrées JIRA dans vos histoires Thucydides easyb. Lorsque vous utilisez l’intégration easyb Thucydides, vous associez une ou plusieurs entrées avec l’histoire easyb comme un tout, mais pas avec des scénarios particuliers. Vous faites cela en utilisant la notation thucydides.tests_issue:

Vous pouvez également associer plusieurs entrées en utilisant thucydides.tests_issues:

Pour utiliser easyb avec Thucydides, vous devez ajouter la dernière version de thucydides-easyb-plugin à vos dépendances, si ce n’est pas déjà fait:

Comme avec JUnit, vous devez passer les paramètres appropriés à easyb pour que cela fonctionne. Vous devrez également utiliser la version 1.4 ou supérieure de maven-easyb-plugin, configuré pour passer les paramètres JIRA comme montré ici:

Une fois que ceci est fait, Thucydides mettra automatiquement à jour les entrées JIRA appropriées à chaque fois que les tests seront exécutés.

La propriété thucydides.take.screenshots peut être utilisée pour configurer la fréquence à laquelle les captures d'écran sont faites. Cette propriété peut prendre les valeurs suivantes :

Il est possible d’utiliser un degré encore plus fin de contrôle en utilisant des annotations. vous pouvez annoter n’importe quelle méthode de test ou d'étape (ou n’importe quelle méthode utilisée par un test ou une méthode) avec l’annotation @Screenshots pour surcharger le nombre des captures d'écran prises pour cette étape (ou sous-étape). Voici quelques exemples :

Il est possible d’avoir un contrôle encore plus fin sur les captures d'écran dans les tests. En utilisant la méthode takeScreenshot, vous pouvez indiquer à Thucydides de prendre une capture d'écran à n’importe quel endroit de l'étape indépendemment du niveau de capture d'écran choisi via la configuration ou les annotations.

Appelez simplement Thucydides.takeScreenshot() dans les méthodes de test à chaque fois que vous voulez qu’une capture d'écran soit réalisée.

Parfois, la taille par défaut de la fenêtre est trop petite pour afficher tous les écrans de l’application dans les captures. Vous pouvez agrandir la taille de la fenêtre que Thucydides ouvre en fournissant les propriétés système thucydides.browser.width et thucydides.browser.height. Par exemple, pour utiliser une fenêtre de navigateur de dimensions 1200x1024, vous devriez faire ce qui suit:

Typiquement, le paramètre largeur (width) est le seul que vous aurez besoin d’indiquer, la hauteur étant déterminée par le contenu de la page du navigateur.

Si vous exécutez Thucydides avec JUnit, vous pouvez également indiquer ce paramètre (et n’importe quel autre qui serait concerné) directement dans votre fichier pom.xml, dans la configuration de maven-surefire-plugin, par exemple:

Lorsque la largeur du navigateur est supérieure à 1000px, la vue diaporama dans les rapports s’agrandira pour montrer les captures entières.

Notez qu’il existe quelques problèmes avec cette fonctionnalité. En particulier, elle ne fonctionnera pas du tout avec Chrome, car Chrome, par conception, ne gère pas le redimensionnement de la fenêtre. De plus, puisque WebDriver utilise un vrai navigateur, la taille maximum sera limitée par la taille physique du navigateur. Cette limitation s’applique à la largeur du navigateur, étant donné que la longueur verticale totale de l'écran sera toujours enregistrée dans la capture d'écran même si celle-ci dépasse la hauteur d’une seule page et nécessite un ascenseur.

Thucydides n’enregistre par défaut que des captures d'écran redimensionnées. Ceci est fait pour réduire l’espace disque utilisé par les rapports. Si vous avez besoin d’enregistrer des captures d'écran à la taille originale, ce réglage par défaut peut facilement être surchargé en réglant la propriété thucydides.keep.unscaled.screenshots à true.

Il est possible d’enregistrer des fichiers source html pour les captures d'écran en positionnant la propriété thucydides.store.html.source à true. Les fichiers source Html ne sont pas enregistrés par défaut pour préserver l’espace disque.

Pour des raisons de sécurité ou de préservation de la vie privée, il peut être nécessaire de flouter des captures d'écran sensibles dans les rapports Thucydides. Ceci peut être fait en annotant les méthodes de test ou les étapes avec l’annotation @BlurScreenshots. Quand elle est définie sur un test, toutes les captures d'écran de ce test seront floutées. Quand elle est définie sur une étape, seules les captures d'écran de cette étape seront floutées. @BlurredScreenshot prend une chaîne de caractère en paramètre ayant la valeur LIGHT, MEDIUM ou HEAVY pour indiquer le niveau de flou. Par exemple,

Un écran à divers niveaux de flou est montré ci-dessous.

Avec JUnit 4, vous pouvez utiliser le lanceur de test Parameterized pour exécuter des tests dirigés par les données. Dans Thucydides, vous utilisez ThucydidesParameterizedRunner. Ce lanceur est très semblable au lanceur de tests JUnit Parameterized, excepté que vous utilisez l’annotation TestData pour fournir les données de test et que vous pouvez utiliser toutes les autres annotations Thucydides (@Managed, @ManagedPages, @Steps, etc.). Ce lanceur de tests générera également des rapports spécifiques Thucydides HTML et XML pour les tests exécutés.

Un exemple de test Thucydides dirigé par les données est montré ci-dessous. Dans ce test, vous vérifiez que des valeurs correctes d'âge et de couleur préférée sont acceptées sur la page d’une application (imaginaire). Pour tester cela, nous utilisons plusieurs combinaisons d'âges et de couleur préférée indiquées par la méthode testData(). Ces valeurs sont représentées comme des variables d’instance dans la classe de test instanciée via le constructeur.

Quand vous générez des rapports sur des tests web dirigés par les données, ces rapports affichent la totalité des sorties et des captures d'écran pour chaque série de données. Un rapport global des histoires pour les tests dirigés par les données est affiché, avec un cas de test pour chaque ligne des données de test. Les données de test utilisées pour chaque test sont affichées dans le rapport.

Les tests web dirigés par les données peuvent être longs, spécialement si vous devez naviguer dans une page particulière avant de tester une valeur de champ différente à chaque fois. Dans la plupart des cas, cependant, ceci est nécessaire car il n’est pas sûr de faire des suppositions sur l'état d’une page web après un test dirigé par les données précédemment effectué. Un moyen efficace de les accélérer, cependant, consiste à les exécuter en parallèle. Vous pouvez configurer ThucydidesParameterizedRunner pour que les tests s’exécutent en parallèle en utilisant l’annotation Concurrent.

Par défaut, ceci exécutera les tests de manière concurrente, en utilisant deux proccessus par coeur CPU. Si vous voulez régler finement le nombre de processus utilisés, vous pouvez le faire en précisant la propriété d’annotation threads.

Vous pouvez également exprimer cela comme valeur relative au nombre de processeurs disponibles. Par exemple, pour exécuter 4 processus par CPU, vous pourriez indiquer ce qui suit:

Thucydides vous permet d’effectuer des tests dirigés par les données en utilisant des données de test dans un fichier CSV. Vous enregistrez vos données de test dans un fichier CSV (par défaut avec des colonnes séparées par des virgules) et dont la première ligne se comporte comme un en-tête:

Ensuite, créez une classe de test contenant les propriétés qui correspondent aux colonnes des données de test. Chaque propriété doit être une propriété au sens JavaBean, avec un getter et un setter correspondant. La classe de test contiendra typiquement un ou plusieurs tests qui utiliseront ces propriétés comme paramètres pour l'étape de test ou les méthodes de l’objet page.

La classe contiendra également l’annotation @UseTestDataFrom pour indiquer où trouver le fichier CSV (celui-ci peut être soit un fichier dans le classpath, soit un chemin de fichier relatif ou absolu - mettre la série de données dans le classpath (par exemple dans src/test/resources) rend les tests davantage portables).

Vous pouvez également utiliser l’annotation @RunWith ou tout autre annotation Thucydides usuelle (@Managed, @ManagedPages et @Steps).

Un exemple de ce type de classes est montré ici:

Vous pouvez également indiquer plusieurs chemins d’accès de fichiers séparés par des séparateurs de chemin - deux points, point virgule ou virgule. Par exemple :

Vous pouvez également configurer un répertoire arbitraire en utilisant la propriété système thucydides.data.dir puis vous y référer via la variable $DATADIR dans l’annotation.

Chaque ligne de données de test nécessite d'être distinguée dans les rapports générés. Par défaut, Thucydides appellera la méthode toString(). Si vous fournissez une méthode publique retournant une chaîne et annotée par @Qualifier, c’est cette méthode qui sera utilisée pour distinguer les séries de données. Elle doit renvoyer une valeur unique pour chacune des séries de données.

Le lanceur de tests créera une nouvelle instance de cette classe pour chaque ligne de données du fichier CSV, affectant les propriétés aux valeurs correspondantes des données de test. Ainsi, quand nous exécuterons ce test, nous obtiendrons une sortie telle que celle-ci:

Il y a quelques points à noter. Les colonnes du fichier CSV sont converties en nom de propriété en Camel Case (ainsi, "NAME" devient name et "PLACE OF BIRTH" devient placeOfBirth). Puisque nous testons des applications web, tous les champs devraient être des chaînes de caractères.

Si certaines des valeurs de champ contiennent des virgules, vous devrez utiliser un séparateur différent. Vous pouvez utiliser l’attribut separator de l’annotation @UseTestDataFrom pour indiquer ce séparateur alternatif. Par exemple, les données suivantes utilisent un point-virgule comme séparateur:

Pour exécuter nos tests avec ces données, nous devrons utiliser une classe de test telle que la suivante:

Ceci produira une sortie telle que celle-ci:

Le support d’Excel sera ajouté dans une future version. Cependant, si vous enregistrez vos données sous forme CSV, il devient facile de suivre les modifications des données de test dans votre système de contrôle de version.

Parfois, vous voulez utiliser le test dirigé par les données au niveau d’une étape, plutôt qu’au niveau du test. Par exemple, vous pourriez vouloir naviguer dans un écran donné de l’application puis essayer différentes combinaisons de données ou boucler sur une séquence d'étapes avec des données provenant d’un fichier CSV. Ceci évite d’avoir à ré-ouvrir le navigateur à chaque ligne de données.

Vous pouvez faire cela en ajoutant des valeurs de propriété à vos fichiers d'étapes. Considérez le fichier d'étapes suivant:

Le groupe d'étapes enter_personal_details utilise les champs étape pour exécuter les étapes enter_name_and_age et enter_address. Nous voulons récupérer ces données depuis un fichier CSV et boucler sur l'étape enter_personal_details pour chaque ligne de données.

Nous faisons cela en utilisant la méthode withTestDataFrom() de la classe StepData:

Ceci va appeler data_driven_test_step() plusieurs fois, injectant à chaque fois des données dans l'étape depuis le fichier test-data/simple-data.csv.

Vous pouvez également utiliser autant de fichiers que vous le souhaitez, y compris pour un même test. Vous pouvez également utiliser le même fichier de données pour plus d’une étape de test. Rappelez-vous que seules les propriétés correspondant aux colonnes du fichier CSV seront instanciées - les autres seront ignorées:

Au fait, nous devons utiliser ThucydidesRunner pour les cas de tests au lieu de ThucydidesParameterizedRunner.

Notez que, comme raccourci, vous pouvez omettre les méthodes setters et ne déclarer que les champs nécessaires comme publics. De cette façon, la classe d'étapes montré ci-dessus pourra être réécrite comme suit:

Par défaut, les cas de test sont répartis également entre les batchs. Ceci peut être inefficace si certains cas de tests ont plus de tests que d’autres. Dans de telles situations, une stratégie de batch différente, DIVIDE_BY_TEST_COUNT, peut être définie en utilisant la propriété système thucydides.batch.strategy. Cette stratégie va distribuer équitablement les cas de tests entre les batchs en se basant sur le nombre de méthodes de test dans chacun des cas de test.

Vous pouvez utiliser l’API agile de FluentLenium avec Thucydides. La meilleure façon d’utiliser FluentLenium dans Thucydides est d’utiliser ThucydidesFluentAdapter qui est disponible dans le PageObject. Voici un exemple du même PageObject écrit en style traditionnel et avec FluentLenium.

et avec FluentLineum

Une autre nouvelle fonctionnalité expérimentale introduit la possibilité de remplacer la méthode element() communément utilisée avec $, comme illustré dans les exemples suivants :

Il est parfois nécessaire de réessayer un test un échec. Ceci peut être réalisé en réglant la propriété système max.retries avec le nombre de fois que vous voulez que les tests en échec soient réessayés.

Les méthodes dans la bibliothèque d'étape peuvent être utilisées pour fournir de la documentation complémentaire pour les scénarios de test dans les rapports Thucydides. Vous pouvez passer du texte HTML valide en paramètre aux méthodes @Step dans la bibliothèque d'étapes. Ce texte apparaîtra sous forme de texte mis en forme dans les rapports sur la page des détails de l'étape. La capture d'écran suivante illustre ceci.

Ceci est obtenu en créant une méthode fictive @Step appelée description prenant un paramètre chaîne de caractères. À l’exécution, les tests fournissent à cette méthode du texte au format html en paramètre.