Bonjour à tous ! Aujourd'hui, nous souhaitons présenter à la communauté IT notre produit — un IDE pour travailler avec des API TestMace. Certains d'entre vous nous connaissent peut-être déjà grâce à des articles précédents. Cependant, il n'y a pas eu de revue complète de l'outil, donc nous allons corriger ce regrettable oubli.

Motivation

Nous aimerions commencer par expliquer comment nous en sommes arrivés là et pourquoi nous avons décidé de créer notre propre outil pour un travail avancé avec les API. Commençons par la liste des fonctionnalités que devrait avoir un produit qu'on peut appeler « IDE pour travailler avec des API » :

• Création et exécution de requêtes et de scripts (séquences de requêtes)
• Rédaction de divers tests
• Génération de tests
• Travail avec la documentation des API, y compris l'importation de formats tels que Swagger, OpenAPI, WADL, etc.
• Mocking des requêtes
• Bonne prise en charge d'un ou plusieurs langages de programmation pour l'écriture de scripts, y compris l'intégration avec des bibliothèques populaires
• etc.

La liste peut être complétée selon les préférences. Il est également important de créer non seulement l'IDE lui-même, mais aussi une infrastructure particulière, comme la synchronisation dans le cloud, des outils en ligne de commande, un service de surveillance en ligne, etc. Finalement, les tendances des dernières années nous dictent non seulement une fonctionnalité puissante pour l'application, mais aussi une interface agréable.

Pour qui cet outil est-il utile ? Évidemment, pour tous ceux qui sont d'une manière ou d'une autre liés au développement et aux tests d'API — développeurs et testeurs =). En effet, pour les premiers, il suffit souvent d'exécuter des requêtes isolées et des scénarios simples, tandis que pour les testeurs, c'est l'un des principaux outils qui, en plus, doit inclure un puissant mécanisme d'écriture de tests avec la possibilité de les exécuter en CI.

Ainsi, en suivant ces repères, nous avons commencé à créer notre produit. Voyons ce que nous avons réussi à réaliser à ce stade.

Démarrage rapide

Commençons par une première découverte de l'application. Vous pouvez la télécharger sur notre site. Actuellement, toutes les 3 principales plateformes sont supportées — Windows, Linux, MacOS. Téléchargez, installez et lancez. Lors du premier lancement, vous pouvez voir la fenêtre suivante :

Cliquez sur le plus en haut de la zone de contenu pour créer votre première requête. L'onglet de requête ressemble à ceci :

Examinons-le plus en détail. L'interface de requête ressemble beaucoup à celle des clients REST populaires, ce qui facilite la migration depuis ces outils. Effectuons la première requête sur l'url. https://next.json-generator.com/api/json/get/NJv-NT-U8

À première vue, le panneau de réponse ne semble pas non plus présenter de surprises. Cependant, je voudrais attirer votre attention sur certains points :

1. Le corps de la réponse a une représentation en arbre, ce qui, d'une part, ajoute de l'information et, d'autre part, permet d'ajouter certaines fonctionnalités intéressantes que je décrirai ci-dessous.
2. Il y a un onglet Assertions, qui affiche la liste des tests pour cette requête.

Comme vous pouvez le constater, notre outil peut être utilisé comme un client REST pratique. Cependant, nous ne serions pas ici si ses capacités se limitaient uniquement à l'envoi de requêtes. Je vais maintenant exposer les concepts de base et les fonctionnalités de TestMace.

Concepts de base et fonctionnalités

Noeud

Les fonctionnalités de TestMace sont réparties en différents types de nœuds. Dans l'exemple ci-dessus, nous avons démontré le fonctionnement du nœud RequestStep. Cependant, l'application propose également actuellement les types de nœuds suivants :

• RequestStep. C'est un nœud qui permet de créer une requête. En tant qu'élément enfant, il peut n'avoir qu'un seul nœud Assertion.
• Assertion. Ce nœud est utilisé pour écrire des tests. Il ne peut être un nœud enfant que pour le nœud RequestStep.
• Folder. Permet de regrouper des nœuds Folder et RequestStep à l'intérieur.
• Project. C'est le nœud racine, créé automatiquement lors de la création d'un projet. Par ailleurs, il reprend les fonctionnalités du nœud Folder.
• Link. Lien vers un nœud Folder ou RequestStep. Permet de réutiliser des requêtes et des scénarios.
• etc.

