Personnalisation des scripts pour les moniteurs d’API multi-étapes

Les moniteurs d’API s’accompagnent de nombreuses fonctionnalités : réalisation de vérifications (au moyen d’assertions), stockage temporaire de valeurs pour une utilisation ultérieure (au moyen de variables), transformation de valeurs (au moyen de fonctions système), voire intégration de votre propre logique (au moyen des fonctions définies par l’utilisateur). Grâce à cet ensemble de fonctionnalités, le moniteur d’API est une solution puissante qui fonctionne sans code.

Cependant, bien qu’elle soit très commode pour configurer vos moniteurs, l’approche sans code ne vous permet pas toujours d’aller suffisamment dans le détail. C’est particulièrement le cas lorsque vous devez effectuer des tests fonctionnels, qui nécessitent de préciser une logique personnalisée qui ne peut être exprimée avec une configuration reposant sur une interface utilisateur. Votre langage de script doit exprimer et décrire clairement ce que vous attendez de vos API. Avec le monitoring d’API, c’est possible !

En réalité, vous pouvez même associer les fonctionnalités sans code classiques telles que les assertions et les variables avec leurs équivalents sous forme de script. Si vous avez besoin d’utiliser la fonction de scripts avec des moniteurs d’API utilisant des assertions et des variables, vous ne devez pas recréer complètement vos moniteurs. Vous pouvez commencer par ajouter de petites sections de script et les associer aux vérifications et variables existantes.

Deux éditeurs de scripts : pré-requête et post-réponse

Un moniteur d’API peut exécuter une seule étape, ou plusieurs étapes à la suite. Cependant, chaque étape (à l’exception des étapes d’attente) est composée d’une phrase de préparation, qui configure la requête HTTP pour cette étape, et d’une phase de vérification, qui traite la réponse HTTP renvoyée par l’API. Ces deux phases peuvent avoir leur propre script :

• Le script de pré-requête s’exécute avant que la requête HTTP soit pleinement construite et exécutée.
  Il est très utile pour préparer et calculer des valeurs à inclure dans la requête, comme les paramètres d’URL, les en-têtes de requête ou le contenu du corps de requête.

• Le script de post-réponse s’exécute après que la réponse HTTP correspondante a été entièrement reçue, et après le traitement des assertions et des variables dans l’onglet Réponse.
  Ce script permet d’intégrer votre logique personnalisée pour la vérification des en-têtes de réponse, de vérifier que votre contenu est complet et cohérent, et d’utiliser ce contenu pour préparer les étapes suivantes.

Comme visible dans la capture d’écran suivante, les deux types de scripts possèdent leur propre onglet dans l’éditeur du moniteur d’API. Chaque onglet possède un éditeur de code doté de fonctions de numérotation, de mise en surbrillance et d’auto-complétion, ainsi que d’un panneau latéral contenant des extraits de code. Pour commencer, vous pouvez cliquer sur n’importe quel extrait pour insérer du code dans l’éditeur.

Onglets Requête, Pré-Requête, Réponse et Post-Réponse dans l’étape 1.

Utilisation de JavaScript avec les extensions de monitoring

Les scripts de pré-requête et de post-réponse configurables dans le moniteur d’API vous permettent d’exécuter du code JavaScript. En plus des nombreuses capacités offertes par JavaScript, des fonctions spéciales sont disponibles pour accéder aux données pertinentes pour configurer des requêtes (pendant la phase de pré-requête), traiter les réponses (pendant la phase de post-réponse), réaliser des tests sur ces données, exécuter les instructions de log (pour le débogage ou pour récupérer des informations) et stocker les données calculées sous forme de métriques personnalisées.

Ces fonctions spéciales sont disponibles via un objet spécial appelé ut. Les différentes sections de la suite de cet article contiennent une description complète de chaque fonction et attribut disponible dans l’objet ut. Commençons toutefois par examiner la structure dans son ensemble :

• ut.request et ut.response vous donnent accès aux objets de la requête d’API et de la réponse d’API, soit les objets les plus importants à chaque étape.

