Tutoriel : HelloWorld, un premier exemple pour commencer avec rTest

Les ressources de cet exemple se situent dans le répertoire ./tutorial/ du dossier rTest.

Le projet HelloWorld

Pour bien comprendre le fonctionnement de rTest, il faut se mettre à la place d'un développeur de scripts FME qui cherche à vérifier si son projet est conforme aux spécifications.

Prenons l'exemple du projet FME HelloWorld.fmw.

L'objectif de ce projet est d'écrire dans un fichier au format Spatialite les informations relatives à un pays à partir d'un jeu de données Shapefile. Le traitement doit s'intéresser uniquement au pays qui contient le point dont les coordonnées sont passées en paramètre.

Par exemple, si les coordonnées passées en paramètres valent -100.0 (longitude) et 60.0 (latitude), alors le résultat doit contenir la géométrie et les attributs du Canada.

  • Format source : ESRI Shapefile

  • Format destination : SpatiaLite

  • Paramètres :

    • --xy (longitude et latitude du point séparées par un espace)

    • --destSpatialiteFile (emplacement du résultat)

L'image ci-dessus montre le projet HelloWorld.fmw que pourrait créer un développeur pour répondre à cette demande.

Le traitement produit un résultat mais pour valider son bon fonctionnement, il manque deux choses :

  • Identifier les cas de test

  • Vérifier que le traitement engendre le bon résultat pour chacun des cas de test

Démarche

1. Identification des cas de test

L'identification des cas de test doit idéalement provenir des spécifications. On peut imaginer les cas de test suivants :

  • Point en Suisse (coordonnées positives)

  • Point en Argentine (coordonnées négatives)

  • Coordonnées sur une frontière entre 2 pays (France et Suisse)

  • Coordonnées sur un point triple (France, Suisse, Italie)

  • Point en mer (0 0)

  • Coordonnées numériques aberrantes (1000 1000)

  • Coordonnées alphanumériques (1x 45)

  • Coordonnées avec mauvais délimiteur (4;45)

  • Absence de coordonnées

  • …

Pour chaque cas, il faudrait vérifier si le traitement FME échoue ou non, si le pays trouvé est bien le bon et vérifier au moins une fois que la géométrie et tous les attributs ont bien été chargés.

2. Ecriture du scénario de tests

La deuxième étape consiste à écrire un scénario de test.

Le document ./tutorial/HelloWorld.xml montre la formalisation des trois premiers tests :

  • Point dans un pays avec des coordonnées positives (Suisse)

  • Point dans un pays avec des coordonnées négatives (Argentine)

  • Point sur une frontière (Franco-Suisse)

Contenu

  • L'entête <scenario> est obligatoire et généralement fixe.

<scenario xmlns="http://www.veremes.com/rtest" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.veremes.com/rtest http://schemas.veremes.net/rtest/2.0/rtest.xsd">

  • Les éléments <projet> et <description> sont purement descriptifs et même facultatifs. Ils sont exploités dans les rapports de contrôle.

<project>Hello World !</project>
<description>A simple test scenario to understand how rTest for FME does work</description>

  • Les éléments <rtest> contiennent les informations relatives aux tests à réaliser. Chaque élément <rtest> est composé d'un ou plusieurs traitements (élément <process>) et d'une ou plusieurs vérifications (<check>).

<rtest id="hw.t1" label="Point with positive coordinates">
  <processCollection>
    <process label="Run HelloWorld.fmw with a point in Switzerland">
...
    </process>
  </processCollection>
  <checkCollection>
    <check label="Number of features in the 'country' feature type">
..
    </check>
    <check label="Country name in the first record">
...
    </check>
  </checkCollection>
</rtest>

  • Le traitement (<process>) est décrit essentiellement par l'emplacement du projet .fmw et par les paramètres à utiliser pour exécuter le projet conformément au cas de test, notamment le paramètre xy qui définit les coordonnées du point.

<process label="Run HelloWorld.fmw with a point in Switzerland" deletebefore="./result/dbcountry.sqlite">
  <workspace>./HelloWorld.fmw</workspace>
  <parameterCollection>
    <parameter name="xy" value="6.6 46.6"/>
    <parameter name="destSpatialiteFile" value="./result/dbcountry.sqlite"/>
  </parameterCollection>
</process>

Notez la présence de l'attribut xml "deletebefore" qui permet de supprimer le jeu de données destination avant le lancement du traitement. Cet attribut n'est pas spécifié dans le <process> du second test, le second traitement chargera donc un enregistrement supplémentaire dans le fichier dbcountry.sqlite créé lors du premier test.

  • Les vérifications (<check>) demandent plus d'informations pour être définies. La première vérification permet de calculer le nombre d'entités dans le résultat du traitement (appel à l'opérateur de test featuresCount()) et de comparer cette valeur observée (comparateur "eq" correspondant à l'égalité) à la constante "1" qui est la valeur attendue. La seconde vérification consiste à rechercher la première valeur du champ name du type d'entités country dans le jeu de données résultat (./result/dbcountry.sqlite). La valeur attendue ici est Switzerland.

<checkCollection>
  <check label="Number of features in the 'country' feature type">
    <source type="datafile" format="SPATIALITE" dataset="./result/dbcountry.sqlite" request="featuresCount()" requestparams="country"/>
    <condition comparator="eq" expectedvalue="1"/>
  </check>
  <check label="Country name in the first record">
    <source type="datafile" format="SPATIALITE" dataset="result\dbcountry.sqlite" request="attributeValue()" requestparams="country,name,1"/>
    <condition comparator="eq" expectedvalue="Switzerland"/>
  </check>
</checkCollection>

3. Lancement du contrôle