Les nœuds sont placés dans les scratches (panneau en bas à gauche, utilisé pour la création rapide de requêtes « jetables ») et dans le project (panneau en haut à gauche), sur lequel nous allons nous attarder.

Projet

Au lancement de l'application, vous avez pu remarquer une seule ligne Project en haut à gauche. C'est la racine de l'arbre du projet. Lorsqu'un projet est lancé, un projet temporaire est créé, dont le chemin dépend de votre système d'exploitation. À tout moment, vous pouvez déplacer le projet à un emplacement qui vous convient.

La principale fonction du projet est de permettre de sauvegarder les développements dans le système de fichiers et de synchroniser ensuite via des systèmes de contrôle de versions, d'exécuter des scénarios dans CI, de réviser les modifications, etc.

Variables

Les variables sont l'un des mécanismes clés de l'application. Ceux d'entre vous qui travaillent avec des outils comme TestMace auront peut-être déjà compris de quoi il s'agit. Ainsi, les variables sont un moyen de conserver des données communes et de communiquer entre les nœuds. Par exemple, elles sont similaires aux variables d'environnement dans Postman ou Insomnia. Cependant, nous avons approfondi le sujet. Dans TestMace, les variables peuvent être définies au niveau du nœud. N'importe quel nœud. Il existe également un mécanisme d'héritage des variables des ancêtres et de substitution des variables dans les descendants. De plus, il y a un certain nombre de variables intégrées, dont les noms commencent par $. Voici quelques-unes d'entre elles :

• $prevStep — référence aux variables du nœud précédent
• $nextStep — référence aux variables du nœud suivant
• $parent — idem, mais pour un ancêtre
• $response — réponse du serveur
• $env — variables d'environnement actuelles
• $dynamicVar — variables dynamiques, créées lors de l'exécution du scénario ou de la requête

$env — ce sont en fait des variables ordinaires au niveau du projet, mais l'ensemble des variables d'environnement change en fonction de l'environnement sélectionné.

L'accès à une variable se fait via ${variable_name}
En tant que valeur d'une variable, il peut s'agir d'une autre variable, ou même d'une expression complète. Par exemple, en tant que variable url, on peut avoir une expression du type
http://${host}:${port}/${endpoint}.

Il convient de noter la possibilité d'assigner des variables pendant l'exécution du script. Par exemple, il est souvent nécessaire de conserver les données d'autorisation (token ou tout l'en-tête) qui ont été reçues du serveur après une connexion réussie. TestMace permet de conserver de telles données dans des variables dynamiques de l'un des ancêtres. Pour éviter les collisions avec les variables « statiques » déjà existantes, les variables dynamiques sont placées dans un objet séparé. $dynamicVar.

Scénarios

En utilisant toutes les possibilités mentionnées ci-dessus, vous pouvez réaliser des scénarios de requêtes entiers. Par exemple, création d'une entité -> requête d'entité -> suppression d'entité. Dans ce cas, vous pouvez utiliser un nœud Folder pour regrouper plusieurs nœuds RequestStep.

Autocomplétion et surlignage de la valeur de l'expression

Pour travailler efficacement avec des variables (et pas seulement), l'autocomplétion est essentielle. Bien sûr, il est également important de mettre en surbrillance la valeur de l'expression, afin de voir plus facilement à quoi correspond chaque variable. C'est le genre de situation où il est souvent préférable de voir une fois que d'entendre cent fois.

Il convient de noter que l'autocomplétion est mise en œuvre non seulement pour les variables, mais aussi, par exemple, pour les en-têtes, les valeurs de certains en-têtes (comme l'autocomplétion pour l'en-tête Content-Type), les protocoles et bien d'autres choses encore. La liste est constamment enrichie à mesure que l'application se développe.

Annuler/Rétablir