• ut.variables désigne la collection de variables qui peut être utilisée dans tout le scénario d’API, toutes étapes comprises. Vous utilisez cette fonction pour faire passer des valeurs d’une étape à la suivante. Si vous créez des variables prédéfinies, elles seront ajoutées à cette collection de variables. Toute variable classique (sans code) utilisée dans l’onglet Réponse interagira aussi avec cette même collection de variables.

• ut.log() est une fonction helper qui extrait du texte vers une fenêtre de log. Elle est utile pour écrire temporairement du texte et des valeurs dans le log, tout en écrivant ou en déboguant vos scripts.

• ut.test() est la principale fonction de saisie du résultat du test. Le résultat de test que vous définissez à l’intérieur de chaque appel ut.test() est enregistré et ajouté en tant que résultat d’assertion, juste à côté des assertions classiques (sans code) que vous définissez.

• ut.customMetrics est une collection qui peut être remplie pendant l’écriture de vos scripts avec des valeurs numériques provenant directement d’une réponse d’API ou d’une valeur calculée, que vous souhaitez capturer en tant que métrique. Cette valeur s’affiche pour chaque mesure dans les détails de vérification du moniteur, et peut aussi être listée et présentée sur les dashboards.

Requête

Attributs qui décrivent la définition de la requête d’API dans l’étape actuelle.

Attributs de ut.request :

• .url (obtient ou définit l’URL de requête)

• .method (obtient ou définit la méthode HTTP de la requête, par exemple GET, POST, etc.)

• .body (obtient ou définit une version sous forme de texte brut du corps de la requête)

En-têtes de requête

Fonctions de ut.request.headers:

• .has(header) : indique si l’en-tête existe

• .get(header) : indique la valeur de l’en-tête ou une chaîne vide si l’en-tête n’existe pas

• .add(header, value) : ajoute l’en-tête avec la valeur spécifiée

Réponse

Attributs de ut.request :

• .code (obtient le code de statut numérique de la réponse HTTP, par exemple 200)

• .status (obtient la description du statut HTTP, par exemple OK)

• .responseSize (obtient la taille de la réponse en octets)

Fonctions de ut.request :

• .text() : renvoie une version sous forme de texte brut du corps de la réponse

• .json() : renvoie un objet en analysant le texte de la réponse sous format JSON

En-têtes de réponse

Fonctions de ut.response.headers:

• .has(header) : indique si l’en-tête existe

• .get(header) : indique la valeur de l’en-tête ou une chaîne vide s’il n’existe pas

Variables

Fonctions de ut.variables :

• .has(key) : indique si l’en-tête existe

• .get(key) : indique la valeur de la variable ou une chaîne vide si elle n’existe pas

• .set(key, value) : crée la variable si nécessaire et enregistre la valeur spécifiée

Métriques personnalisées

Fonctions de ut.customMetrics :

• .get(key): indique la valeur de la métrique personnalisée ou une chaîne vide si elle n’existe pas

• .set(key, value) : enregistre la valeur de la métrique personnalisée

Journal

• ut.log(text) : extrait le journal spécifié vers le journal de la console : le log de la requête s’il est exécuté dans le script de pré-requête et le log de la réponse s’il est exécuté dans le script de post-réponse.

Test/Assertion

Nous prenons en charge les interfaces Expect et Should de Chai JS. Lisez Chai - Should et Chai - Expect pour en savoir plus sur l’expression des tests de valeur et des comparaisons.

• ut.expect(value) + différentes expressions

• ut.should(value) + différentes expressions

Si elles sont utilisées seules et que les critères ne sont pas remplis, les expressions .expect() et .should() génèrent une erreur qui interrompt l’exécution du moniteur. Toute autre assertion figurant dans le restant du script ne sera pas exécutée. Pourtant, dans la plupart des cas, vous souhaitez exécuter l’ensemble des assertions, et ce, malgré l’échec possible de l’une d’entre elles. Pour cela, vous pouvez utiliser ut.test():

• ut.test(descriptionText, testFunction) : le résultat (succès ou échec) d’une assertion .expect ou .should définie dans la fonction spécifiée testFunction est présentée dans les résultats des assertions du moniteur. De plus, lorsqu’une assertion échoue, la fonction ut.test() garantit que l’exécution du script n’est pas interrompue.