L'extension APE Template Editing propose un environnement permettant de déclarer et d'exécuter des cas de test (des tests unitaires) pour chaque template .ftlx défini dans votre répertoire de travail (le dossier ouvert par Visual Studio Code).

Comme décrit dans la page Configuration d'un environnement de programmation, l'extension offre les trois briques fonctionnelles de base pour la programmation et le test de templates :

l'éditeur textuel de fichier template,
une instance d'APE : Une application APE Spring Boot MergeTransformMicroService est embarquée avec l'extension. Celle-ci est configurée pour exécuter les cas de test définis pour chaque template développé,
un client REST : A l'instar d'Insomnia, cet outil permet d'exécuter un cas de test en envoyant une requête HTTP contenant ses données pour consommer le service Web de l'APE Spring Boot dédié à l'exécution du template. Le résultat de la requête est visualisable directement dans l'extension.

Par définition, un cas de test est l'instanciation d'un cas d'utilisation (ou use case) dans un contexte défini. Dans le cadre de l'APE un cas de test regroupe l'ensemble des données nécessaires pour décrire un cas d'utilisation d'un template exécuté à travers un service Web de l'APE Spring Boot.

Un cas de test est unique : Il est caractérisé par un nom et est associé à un seul template.

Par définition, une suite de tests est un regroupement de cas de tests : Cette suite est constituée d'un ensemble de paramètres définissant l'environnement d'exécution ainsi qu'une collection de cas de tests. Dans le cadre de l'APE, une suite de tests contient les paramètres nécessaires à la configuration et à l'exécution de l'APE Spring Boot et regroupe les cas de tests des templates définis dans l'espace de travail. Une suite de tests est unique dans un répertoire de travail.

L'interface utilisateur

L'extension APE Template Editing offre une vue dédiée à la gestion des tests. Cette vue s'active en cliquant sur l'icône présent dans la barre d'activité (située sur le côté gauche) de Visual Studio Code :

Cette vue fait apparaître dans la barre latérale quatre sous-vues arborescentes :

la vue SUITE DE TESTS : elle regroupe l'ensemble des cas de tests des templates définis dans le répertoire de travail (et ses sous-répertoires éventuels),
la vue CAS DE TEST DE TEMPLATE : elle regroupe l'ensemble des cas de tests du template actif,
la vue INFO DE CAS DE TEST : elle regroupe les informations relatives au cas de test actif,
la vue EXEC DE CAS DE TEST : elle regroupe les informations relatives à l'exécution du cas de test actif.

Lors de l'ouverture d'un répertoire de travail, si aucune suite de tests n'existe, alors la vue SUITE DE TESTS indique à l'utilisateur qu'il est nécessaire de générer un fichier suite de tests pour pouvoir créer des cas de test.

Les vues CAS DE TEST DE TEMPLATE, INFO DE CAS DE TEST et EXEC DE CAS DE TEST mettent à jour automatiquement leur contenu lorsque l'utilisateur change le document actif.

↑ Haut de page

Vue SUITE DE TESTS

Cette vue est la vue principale de la suite de tests. Lorsque aucune suite de tests n'est trouvée dans le répertoire de travail, alors cette vue indique à l'utilisateur qu'il est nécessaire de générer un fichier suite de tests pour pouvoir créer des cas de test.

Une fois créée, cette vue arborescente présente les cas de test regroupés par template. Chaque cas de test est un item terminal de l'arborescence représenté par l'icône . Le texte associé à l'item est le nom du cas de test suivi de la locale associée au cas de test. Un clic souris sur un item de cas de test déclenche l'ouverture d'un document contenant les données du cas de test et son affichage dans la zone d'édition de l'éditeur. Si le document est déjà ouvert, alors il devient le document actif.

Un item cas de test est rattaché à un item parent représenté par l'icône et dont le texte est le nom du template .ftlx associé.

Chaque item template est localisé dans l'arborescence par un chemin représentant l'espace de noms du template associé (un sous-chemin de répertoires relatif à une racine de recherche qui est le répertoire racine d'espace de noms indiqué lors de la génération du fichier suite de tests).

Le déplacement du curseur de la souris dans la zone d'affichage de la vue fait apparaître les commandes disponibles.

Commandes générales

Les commandes générales apparaissent dans la barre de titre de la vue : Elles sont accessibles soit via des icônes soit via un menu contextuel sous l'icône "...".

Commande Nouveau cas de test

Cette commande permet d'ajouter un cas de test à la suite de tests. La création d'un cas de test se fait en quatre étapes :

Etape 1 : Saisir un nom de cas de test,
Etape 2 : Saisir une description de cas de test (peut être vide),
Etape 3 : Sélectionner dans la liste proposée le template associé au cas de test. Chaque template est localisé dans son espace de noms. La liste se met automatiquement à jour en fonction du texte saisi dans le champ,.
Etape 4 : Saisir la requête HTTP du service Web de l'APE Spring Boot qui sera consommé à l'exécution du cas de test. Dans cette étape, deux aides à la saisie (placées au-dessus du champ) sont disponibles :
- L'icône (Choisir une URL de requête existante) permet de choisir une URL parmi les URL existantes (celles créées par défaut et celles créées par l'utilisateur). Lorsqu'une URL est définie avec des variables d'environnement, sa valeur expansée est affichée sur la même ligne.
- L'icône (Ajouter une variable d'environnement) permet d'ajouter en fin du texte en cours de saisie une variable d'environnement. La liste propose l'ensemble des variables définies dans l'environnement courant ainsi que celles de l'environnement de base (si elles n'ont pas été redéfinies dans l'environnement courant). Chaque ligne de la liste affiche le nom de la variable, sa valeur réelle et sa valeur expansée si elle contient d'autres variables, son origine (l'environnement dans lequel la variable a été définie ou redéfinie) et enfin son type (numérique, chaîne de caractères, booléen, nul).

Il est possible d'annuler ces aides à la saisie et de retourner à l'étape 4 en cliquant sur le bouton Précédent.

A la fin de la dernière étape, le nouveau cas de test est créé dans la vue et le document cas de test est affiché dans la zone d'édition de l'éditeur.

Il est possible à chaque étape d'annuler la création d'un nouveau cas de test en appuyant sur la touche Echap.

↑ Haut de page

Commandes du menu contextuel

Ce menu regroupe un ensemble de commandes rassemblées par thème. Certaines commandes ne sont visibles que lorsque l'éditeur est dans un contexte particulier.

Commandes de gestion de l'application APE Spring Boot

Regroupe les commandes :

Démarrer l'application APE Spring Boot (commande visible seulement si l'application est arrêtée),
Arrêter l'application APE Spring Boot (commande visible seulement si l'application est démarrée),
Redémarrer l'application APE Spring Boot (commande visible seulement si l'application est démarrée).

