Améliorer la fiabilité de vos manifestes Jelastic grùce à une documentation vivante

Improve the reliability of your Jelastic manifests with living documentation

Les manifestes Jelastic sont parfois si complexes qu’il est difficile de suivre tous les petits dĂ©tails qui peuvent Ă©chouer lors d’une installation. La plupart du temps, un manifeste complexe est Ă©galement difficile Ă  comprendre. En effet, les manifestes Jelastic sont souvent un tas de scripts Ă©crits en plusieurs langues et il est facile de s’y perdre lorsque l’infrastructure qu’ils dĂ©finissent prend de l’ampleur. Chaque script est responsable d’un petit dĂ©tail qui finira par faire tenir l’ensemble du systĂšme. En tant que fournisseur de logiciels sur la plateforme Jelastic, vous voulez certainement vous assurer que les manifestes que vous mettez sur le marchĂ© fonctionneront toujours correctement lorsque Jelastic publiera une nouvelle mise Ă  jour de la plateforme. Au moins, vous voulez ĂȘtre informĂ© si vos manifestes ne fonctionnent plus, afin de pouvoir les corriger avant que les utilisateurs ne les utilisent. J’ai trop souvent Ă©tĂ© ralenti dans mes projets juste parce qu’un manifeste du marchĂ© ne fonctionnait plus. Je l’avais installĂ© de nombreuses fois dans le passĂ©, mais avec la nouvelle mise Ă  jour de Jelastic, il ne fonctionne plus. Parfois, je passe Ă  un logiciel Ă©quivalent dont le manifeste fonctionne tout simplement. D’autres fois, comme il n’y a pas d’alternative, je dois avertir mon fournisseur Jelastic et attendre que le manifeste soit corrigĂ©.

Je suis d’avis que les fournisseurs de manifestes Jelastic bĂ©nĂ©ficieraient grandement d’une sorte de validation de leur installation de manifeste ainsi que d’une documentation synchronisĂ©e avec ce que leurs manifestes livrent. Les tests automatisĂ©s sont l’une des pierres angulaires de tout logiciel professionnel. Une documentation vivante vous permettra de faire exactement cela : valider vos manifestes et documenter ce qu’ils font.

Laissez-moi vous montrer ce que je veux dire avec un exemple simple.

Le manifeste hasura

Hasura simplifie considĂ©rablement la crĂ©ation d’API web basĂ©es sur une base de donnĂ©es (notamment postgresql). Les applications typiques conçues avec Hasura sont les suivantes

Je suis actuellement en train de dĂ©velopper un manifeste pour installer hasura sur Jelastic et j’ai pensĂ© vous fournir un exemple concret de la façon de rĂ©aliser une documentation vivante sur un cas simple. Vous pouvez trouver le code dans ce dĂ©pĂŽt gitlab. Pour des raisons de concision, nous allons nous concentrer sur la validation d’une partie du moteur de faas. La mĂ©thode que je dĂ©cris ci-dessous est gĂ©nĂ©ralisable au dĂ©veloppement de tout type de manifeste.

Tout commence par une caractéristique du cornichon :

Voyez-vous cette belle description de ce que le manifeste faas veut rĂ©aliser ? La formulation claire et agrĂ©able en anglais ? Et ce fichier de fonctionnalitĂ©s est minimaliste. J’aurais pu ajouter des images, des descriptions de scĂ©narios ou des dĂ©tails sur la description des fonctionnalitĂ©s.

Les quelques scĂ©narios ci-dessus permettent de s’assurer que notre manifeste Jelastic installe bien faasd et que nous pouvons effectuer les opĂ©rations de base sur le moteur faas. Avec ce simple fichier de fonctionnalitĂ©s, nous dĂ©crivons le strict minimum que nous devons rĂ©aliser avec notre moteur faas aprĂšs son installation rĂ©ussie : nous devons

  • ĂȘtre capable de dĂ©ployer des fonctions vers le moteur faas
  • invoquer des fonctions sur le moteur faas

En substance, le fichier de caractĂ©ristiques ci-dessus est votre spĂ©cification. Dans un projet typique, vous aurez un grand nombre de fichiers de caractĂ©ristiques. Il est donc assez pratique de les transformer en format html dynamique. Vous pouvez y parvenir, par exemple, avec pickles, pour lequel vous disposez Ă  la fois d’une interface utilisateur et d’un outil de console, ce qui en fait l’outil idĂ©al pour votre pipeline gitlab ! Le site web statique gĂ©nĂ©rĂ© par pickles permet de parcourir facilement vos fonctionnalitĂ©s. Vous pouvez mĂȘme joindre les rĂ©sultats des tests Ă  ce rapport Web, ce qui en fait un bon outil de suivi de la progression de votre Ă©quipe dans l’itĂ©ration de dĂ©veloppement en cours.

Dans le reste de cet article, nous voulons faire vivre cette spécification et nous allons nous concentrer sur la méthode du concombre. Une alternative à cucumber est gauge.

Configuration de l’exemple Python

Concentrons-nous d’abord sur la configuration du code nĂ©cessaire pour donner vie Ă  ces scĂ©narios de test. Il existe des frameworks pour la majoritĂ© des langages de programmation les plus populaires, comme vous pouvez le voir ici. Partons du principe que nous allons programmer les tests en python, avec behave, car c’est trĂšs facile. Tout d’abord, installez behave

pip install behave

Ensuite, lorsque j’ai dĂ©marrĂ© le projet, l’arbre source de ce projet de test ressemblait Ă  ceci :