Un contrôle correspond à l'exécution d'un scénario de test. Vous pouvez lancer le contrôle de plusieurs manières :

  • A partir d'une ligne de commande

fme.exe ..\scenarioPlayer.fmw --scenarioxml "./HelloWorld.xml"

  • En exécutant le fichier HelloWorld.bat

./HelloWorld.bat

  • Ou tout simplement sur Windows à partir d'un double clic sur HelloWorld.bat

Plusieurs paramètres peuvent être utilisés lors de l'appel à scenarioPlayer.fmw, ceux-ci sont documentés dans la section Lancer un contrôle avec scenarioPlayer.

Avertissement

FME Desktop 2019 ou + doit être installé sur votre poste de travail. Il peut être nécessaire de spécifier le chemin de fme.exe sur la ligne de commande ou dans HelloWorld.bat. En cas de problème, consultez le fichier de log du traitement dans le répertoire ./rtlog ou lancez le traitement en ligne de commande pour afficher les messages dans la console.

Les résultats du contrôle

Suite à l'exécution du contrôle, le répertoire ./tutorial doit contenir trois répertoires supplémentaires :

  • ./result a été créé par le projet FME HelloWorld.fmw, il est donc indépendant de rTest

  • ./rtreport a été créé par scenarioPlayer, il contient les rapports html générés lors de chaque contrôle

  • ./rtlog a été créé par scenarioPlayer, il contient les fichiers de log générés par scenarioPlayer et par les process décrits dans le scénario de test, ici HelloWorld.fmw

Le rapport généré se trouve donc dans le répertoire ./rtreport. Il porte un nom avec une marque de date telle que HelloWorld_1627559274861.html, l'historique des rapports est ainsi conservé. Le dernier rapport est également dupliqué et renommé avec une valeur fixe lastReport.html ce qui facilite la consultation dans un navigateur.

Le rapport HTML

Le rapport est une application HTML + JavaScript qui contient toutes les informations relatives au contrôle qui vient d'être effectué :

  • contrôle (date, projet, utilisateur, version de FME, lien vers le fichier de log...)

  • test (état)

  • traitements (paramètres, statut, durée, état de la mémoire, lien vers chaque fichier de log)

  • vérification (état, valeur observée, valeur attendue...)

Un clic sur un élément (process ou check) permet d'obtenir des informations supplémentaires sur le traitement ou la vérification.

Note

La description des différents états des tests est disponible sur la page Etat des tests, traitements et vérifications de la documentation.

Analyse

L'analyse du rapport montre que le premier test (Point with positive coordinates) est satisfaisant (état : Succès). Le traitement FME s'est bien déroulé et les deux vérifications indiquent que les résultats sont bien conformes aux attentes.

En revanche, il y a un problème sur le second test (Point with negative coordinates). Le traitement s'est bien déroulé mais la seconde vérification a échoué (état : Echec).

En accédant au détail du problème on voit que la valeur attendue est "Argentine" alors que la valeur observée est "Argentina".

Dans ce cas de figure, il s'agit d'une simple erreur de saisie dans le scénario de test. Pour corriger ce problème, il faut :

  • Editer HelloWorld.xml

  • Modifier la vérification :

		<condition comparator="eq" expectedvalue="Argentina"/>

  • Relancer l'exécution du scénario de test

  • Rafraichir le rapport lastReport.html dans le navigateur

Les deux premiers tests devraient être passés avec succès.

Le troisième test (Point on a border) a un statut particulier qui n'est ni "Succès", ni "Echec" mais "Erreur". Cet état est attribué lorsqu'il est impossible de comparer la valeur attendue et la valeur observée (cf.Définition des état des tests). Dans notre cas on voit que le traitement s'est bien déroulé mais que la vérification a échoué (état : Erreur)

Le message indique que le fichier attendu ./result/border.sqlite n'existe pas. Pour comprendre d'où vient le problème, il est bon d'inspecter le fichier de log de traitement FME. Celui-ci est accessible à partir du lien "Consulter le fichier de log" de la section process.

Effectivement le traitement n'a produit aucun résultat bien qu'il se soit terminé correctement.

Humm... Il semble qu'il y a un problème dans le projet HelloWorld.fmw, le développeur va devoir revoir sa copie.

Petite piste si vous voulez corriger HelloWorld.fmw : il faut ajouter le test Touches dans le transformer SpatialFilter, en plus de Within...

A vous de jouer...

Pour créer ou modifier un scénario de test, nous vous conseillons d'utiliser un éditeur XML tel que XMLSpy ou bien un outil de validation en ligne tel que Truugo.

Avertissement

Attention à ne pas verrouiller les fichiers produits par le traitement HelloWorld.fmw (dbcountry.sqlite et border.sqlite) en les laissant ouverts dans FME DataInspector ou un autre outil, sinon la suppression du fichier échouera ainsi que tout le traitement de contrôle.

  • Ajoutez un test pour vérifier la valeur de l'attribut "name" et "pop2005" lorsque le point est situé aux coordonnées (0.0 41.1). Résultat attendu : "Spain" et "43397491". Pensez à attribuer un identifiant unique au test.

  • Contrôlez la valeur de tous les attributs de l'enregistrement (name, pop2005,region, subregion ) en une seule vérification.

  • Contrôlez la valeur de la géométrie.

  • Traitez le cas du point en mer (0,0). Dans ce cas il vous faut au préalable spécifier le résultat attendu : échec du traitement ou écriture d'une information dans le fichier de log.

Correction tutoriel

Vous pouvez télécharger le fichier HelloWorld_corrected.xml qui corrige le tutoriel.

Note

Si vous voulez exécuter le fichier .xml de correction, il vous faut modifier le fichier "HelloWorld.bat" en changeant le scenario.xml appelé.