Ces commandes permettent de gérer le cycle de vie de l'application APE.

L'application APE Spring Boot doit être démarrée avant d'exécuter un cas de test.

Lors de la sélection d'un environnement, si celui-ci contient des variables de paramétrage des fichiers de configuration de l'APE Spring Boot, alors celle-ci doit être redémarrée pour que les paramètres définis dans l'environnement soient pris en compte.

Commande Afficher les fichiers de configuration de l'application APE

La sélection du fichier de configuration à afficher se fait à partir d'une liste contenant les fichiers freemarker.properties, application.yml et fop.xconf. Le fichier sélectionné est affiché dans la zone d'édition de l'éditeur.

Les fichiers de configuration de l'APE étant générés au démarrage de l'APE à partir des variables de paramétrage de l'environnement courant, ceux-ci sont ouverts en lecture seule et ne peuvent être modifiés par l'utilisateur.

Cette commande est visible seulement si l'application APE est démarrée.

Commandes de gestion des environnements

Regroupe les commandes :

Créer un environnement : Permet de créer un nouvel environnement dans la suite de tests en saisissant son nom. Après confirmation, le document de l'environnement est affiché dans la zone d'édition de l'éditeur.
Supprimer un environnement : Permet de supprimer un environnement de la suite de tests en sélectionnant son nom dans la liste des environnements existants. Après confirmation de la suppression, l'environnement est détruit et s'il était ouvert dans la zone d'édition de l'éditeur son document est fermé.
Editer un environnement : Permet de visualiser le contenu d'un environnement en sélectionnant son nom dans la liste des environnements existants. Après sélection par l'utilisateur, le document de l'environnement est affiché dans la zone d'édition de l'éditeur. Si l'environnement était déjà ouvert, son document devient le document actif. L'environnement de base (de nom "Base environment" et créé à la génération du fichier de suite de tests) est toujours ouvert en lecture seule et ne peut être modifié par l'utilisateur.

Commande Fermer tous les cas de test

Cette commande permet de fermer tous les documents de cas de test ouverts dans la zone d'édition de l'éditeur ainsi que tous les documents résultats de l'exécution de cas de test ouverts dans cette même zone.

Commande Recharger le fichier de suite de tests

Cette commande permet de recharger le fichier de suite de tests (utile seulement si ce fichier a été modifié en dehors de l'application Visual Studio Code). Le rechargement provoque l'arrêt de l'application APE Spring Boot si celle-ci était démarrée et la fermeture de tous les cas de test.

Commande Afficher l'aide Adélia

Affiche cette page dans le navigateur par défaut de la machine.

Lors de la demande d'ouverture de l'aide (considéré comme un lien externe), Visual Studio Code demande une confirmation d'ouverture. Pour ne pas avoir à confirmer systématiquement, il est nécessaire d'ajouter la source de l'URL du lien comme site de confiance.

Note : La gestion des sites de confiance dans Visual Studio Code se fait en activant la commande "Manage Trusted Domains" via la palette de commandes (Ctrl+Maj+P sous Windows).

Commandes d'items

Il est possible d'accéder aux commandes associées aux items de la vue arborescente SUITE DE TESTS. Seuls les items cas de test et template ont des commandes associées.

Ces commandes s'activent en déplaçant le curseur de la souris sur l'item concerné.

↑ Haut de page

Commandes d'item de type template

Commande Nouveau cas de test

Cette commande permet d'ajouter un cas de test à la suite de tests. Ce cas de test sera directement associé au template défini par l'item. La création d'un cas de test s'effectue en trois étapes :

Etape 1 : Saisir un nom de cas de test,
Etape 2 : Saisir une description de cas de test (peut être vide),
Etape 3 : Saisir la requête HTTP du service Web de l'APE Spring Boot qui sera consommé à l'exécution du cas de test. Dans cette étape, deux aides à la saisie (placées au dessus du champ) sont disponibles :
- L'icône (Choisir une URL de requête existante) permet de choisir une URL parmi les URL existantes (celles créées par défaut et celles créées par l'utilisateur). Lorsqu'une URL est définie avec des variables d'environnement, sa valeur expansée est affichée sur la même ligne.
- L'icône (Ajouter une variable d'environnement) permet d'ajouter en fin du texte en cours de saisie une variable d'environnement. La liste propose l'ensemble des variables définies dans l'environnement courant ainsi que celles de l'environnement de base (si elles n'ont pas été redéfinies dans l'environnement courant). Chaque ligne de la liste affiche le nom de la variable, sa valeur réelle et sa valeur expansée si elle contient d'autres variables, son origine (l'environnement dans lequel la variable a été définie ou redéfinie) et enfin son type (numérique, chaîne de caractères, booléen, nul).

Il est possible d'annuler ces aides à la saisie et de retourner à l'étape 3 en cliquant sur le bouton Précédent.

A la fin de la dernière étape, le nouveau cas de test est créé dans la vue (un nouvel item cas de test est créé sous l'item template) et le document cas de test est affiché dans la zone d'édition de l'éditeur.

Il est possible à chaque étape d'annuler la création d'un nouveau cas de test en appuyant sur la touche Echap.

Commandes du menu contextuel

Ce menu apparaît après un clic droit sur un item template.

Commande Ouvrir le fichier template

Ouvre le fichier associé au template (normalement accessible via la vue Explorateur de Visual Studio Code) et affiche le document dans la zone d'édition de l'éditeur. Si celui-ci est déjà ouvert, alors il devient le document actif.

Commande Fermer tous les cas de test

Cette commande permet de fermer tous les documents ouverts dans la zone d'édition de l'éditeur qui correspondent :

aux documents de cas de test associés au template se rapportant à l'item,
aux documents résultat de l'exécution de cas de test associés au template se rapportant à l'item.

Commande Supprimer tous les cas de test

Supprime de la suite de tests, après confirmation, tous les cas de test associés au template correspondant à l'item. Les documents ouverts correspondant aux cas de test concernés sont fermés.

↑ Haut de page

Commandes d'item de type cas de test

Commande Exécuter

Cette commande lance l'exécution du cas de test correspondant à l'item. Le document résultat de l'exécution est affiché dans la zone d'édition de l'éditeur.

Commandes du menu contextuel

Ce menu apparaît après un clic droit sur un item cas de test.

Commande Supprimer

Supprime de la suite de tests, après confirmation, le cas de test correspondant à l'item. Les documents ouverts correspondant au cas de test concerné sont fermés (document cas de test et document résultat de l'exécution du cas de test).

Commande Dupliquer

Cette commande permet de cloner un cas de test. Après saisie du nom du cas de test copie, le document du nouveau cas de test est affiché dans la zone d'édition de l'éditeur.

Commande Renommer

Cette commande permet de renommer un cas de test après saisie de son nouveau nom. Si le document du cas de test était ouvert, alors il est réaffiché dans la zone d'édition de l'éditeur avec son nouveau nom.

Commande Activer le data model

Cette commande permet de sélectionner ce cas de test comme data model du template associé. L'icône de l'item devient . L'ancien cas de test data model de ce même template (s'il existe) est désélectionné.