D’un cĂŽtĂ©, nous avons le dossier features, oĂč toute la magie des tests de comportement va se produire. D’autre part, nous avons nos manifestes jps que nous voulons tester et documenter. Dans le dossier features, nous trouvons un environment.py qui dĂ©finit l’environnement de test. En substance, c’est ici que nous appliquons les fixtures dĂ©finies dans le fichier fixtures.py, c’est-Ă -dire que vous dĂ©finissez ce qui va se passer avant tous les tests, avant chaque fonctionnalitĂ©, avant chaque scĂ©nario, aprĂšs tous les tests, etc. Par exemple, le fichier environment.py pourrait ressembler Ă  ceci :

Dans nos tests de manifeste jps, nous avons gĂ©nĂ©ralement besoin de crĂ©er des environnements Jelastic, de les vider aprĂšs les tests, de vĂ©rifier certaines choses sur les environnements, etc. C’est pourquoi nous avons besoin de clients API Jelastic. Afin de faciliter les tests des manifestes hasura-jps, nous avons mis en place un client Jelastic en python. Vous le verrez en action ci-dessous. De plus, comme il se peut que de nombreux tests soient exĂ©cutĂ©s simultanĂ©ment (par exemple Ă  partir de diffĂ©rentes branches de notre dĂ©pĂŽt), nous devons choisir nos noms d’environnement Jelastic avec soin. Cela explique les fixtures random_seed, worker_id, et commit_sha. Les fixtures sont dĂ©finis comme ceci :


                                                                                    

En substance, behave met un contexte Ă  la disposition de tous les scĂ©narios de test. Les fixtures placent des Ă©lĂ©ments dans ce contexte, afin qu’ils soient disponibles dans les Ă©tapes de test que nous dĂ©finirons plus tard. Par exemple, nous ne voulons pas crĂ©er nos clients API Jelastic dans nos mĂ©thodes d’Ă©tape. Nous les dĂ©finissons donc une fois pour toutes dans un fixture et les rendons disponibles dans le contexte.

Le pipeline de test des fonctionnalités correspondant ressemble à ceci dans gitlab :

Notez les options -D dans la ligne de commande, auxquelles on accĂšde via les userdata dans nos fixtures.

Nous pouvons maintenant aborder le premier scĂ©nario, avec le titre Log on. La procĂ©dure pour mettre en Ɠuvre les autres scĂ©narios est la mĂȘme. L’implĂ©mentation se dĂ©roule comme suit :

 

Je ne vais pas donner la dĂ©finition de tout ici car cela prendrait trop de temps de tout expliquer. J’espĂšre que le code est auto-explicatif et que son intention est claire. Dans la premiĂšre Ă©tape donnĂ©e, nous utilisons notre client API Jelastic pour crĂ©er un nouvel environnement Jelastic avec un nƓud docker avec l’image docker spĂ©cifiĂ©e dans le groupe de nƓuds Jelastic spĂ©cifiĂ©. La deuxiĂšme Ă©tape utilise l’API Jelastic marketplace.jps pour installer notre manifeste faasd et attendre que le nƓud faasd ait un port 8080 ouvert, ce qui sera nĂ©cessaire pour toutes les opĂ©rations suivantes. L’Ă©tape when utilise notre FaasClient maison pour se connecter Ă  faasd. Le FaasClient est essentiellement une enveloppe de shell sur l’exĂ©cutable faas-cli. Enfin, l’Ă©tape then vĂ©rifie que la connexion a rĂ©ussi. Vous trouverez tous les dĂ©tails sur notre dĂ©pĂŽt public. Le code source de notre client API Jelastic est Ă©galement open-source, comme vous pouvez le voir ici. Avec les dĂ©finitions des Ă©tapes ci-dessus en place, nous avons liĂ© notre spĂ©cification en anglais simple avec le code python et l’avons rendu vivant.

Conclusion

J’espĂšre avoir rĂ©ussi Ă  Ă©veiller votre curiositĂ© pour les tests d’acceptation et Ă  vous motiver Ă  faire vos premiers pas vers une bonne documentation vivante de vos manifestes Jelastic. Bien sĂ»r, en plus de tous les avantages de la documentation vivante, il y a des inconvĂ©nients. La rĂ©daction de la documentation est une charge supplĂ©mentaire. L’Ă©criture de bonnes spĂ©cifications nĂ©cessite de l’exercice et vous devez produire du code de test. De plus, l’exemple que j’ai prĂ©sentĂ© ici teste la crĂ©ation de l’environnement Jelastic, qui est trĂšs lente, ce qui rend vos tests trĂšs lents. Il existe cependant des moyens d’optimiser un peu. Par exemple, vous pourriez essayer d’utiliser une version du comportement supportant la concurrence, mais il n’y a rien d’officiellement supportĂ© pour le moment (seulement une demande de pull en attente sur github). Vous pouvez Ă©galement exĂ©cuter vos tests sur des environnements prĂ©-crĂ©Ă©s. Vous pouvez dĂ©finir des balises de niveau fonctionnalitĂ© qui appliqueront des fixtures de niveau fonctionnalitĂ© qui crĂ©eront les environnements Jelastic pertinents pour une fonctionnalitĂ© une fois pour toutes. Les scĂ©narios de cette fonctionnalitĂ© s’exĂ©cuteront tous sur les environnements Jelastic prĂ©configurĂ©s.

Écrit par

Laurent MICHEL
02/03/2022

Product owner chez Softozor et client Hidora depuis 2017, utilisant le PaaS jelastic et le ci/cd gĂ©rĂ© gitlab pour rĂ©duire les frais gĂ©nĂ©raux d’infrastructure de leur plateforme e-commerce.

Recevoir nos actualités