L'annulation/rétablissement des modifications est une fonctionnalité très pratique, mais elle n'est pas toujours disponible (et les outils de travail avec l'API ne font pas exception). Cependant, nous ne faisons pas partie de ceux-là !) L'annulation/rétablissement est mise en œuvre dans l'ensemble du projet, ce qui permet d'annuler non seulement l'édition d'un nœud spécifique, mais aussi sa création, sa suppression, son déplacement, etc. Les opérations les plus critiques nécessitent une confirmation.

Création de tests

La création de tests est assurée par le nœud Assertion. L'une des principales caractéristiques est la possibilité de créer des tests sans programmation, en utilisant des éditeurs intégrés.

Le nœud Assertion se compose d'un ensemble d'assertions. Chaque assertion a son propre type, et à l'heure actuelle, plusieurs types d'assertions existent.

1. Comparer des valeurs — compare simplement 2 valeurs. Plusieurs opérateurs de comparaison sont disponibles : « égal », « différent », « plus grand », « plus grand ou égal », « plus petit », « plus petit ou égal ».

2. Contient la valeur — vérifie si une sous-chaîne est présente dans une chaîne.

3. XPath — vérifie qu'une valeur spécifique se trouve par sélecteur dans le XML.

4. Assertion JavaScript — un script arbitraire en JavaScript qui renvoie true en cas de succès et false en cas d'échec.

Je tiens à souligner que seul le dernier demande des compétences en programmation, les 3 autres assertions étant créées à l'aide de l'interface graphique. Voici à quoi ressemble le dialogue de création d'une assertion de comparaison de valeurs :

La cerise sur le gâteau est la création rapide d'assertions à partir de la réponse, regardez juste ça !

Cependant, de telles assertions présentent des limites évidentes, face auxquelles vous pouvez utiliser des assertions JavaScript. Et ici, TestMace offre également un environnement confortable avec autocomplétion, mise en surbrillance de la syntaxe et même un analyseur statique.

Description de l'API

TestMace permet non seulement d'utiliser l'API, mais aussi de le documenter. La description elle-même a une structure hiérarchique et s'intègre harmonieusement dans le reste du projet. De plus, il est actuellement possible d'importer la description de l'API à partir des formats Swagger 2.0 / OpenAPI 3.0. La description ne reste pas simplement dans un état inerte, mais s'intègre étroitement avec le reste du projet, notamment grâce à l'autocomplétion des URLs, des en-têtes HTTP, des paramètres de requête et d'autres éléments, et à l'avenir, nous prévoyons d'ajouter des tests de conformité des réponses à la description de l'API.

Partage de nœuds

Cas d'utilisation : vous voudriez partager une requête problématique ou même un scénario entier avec un collègue ou simplement l'attacher à un bug. TestMace couvre également ce cas : l'application permet de sérialiser n'importe quel nœud et même un sous-arbre dans une URL. Un simple copier-coller et vous avez déjà transféré la requête vers un autre ordinateur ou projet avec facilité.

Format de stockage lisible par l'homme du projet

À l'heure actuelle, chaque nœud est stocké dans un fichier séparé avec l'extension yml (comme dans le cas du nœud Assertion), ou dans un dossier nommé d'après le nœud avec un fichier index.yml à l'intérieur.
Voici à quoi ressemble par exemple le fichier de la requête que nous avons créé dans l'examen ci-dessus :

index.yml

children: []
variables: {}
type: RequestStep
assignVariables: []
requestData:
  request:
    method: GET
    url: 'https://next.json-generator.com/api/json/get/NJv-NT-U8'
  headers: []
  disabledInheritedHeaders: []
  params: []
  body:
    type: Json
    jsonBody: ''
    xmlBody: ''
    textBody: ''
    formData: []
    file: ''
    formURLEncoded: []
  strictSSL: Inherit
authData:
  type: inherit
name: Scratch 1

Comme vous pouvez le voir, tout est très clair. Si vous le souhaitez, ce format est tout à fait confortable à éditer manuellement.

La hiérarchie des dossiers dans le système de fichiers reflète exactement la hiérarchie des nœuds dans le projet. Par exemple, un scénario comme :

Se mappent dans le système de fichiers selon la structure suivante (seule la hiérarchie des dossiers est montrée, mais le principe est clair)

Ce qui facilite le processus de révision du projet.

Importation depuis Postman

Après avoir lu tout ce qui précède, certains utilisateurs voudront peut-être essayer (n'est-ce pas ?) le nouveau produit ou (qui sait ?) l'utiliser pleinement dans leur projet. Cependant, la migration peut être entravée par un grand nombre de développements déjà réalisés dans Postman. Pour de tels cas, TestMace prend en charge l'importation de collections depuis Postman. Actuellement, l'importation sans tests est prise en charge, mais nous ne rejetons pas leur prise en charge à l'avenir.

Plans

J'espère que de nombreux lecteurs, jusqu'à ce stade, ont apprécié notre produit. Cependant, ce n'est pas tout ! Le développement du produit est en plein essor et voici quelques fonctionnalités que nous prévoyons d'ajouter prochainement.

Synchronisation Cloud

L'une des fonctionnalités les plus demandées. À l'heure actuelle, nous proposons d'utiliser des systèmes de contrôle de version pour la synchronisation, ce qui rend le format plus adapté à ce type de stockage. Cependant, ce flux de travail ne convient pas à tout le monde, c'est pourquoi nous prévoyons d'ajouter un mécanisme de synchronisation familier pour beaucoup à travers nos serveurs.

CLI

Comme mentionné précédemment, les produits de niveau IDE ne se passent pas des diverses intégrations avec les applications ou flux de travail existants. Le CLI est en effet nécessaire pour intégrer les tests écrits dans TestMace dans le processus d'intégration continue. Le développement du CLI est en plein cours, les premières versions permettront de lancer le projet avec un simple rapport en console. Par la suite, nous prévoyons d'ajouter une sortie de rapport au format JUnit.

Système de plugins

Malgré toute la puissance de notre outil, le nombre de cas à résoudre est illimité. Après tout, il existe des tâches spécifiques à chaque projet. Pour cette raison, nous prévoyons d'ajouter un SDK pour le développement de plugins, permettant à chaque développeur d'ajouter des fonctionnalités à sa convenance.

Élargissement de la gamme de types de nœuds

Cet ensemble de nœuds ne couvre pas tous les cas nécessaires pour l'utilisateur. Les nœuds qui sont prévus d'être ajoutés :

• Nœud Script — transforme et place des données en utilisant js et l'API appropriée. En utilisant ce type de nœud, il est possible de créer des choses comme des scripts pré-requête et post-requête dans Postman.
• Nœud GraphQL — support de graphql
• Nœud d'assertion personnalisée — permettra d'élargir l'ensemble des assertions disponibles dans le projet
  Naturellement, ce n'est pas une liste définitive, elle sera constamment mise à jour grâce à votre feedback, entre autres.

FAQ

Qu'est-ce qui vous distingue de Postman ?

1. Concept de nœuds permettant d'évoluer presque indéfiniment les fonctionnalités du projet
2. Format lisible par l'homme pour le projet, conservé dans le système de fichiers, ce qui facilite le travail avec les systèmes de contrôle de version
3. Possibilité de créer des tests sans programmation et prise en charge avancée de js dans l'éditeur de tests (auto-complétion, analyseur statique)
4. Complétion automatique avancée et surlignage de la valeur actuelle des variables

Est-ce un produit open-source?

Non, actuellement les sources sont fermées, mais nous envisageons de les rendre ouvertes à l'avenir.

Comment vivez-vous ?

Avec la version gratuite, nous prévoyons de lancer une version payante du produit. Celle-ci inclura principalement des fonctionnalités nécessitant une partie serveur, comme la synchronisation.

Conclusion

Notre projet progresse à grands pas vers une version stable. Cependant, le produit est déjà utilisable et les retours positifs de nos premiers utilisateurs en témoignent. Nous collectons activement des retours, car sans une collaboration étroite avec la communauté, il est impossible de créer un bon outil. Vous pouvez nous trouver ici :

Site officiel

Telegram

Slack

Facebook

Suivi des problèmes

Nous attendons avec impatience vos souhaits et suggestions !

Source : habr.com