↑ Haut de page

Vue CAS DE TEST DE TEMPLATE

Cette vue regroupe l'ensemble des cas de test associé à un template. Son contenu se met à jour en fonction du document actif :

un document template, un document cas de test, un document résultat d'exécution de cas de test provoque une mise à jour de la vue,
tout autre document vide la vue.

L'arborescence de la vue est constituée d'un item template représenté par l'icône et dont le texte est le nom du template actif. Chaque cas de test est un item terminal de l'arborescence représenté par l'icône . Le texte associé à l'item est le nom du cas de test suivi de la locale associée au cas de test. Un clic souris sur un item de cas de test déclenche l'ouverture d'un document contenant les données du cas de test et son affichage dans la zone d'édition de l'éditeur. Si le document est déjà ouvert, alors il devient le document actif.

Le déplacement du curseur de la souris dans la zone d'affichage de la vue fait apparaître les commandes disponibles.

Commandes d'items

Il est possible d'accéder aux commandes associées aux items de la vue arborescente CAS DE TEST DE TEMPLATE. Ces commandes s'activent en déplaçant le curseur de la souris sur l'item concerné.

↑ Haut de page

Commandes d'item de type template

Commande Nouveau cas de test

Cette commande permet d'ajouter un cas de test à la suite de tests. Ce cas de test sera directement associé au template défini par l'item. La création d'un cas de test s'effectue en trois étapes :

Etape 1 : Saisir un nom de cas de test,
Etape 2 : Saisir une description de cas de test (peut être vide),
Etape 3 : Saisir la requête HTTP du service Web de l'APE Spring Boot qui sera consommé à l'exécution du cas de test. Dans cette étape, deux aides à la saisie (placées au dessus du champ) sont disponibles :
- L'icône (Choisir une URL de requête existante) permet de choisir une URL parmi les URL existantes (celles créées par défaut et celles créées par l'utilisateur). Lorsqu'une URL est définie avec des variables d'environnement, sa valeur expansée est affichée sur la même ligne.
- L'icône (Ajouter une variable d'environnement) permet d'ajouter en fin du texte en cours de saisie une variable d'environnement. La liste propose l'ensemble des variables définies dans l'environnement courant ainsi que celles de l'environnement de base (si elles n'ont pas été redéfinies dans l'environnement courant). Chaque ligne de la liste affiche le nom de la variable, sa valeur réelle et sa valeur expansée si elle contient d'autres variables, son origine (l'environnement dans lequel la variable a été définie ou redéfinie) et enfin son type (numérique, chaîne de caractères, booléen, nul).

Il est possible d'annuler ces aides à la saisie et de retourner à l'étape 3 en cliquant sur le bouton Précédent.

A la fin de la dernière étape, le nouveau cas de test est créé dans la vue (un nouvel item cas de test est créé sous l'item template) et le document cas de test est affiché dans la zone d'édition de l'éditeur.

Il est possible à chaque étape d'annuler la création d'un nouveau cas de test en appuyant sur la touche Echap.

Commandes du menu contextuel

Ce menu apparaît après un clic droit sur un item template.

Commande Ouvrir le fichier template

Ouvre le fichier associé au template (normalement accessible via la vue Explorateur de Visual Studio Code) et affiche le document dans la zone d'édition de l'éditeur. Si celui-ci est déjà ouvert alors il devient le document actif.

Commande Fermer tous les cas de test

Cette commande permet de fermer tous les documents ouverts dans la zone d'édition de l'éditeur qui correspondent :

aux documents de cas de test associés au template se rapportant à l'item,
aux documents résultat de l'exécution de cas de test associés au template se rapportant à l'item.

Commande Supprimer tous les cas de test

Supprime de la suite de tests, après confirmation, tous les cas de test associés au template correspondant à l'item. Les documents ouverts correspondant aux cas de test concernés sont fermés.

↑ Haut de page

Commandes d'item de type cas de test

Commande Exécuter

Cette commande lance l'exécution du cas de test correspondant à l'item. Le document résultat de l'exécution est affiché dans la zone d'édition de l'éditeur.

Commandes du menu contextuel

Ce menu apparaît après un clic droit sur un item cas de test.

Commande Supprimer

Supprime de la suite de tests, après confirmation, la cas de test correspondant à l'item. Les documents ouverts correspondant au cas de test concerné sont fermés (document cas de test et document résultat de l'exécution du cas de test).

Commande Dupliquer

Cette commande permet de cloner un cas de test. Après saisie du nom du cas de test copie, le document du nouveau cas de test est affiché dans la zone d'édition de l'éditeur.

Commande Renommer

Cette commande permet de renommer un cas de test après saisie de son nouveau nom. Si le document du cas de test était ouvert, alors il est réaffiché dans la zone d'édition de l'éditeur avec son nouveau nom.

Commande Activer le data model

Cette commande permet de sélectionner ce cas de test comme data model du template associé. L'icône de l'item devient . L'ancien cas de test data model de ce même template (s'il existe) est désélectionné.

↑ Haut de page

Vue INFO DE CAS DE TEST

Cette vue regroupe les informations relative au cas de test actif. Son contenu se met à jour en fonction du document actif :

un document cas de test, un document résultat d'exécution de cas de test provoque une mise à jour de la vue,
tout autre document vide la vue.

L'arborescence de la vue est constituée d'items permettant l'affichage et la modification des informations constitutives du cas de test :

L'item d'icône ou a pour texte le nom du cas de test. Le deuxième icône indique que ce cas de test est sélectionné comme data model.
L'item d'icône a pour texte la description du cas de test.
L'item d'icône a pour texte l'URL de la requête HTTP du cas de test. L'infobulle de l'item affiche la valeur expansée de l'URL si celle-ci contient des variables d'environnement.
.L'item d'icône a pour texte En-têtes et regroupe l'ensemble des en-têtes HTTP de la requête. Un chiffre indique la cardinalité de l'ensemble,
- Les items d'icône ont pour texte le nom de l'en-tête HTTP ainsi que sa valeur si elle est définie. L'infobulle de l'item affiche la valeur expansée de la valeur d'en-tête si celle-ci contient des variables d'environnement.

Le déplacement du curseur souris dans la zone d'affichage de la vue fait apparaître les commandes disponibles.

Commande Editer

Cette commande permet de modifier le texte d'un item. Suivant la nature de l'item cette commande permet de modifier :

le nom du cas de test en saisissant un nouveau nom dans le champ de saisie,
la description du cas de test en saisissant une nouvelle description dans le champ de saisie,
l'URL de la requête HTTP du cas de test. Pour cela, deux aides à la saisie (placées au dessus du champ de saisie de l'URL) sont disponibles :
- L'icône (Choisir une URL de requête existante) permet de choisir une URL parmi les URL existantes (celles créées par défaut et celles créées par l'utilisateur). Lorsqu'une URL est définie avec des variables d'environnement, sa valeur expansée est affichée sur la même ligne.
- L'icône (Ajouter une variable d'environnement) permet d'ajouter en fin du texte en cours de saisie une variable d'environnement. La liste propose l'ensemble des variables définies dans l'environnement courant ainsi que celles de l'environnement de base (si elles n'ont pas été redéfinies dans l'environnement courant). Chaque ligne de la liste affiche le nom de la variable, sa valeur réelle et sa valeur expansée si elle contient d'autres variables, son origine (l'environnement dans lequel la variable a été définie ou redéfinie) et enfin son type (numérique, chaîne de caractères, booléen, nul).
Un en-tête de la requête HTTP (son nom et / ou sa valeur). La modification se fait en deux étapes de saisie :
- Etape 1 : Modification du nom de l'en-tête,
- Etape 2 : Modification de la valeur de l'en-tête. Pour cela, une aide à la saisie (placées au dessus du champ de saisie) est disponible :
  - L'icône (Ajouter une variable d'environnement) permet d'ajouter en fin du texte en cours de saisie une variable d'environnement. La liste propose l'ensemble des variables définies dans l'environnement courant ainsi que celles de l'environnement de base (si elles n'ont pas été redéfinies dans l'environnement courant). Chaque ligne de la liste affiche le nom de la variable, sa valeur réelle et sa valeur expansée si elle contient d'autres variables, son origine (l'environnement dans lequel la variable a été définie ou re-définie) et enfin son type (numérique, chaîne de caractères, booléen, nul).

Commande Supprimer

Cette commande n'est disponible que pour les items d'en-têtes. Elle permet, après confirmation, de supprimer un en-tête de l'ensemble des en-têtes de la requête HTTP.

Commande Ajouter

Cette commande n'est disponible que pour l'item En-têtes. Elle permet d'ajouter un nouvel en-tête à l'ensemble des en-têtes de la requête HTTP. L'ajout se fait en deux étapes :

Etape 1 : Saisir le nom de l'en-tête,
Etape 2 : Saisir la valeur de l'en-tête. Pour cela, une aide à la saisie (placées au dessus du champ de saisie) est disponible :
- L'icône (Ajouter une variable d'environnement) permet d'ajouter en fin du texte en cours de saisie une variable d'environnement. La liste propose l'ensemble des variables définies dans l'environnement courant ainsi que celles de l'environnement de base (si elles n'ont pas été redéfinies dans l'environnement courant). Chaque ligne de la liste affiche le nom de la variable, sa valeur réelle et sa valeur expansée si elle contient d'autres variables, son origine (l'environnement dans lequel la variable a été définie ou redéfinie) et enfin son type (numérique, chaîne de caractères, booléen, nul).

↑ Haut de page

Vue EXEC DE CAS DE TEST

Cette vue regroupe les informations relatives à l'exécution du cas de test actif.

L'arborescence de la vue est constituée d'items permettant l'affichage des informations relatives à l'exécution :

L'item d'icône ou a pour texte le code retour de la requête HTTP exécutée,
L'item d'icône a pour texte le temps d'exécution de la requête,
L'item d'icône a pour texte la taille de la réponse de la requête,
L'item d'icône a pour texte En-têtes et regroupe l'ensemble les en-têtes HTTP de la réponse de la requête. Un chiffre indique la cardinalité de l'ensemble,
- Les items d'icône ont pour texte le nom de l'en-tête HTTP ainsi que sa valeur.

Cette vue est en lecture seule et aucune commande n'est disponible.

↑ Haut de page

Création d'une suite de tests

L'ajout de cas de test nécessite au préalable la création d'une suite de tests. Cette action s'effectue dans la vue SUITE DE TESTS (lorsque celle-ci détecte qu'aucune suite de tests n'est présente dans le dossier de travail) en cliquant sur le bouton Le générer avant de créer des cas de test : L'utilisateur doit sélectionner un sous-répertoire (du dossier de travail) qui servira de racine d'espace de noms. Le chemin absolu de ce sous-répertoire sera pris comme racine de recherche du chargeur de templates FreeMarker de type "système de fichiers" qui servira à l'exécution de l'application APE Spring Boot.

Le choix de ce répertoire implique que l'ensemble des templates à tester doivent se trouver sous ce répertoire : si un template se trouve en dehors de ce répertoire, alors il n'est pas possible de lui associer un cas de test. Pour choisir le dossier de travail comme racine de recherche, il faut sélectionner le sous-répertoire "\" dans la liste.

Le fichier de la suite de tests est créé dans le sous-répertoire .apetest du dossier de travail. Ce fichier nommé apetestsuite.json (au format JSON) contient toutes les informations de la suite de tests :

l'ensemble des cas de test créés,
l'ensemble des environnements créés,
l'ensemble des paramètres de l'APE Spring Boot

↑ Haut de page

Gestion des environnements

Un environnement est un contexte d'exécution paramétrable à l'aide de variables d'environnement. L'utilisateur a la possibilité de créer / supprimer / éditer ses propres environnements. Ceux-ci sont stockés dans le fichier de la suite de tests.

Un environnement est défini par un objet JSON dont les noms d'attributs définissent les variables de l'environnement. Chaque variable a pour type booléen, numérique ou alphanumérique.

Lors de l'édition d'un environnement (via la commande Editer), un document au format JSON ayant pour nom le nom de l'environnement et pour contenu les données de celui-ci est ouvert dans la zone d'édition de l'éditeur.

Une aide à la saisie (autocomplétion avec la combinaison de touches Ctrl + Espace, aide contextuelle lors du survol d'un attribut avec la souris, etc.) est disponible pour l'édition d'un environnement.

Environnement de base

Lors de la création d'une suite de tests, il existe par défaut un environnement de base nommé "Base environment" qui contient les variables suivantes :

hostname : Nom d'hôte de la machine cible vers laquelle sont envoyées les requêtes HTTP d'exécution des cas de test. La valeur de cette variable est "localhost".
http_port : Numéro de port HTTP vers laquelle sont envoyées les requêtes HTTP d'exécution des cas de test. La valeur de cette variable est 8080.
context_path : Chemin utilisé dans la requête HTTP pour accéder au service Web d'exécution du cas de test. La valeur de cette variable est "/ape".
api_version : Version des services Web de l'APE Spring Boot. La valeur de cette variable est "v1".
base_url : Partie de la requête HTTP constituée des variables hostname, http_port et context_path. La valeur de cette variable est "http://{{{hostname}}}:{{{http_port}}}{{{context_path}}}".
root_log_level : Niveau global de trace de l'APE Spring Boot. La valeur de cette variable est "WARN".

Par défaut, l'URL de la requête HTTP du service Web de l'APE Spring Boot qui sera consommé à l'exécution du cas de test est "{{{base_url}}}/{{{api_version}}}/<ws_name> avec ws_name valant "mergeandtransform" ou "mergedoc" suivant les cas de test.

Variable d'environnement

Dans un environnement, une variable peut être définie soit par une valeur littérale (valeur booléenne true / false, valeur numérique, valeur alphanumérique) soit à l'aide d'autres variables. Dans ce cas, il est nécessaire d'utiliser la notation {{{ ref_variable }}} (entourer le nom d'une variable avec une triple paire d'accolades) pour faire référence à la valeur d'une variable dans la définition d'une autre variable.

Lorsqu'une variable est définie en utilisant d'autres variables, alors elle est nécessairement du type alphanumérique.

Par exemple, dans l'environnement suivant :

{
"temperature": 23,
"unit": "°C",
"label": "The temperature is {{{temperature}}} {{{unit}}}"
}

La variable "label" est définie à l'aide des deux autres variables "temperature" et "unit" et sa valeur expansée (ou déduite) est la chaîne alphanumérique "The temperature is 23 °C".

Dans l'environnement de base, la valeur expansée de la variable base_url est "http://localhost:8080/ape" et l'URL par défaut des services Web est "http://localhost:8080/ape/v1/<ws_name>".

Il est possible d'utiliser une variable appartenant à l'environnement courant :

dans la phase de saisie de l'URL d'une requête lors de la création d'un cas de test,
dans la phase de saisie d'une valeur d'en-tête HTTP lors de l'édition / ajout d'en-têtes.

Surcharge de variable

Lorsqu'un utilisateur crée un nouvel environnement, celui-ci hérite des variables de l'environnement de base.

Dans ce nouvel environnement l'utilisateur peut définir une variable dont la valeur fait référence à une variable de l'environnement de base. De plus, il peut redéfinir (ou surcharger) la valeur d'une variable de l'environnement de base en la redéclarant dans son environnement.

Par exemple, dans l'environnement suivant :

{
"http_port": 8081,
"mergeandtransform_url": "{{{base_url}}}/{{{api_version}}}/mergeandtransform"
}

la valeur expansée de la variable "margeandtransform_url" est " http://localhost:8081/ape/v1/mergeandtransform" : la variable http_port est surchargée et les autres variables base_url et api_version sont héritées.

Environnement courant

L'exécution d'un cas de test est associé à un contexte d'exécution. Par défaut, le contexte d'exécution est lié à l'environnement de base. La barre d'état de Visual Studio Code indique, par l'icône l'environnement en cours d'utilisation :

"Pas d'environnement" signifie que l'environnement de base est l'environnement courant. Il est possible de changer l'environnement courant en cliquant sur l'icône : Le nouvel environnement doit être sélectionné dans la liste des environnements proposés.

Suivant la nature des variables définies et / ou surchargées dans le nouvel environnement courant, il peut être nécessaire de redémarrer l'APE Spring Boot pour prendre en compte le nouveau contexte d'exécution (par exemple, changement du port HTTP, changement du niveau de trace, etc.).

↑ Haut de page

Gestion de l'application APE Spring Boot

Cette application est embarquée avec l'extension. Elle expose l'ensemble des services Web de l'APE pour l'exécution des cas de test.

L'utilisateur gère ponctuellement le cycle de vie de cette application via des commandes de démarrage, d'arrêt et de redémarrage (l'application n'est pas installée en tant que service).

Pour pouvoir exécuter l'APE Spring Boot il est nécessaire d'avoir installé un JDK ou JRE Java 1.8 minimum. La recherche d'un JDK / JRE s'effectue dans cet ordre :

recherche si l'option "Ape Spring Boot: Java Path" dans les paramètres de l'extension APE Template Editing est renseignée (cette option permet de spécifier le chemin racine d'un JDK ou JRE),
recherche l'existence dans le système d'exploitation de la machine de la variable d'environnement JAVA_HOME,
recherche l'existence d'un exécutable "java.exe" dans la liste des chemins définis par la variable d'environnement système PATH.

Par défaut, l'exécution d'un cas de test n'est possible que si l'APE Spring Boot est démarrée (voir l'option de paramétrage Ape Spring Boot: Automatic Start App Executing Test Case ). En cas de démarrage automatique et en fonction des performances de la machine hôte, il peut être nécessaire d'augmenter le temps d'attente de démarrage (voir l'option de paramétrage Ape Spring Boot: Waiting Time Before Executing Test Case ).

Le canal de sortie de l'APE Spring Boot

Lors du démarrage de cette application, un canal de sortie est créé pour afficher les traces de sortie produites par l'exécution des cas de test. Ce canal nommé "APE application", est affiché dans l'onglet "SORTIE" de l'aire Panneau dans l'interface Visual Studio Code :

Le niveau global de trace de l'APE Spring Boot est indiqué par la variable d'environnement root_log_level. Il est possible de surcharger cette valeur dans un nouvel environnement (les valeurs possibles sont TRACE, DEBUG, INFO, WARN, ERROR et FATAL).

De plus, il est possible de configurer (dans les options de paramétrage de l'extension) les couleurs et les styles de texte à appliquer aux différents niveaux de trace dans le canal de sortie.

Enfin, il est possible de vider le contenu du canal de sortie via la commande "Effacer la sortie" disponible dans le menu contextuel de la fenêtre du canal de sortie.

La commande de démarrage de l'APE affiche dans le canal de sortie la bannière de l'Adélia Print Engine.

La commande d'arrêt de l'APE affiche dans le canal de sortie le texte "Adelia Print Engine is shutdown".

L'exécution d'un cas de test peut produire dans le canal de sortie des traces de différents niveaux.

Etat de l'APE Spring Boot

Il est possible de connaître à tout moment l'état courant de l'application dans la barre d'état de Visual Studio Code :

Paramétrage de l'APE Spring Boot

Comme indiqué dans la section Options de lancement, l'application est configurable à l'aide des fichiers de configuration suivants :

application.yml (configuration Spring Boot),
freemarker.properties (configuration du moteur FreeMarker),
fop.xconf (configuration Apache FOP).

Au démarrage de l'application, ces trois fichiers sont automatiquement générés et sont chargés par celle-ci. La génération de ces fichiers s'appuie sur des informations paramétrables.

Paramétrage de application.yml

Dans ce fichier au format YAML, les attributs server.port, server.servlet.context-path et logging.level.ROOT sont mappés respectivement avec les variables d'environnement http_port, context_path et root_log_level.

Il est possible de particulariser un niveau de trace par package Java. Pour cela, la variable d'environnement applicationYaml.logging.level peut être définie comme suit :

"applicationYaml": {
	"logging": {
		"level": [
			{
				"package": "com.hardis.adelia.mergedocengine",
				"level": "DEBUG"
			},
			{
				"package": "com.hardis.adelia.transformxslfoengine",
				"level": "DEBUG"
			}
		]
	}
}

L'attribut "level" est une séquence d'objets définis par deux attributs :

package : prend le nom d'un package Java dont on veut affecter un niveau de trace,
level : le niveau de trace à fixer pour ce package

Dans cet exemple, on applique le niveau de trace DEBUG à l'ensemble des classes Java définies dans les deux packages com.hardis.adelia.mergedocengine et com.hardis.adelia.transformxslfoengine.

↑ Haut de page

Paramétrage de freemarker.properties

Dans ce fichier au format Properties, il est possible de particulariser certaines valeurs de propriétés, à savoir :

boolean_format,
default_encoding,
locale,
log_template_exceptions,
template_exception_handler,
template_update_delay,
wrap_unchecked_exceptions

Pour cela, la variable d'environnement freemarkerProp peut être définie de la façon suivante (en définissant les variables choisies) :

"freemarkerProp": {
	"boolean_format": "yes,no",
    "default_encoding": "UTF-8",
    "locale": "fr",
    "log_template_exceptions": false,
    "template_exception_handler": "debug",
    "template_update_delay": "5s",
    "wrap_unchecked_exceptions": false
}

Paramétrage de fop.xconf

Dans ce fichier au format XML, il est possible de particulariser certaines valeurs de propriétés, à savoir :

source-resolution,
target-resolution,
default-page-settings

Pour cela, la variable d'environnement fopXconf peut être définie de la façon suivante (en définissant les variables choisies) :

"fopXconf": {
	"source_resolution": 96,
	"target_resolution": 96,
	"default_page_settings": {
		"height": "29.7cm",
		"width": "21cm"
	}
}

Commande Afficher les fichiers de configuration de l'application APE

Cette commande déclenche l'ouverture d'un document contenant les données du fichier généré dans la zone d'édition de l'éditeur. Chaque document a le nom et le type du fichier sélectionné.

Si l'environnement courant contient des variables de paramétrage, alors leurs valeurs sont expansées dans le fichier généré (le document affiche le fichier résultat).

↑ Haut de page

Gestion du data model

Lors du développement d'un template, il est possible de fournir une aide à la saisie du data model d'un template. Pour cela, l'utilisateur doit produire un fichier JSON spécifique de nom <template_name>_dmodel.json.

Grace à la suite de tests, l'utilisateur peut utiliser les données définies dans un cas de test comme data model du template associé. Il ne peut y avoir qu'un seul cas de test data model parmi l'ensemble des cas de test d'un template.

Lorsqu'un cas de test est défini comme data model d'un template, alors ses données remplacent celles définies dans le fichier <template_name>_dmodel.json s'il existe (priorité est donnée au cas de test sur le fichier data model).

Dans ce cas, l'icône de l'item cas de test dans les vues SUITE DE TESTS et CAS DE TEST DE TEMPLATE est .

De même, l'icône du nom du cas de test dans la vue INFO DE CAS DE TEST est .

L'information des cas de test sélectionnés comme data model est stockée dans la suite de tests.

Création d'un cas de test

Par définition, un cas de test regroupe l'ensemble des données nécessaires pour décrire un cas d'utilisation d'un template exécuté à travers un service Web de l'APE Spring Boot. Il est identifié par les informations suivantes :

un nom (obligatoire),
une description (optionnelle),
les informations relatives à l'appel et à l'exécution du service Web concerné, à savoir :
- une URL d'accès (obligatoire),
- des en-têtes HTTP (optionnels),
- un payload : un message au format JSON stocké dans le corps de la requête HTTP. Dans ce message JSON on trouve principalement :
  - un data model (obligatoire),
  - un nom de template (obligatoire),
  - un namespace (optionnel),
  - une locale (optionnel).

La création d'un cas de test peut être initiée soit dans la vue Explorateur de Visual Studio Code, soit dans les vues SUITE DE TESTS ou CAS DE TEST DE TEMPLATE de l'extension APE Template Editing.

De plus, l'utilisateur a la possibilité de supprimer / dupliquer / renommer un cas de test.

Edition d'un cas de test

Lors de l'édition d'un cas de test, un document portant le nom de celui-ci est ouvert et affiché dans la zone d'édition de l'éditeur. Ce document, au format JSON, contient le payload de la requête HTTP envoyée pour exécuter ce cas de test.

Une aide à la saisie (autocomplétion avec la combinaison de touches Ctrl + Espace, aide contextuelle lors du survol d'un attribut avec la souris, etc.) est disponible pour l'édition du payload.

De plus, une analyse syntaxique est effectuée en cours de saisie du document. Celle-ci peut détecter deux types de problèmes : les avertissements et les erreurs. Lorsque ceux-ci sont détectés, ils sont affichés dans l'onglet "PROBLÈMES" de l'aire Panneau dans l'interface Visual Studio Code :

Lorsqu'un problème est détecté sur un cas de test, alors l'icône de l'item de celui-ci dans l'arborescence des vues SUITE DE TESTS et CAS DE TEST DE TEMPLATE est ou suivant le type du problème :

Lors d'une sauvegarde par l'utilisateur, le contenu du document associé au cas de test est sauvegardé dans le fichier suite de tests. Il est nécessaire de le sauvegarder avant d'exécuter le cas de test associé.

Les commandes

Un document cas de test a des commandes associées disposées dans la barre d'onglets des document ouverts dans la zone d'édition de l'éditeur Visual Studio Code. Ces commandes ne sont accessibles que lorsque le document actif est un document de cas de test.

Commande Exécuter le cas de test

Cette commande est identique aux commandes "Exécuter" des vues SUITE DE TESTS et CAS DE TEST DE TEMPLATE.

Commande Générer le code client

Elle est disponible via un menu contextuel accessible sous l'icône "..." et permet d'afficher le code source de l'exécution du cas de test sous la forme de l'appel du service Web concerné.

L'utilisateur choisit dans une liste le langage de programmation cible ainsi que la bibliothèque de code utilisée pour implémenter l'appel du service Web. Plusieurs langages de programmation sont disponibles :

Adélia langue française (utilisation de l'ordre EXECUTER_HTTP),
Adélia langue anglaise (utilisation de l'ordre EXECUTE_HTTP),
Java,
Go,
C,
PHP,
Python,
etc.

Après sélection du langage cible, un document contenant le code de l'implémentation de l'appel au service Web pour le cas de test est ouvert et affiché dans la zone d'édition de l'éditeur Visual Studio Code.

Ce document a pour nom le nom du cas de test suivi de "[Client code]". Lorsque ce document est actif, il est possible de changer le langage cible en cliquant sur le libellé du langage choisi dans la barre d'état de Visual Studio Code :

↑ Haut de page

Exécution d'un cas de test

L'exécution d'un cas de test consiste à appeler le service Web concerné via la requête associée construite à partir des en-têtes et du payload défini dans le cas de test, puis à restituer le résultat du traitement contenu dans la réponse de la requête sous la forme d'un document visualisable par l'utilisateur.

Le déclenchement de l'exécution se fait via les différences commandes "Exécuter" décrites plus haut et l'exécution en cours d'un cas de test est indiquée par l'animation dans la barre d'état de Visual Studio Code :

De plus, l'exécution peut produire des traces dans le canal de sortie de l'APE Spring Boot.

A la fin de l'exécution, des informations sur le résultat de celle-ci sont affichées dans la vue EXEC DE CAS DE TEST.

La restitution du résultat de l'exécution produit un document qui est affiché dans la zone d'édition de l'éditeur. Par défaut, l'exécution des cas de test est restituée dans un unique document : Un seul document résultat est ouvert pour toutes les exécutions de tous les cas de test et le document résultat de la dernière exécution sera remplacé par le document résultat de la prochaine exécution. L'option "Test Case Result Preview: Single Viewer Of The Test Case Result Document" dans les paramètres de l'extension APE Template Editing permet d'associer un document résultat pour chaque cas de test exécuté.

Suivant le code retour du résultat de l'exécution (le code retour de la requête HTTP), un document est soit un document d'erreur, soit un document résultat.

Document d'erreur

Un document d'erreur restitue les erreurs liées à l'exécution d'un cas de test généralement produites par l'APE Spring Boot. Il s'agit d'un document au format JSON dont le nom est celui du cas de test exécuté, préfixé par "Preview ". L'erreur décrite dans le contenu de ce document va de pair avec les traces d'erreur produites dans le canal de sortie de l'APE Spring Boot :

Document résultat

Lorsque l'exécution s'effectue sans erreur, le résultat produit par le service Web appelé est un document au format défini par l'attribut mimeType ou outputMimeType du payload de la requête et dont le nom est celui du cas de test, prefixé par "Preview ".

Lorsque qu'un document résultat est actif, les informations sur la taille du document et sur le temps d'exécution du cas de test sont affichées dans la barre d'état de Visual Studio Code (ces informations sont aussi disponibles dans la vue EXEC DE CAS DE TEST) :

Par défaut, plusieurs formats sont supportés pour afficher le contenu du document en mode Aperçu (le contenu est interprété et est affiché de la même manière qu'un lecteur spécialisé), à savoir :

PDF : le document est affiché de la même façon d'Acrobat Reader ou qu'un navigateur Internet,
HTML : le document est affiché de la même façon qu'un navigateur Internet,
XML : le document est correctement indenté pour une lecture plus facile, avec la possibilité d'expanser / réduire les noeuds,
CSV : les données sont affichées et indentées sous la forme de colonnes,
PNG, JPEG : l'image est visualisée,
JSON : le document est correctement indenté pour une lecture plus facile, avec la possibilité d'expanser / réduire les objets et les tableaux,

Quelques exemples d'affichage de documents en mode Aperçu :

Lorsqu'aucun mode Aperçu n'est disponible pour le format du document résultat, alors le contenu de celui-ci est affiché sous la forme des données brutes.

Les commandes d'un document résultat

Un document résultat a des commandes associées disposées dans la barre d'onglets des document ouverts dans la zone d'édition de l'éditeur Visual Studio Code. Ces commandes ne sont accessibles que lorsque le document actif est un document résultat.

Commande Sauvegarder les données brutes

Elle permet de sauvegarder sous la forme d'un fichier le contenu du document résultat. Une boîte de dialogue permet à l'utilisateur de sélectionner le dossier qui contiendra le fichier. Par défaut, le nom du fichier contient le nom du cas de test et a l'extension associée au format du document résultat.

Commande Afficher le cas de test

Elle permet d'afficher le cas de test associé au document résultat. Cette commande déclenche l'ouverture d'un document contenant les données du cas de test et son affichage dans la zone d'édition de l'éditeur. Si le document est déjà ouvert, alors il devient le document actif.

Commande Données brutes

Elle permet de basculer le document en mode d'affichage des données brutes lorsque le document résultat est en mode Aperçu. Le nouveau document a pour nom le nom du cas de test préfixé par "Raw ".

Commande Apercu des données

Elle permet de basculer le document en mode Aperçu lorsque le document résultat est en mode affichage des données brutes. Le nouveau document a pour nom le nom du cas de test préfixé par "Preview ".

↑ Haut de page

Test des templates APE

L'interface utilisateur

Vue SUITE DE TESTS

Commandes générales

Commande Nouveau cas de test

Commandes du menu contextuel

Commandes de gestion de l'application APE Spring Boot

Commande Afficher les fichiers de configuration de l'application APE

Commandes de gestion des environnements

Commande Fermer tous les cas de test

Commande Recharger le fichier de suite de tests

Commande Afficher l'aide Adélia

Commandes d'items

Commandes d'item de type template

Commande Nouveau cas de test

Commandes du menu contextuel

Commande Ouvrir le fichier template

Commande Fermer tous les cas de test

Commande Supprimer tous les cas de test

Commandes d'item de type cas de test

Commande Exécuter

Commandes du menu contextuel

Commande Supprimer

Commande Dupliquer

Commande Renommer

Commande Activer le data model

Vue CAS DE TEST DE TEMPLATE

Commandes d'items

Commandes d'item de type template

Commande Nouveau cas de test

Commandes du menu contextuel

Commande Ouvrir le fichier template

Commande Fermer tous les cas de test

Commande Supprimer tous les cas de test

Commandes d'item de type cas de test

Commande Exécuter

Commandes du menu contextuel

Commande Supprimer

Commande Dupliquer

Commande Renommer

Commande Activer le data model

Vue INFO DE CAS DE TEST

Commande Editer

Commande Supprimer

Commande Ajouter

Vue EXEC DE CAS DE TEST

Création d'une suite de tests

Gestion des environnements

Environnement de base

Variable d'environnement

Surcharge de variable

Environnement courant

Gestion de l'application APE Spring Boot

Le canal de sortie de l'APE Spring Boot

Etat de l'APE Spring Boot

Paramétrage de l'APE Spring Boot

Paramétrage de application.yml

Paramétrage de freemarker.properties

Paramétrage de fop.xconf

Commande Afficher les fichiers de configuration de l'application APE

Gestion du data model

Création d'un cas de test

Edition d'un cas de test

Les commandes

Commande Exécuter le cas de test

Commande Générer le code client

Exécution d'un cas de test

Document d'erreur

Document résultat

Les commandes d'un document résultat

Commande Sauvegarder les données brutes

Commande Afficher le cas de test

Commande Données brutes

Commande Apercu des données