Chaque douleur connaît probablement cette douleur - une documentation non pertinente. Peu importe les efforts de l'équipe, dans les projets modernes, nous publierons si souvent qu'il est presque impossible de décrire tous les changements. Notre équipe de test, en collaboration avec des analystes système, a décidé d'essayer de revitaliser la documentation de notre projet.
Les projets Web d'Alfa-Bank utilisent le cadre d'automatisation des tests
Akita , qui est utilisé pour les scripts BDD. À ce jour, le cadre a gagné en popularité en raison de son seuil d'entrée bas, de sa convivialité et de sa capacité à tester la disposition. Mais nous avons décidé d'aller plus loin - sur la base des scénarios de test décrits, pour générer de la documentation, réduisant ainsi considérablement le temps que les analystes consacrent au problème éternel de la mise à jour de la documentation.
En fait, avec Akita, un plug-in de génération de documentation était déjà utilisé, qui passait par les étapes des scripts et les téléchargeait au format html, mais pour rendre ce document populaire, nous devions ajouter:
- Captures d'écran
- valeurs des variables (fichier de configuration, comptes utilisateurs, etc.);
- statuts et paramètres de requête.
Nous avons examiné notre plug-in existant, qui était en fait un analyseur statique et généré une documentation basée sur les scripts décrits dans les fichiers .feature. Nous avons décidé d'ajouter des haut-parleurs, et afin de ne pas faire ressembler le plug-in à un plug-in, nous avons décidé d'écrire le nôtre.
Tout d'abord, nous avons décidé de découvrir comment nous pouvons collecter des captures d'écran et les valeurs des variables utilisées dans les scripts de test à partir des fichiers de fonctionnalités. Tout s'est avéré assez simple. Cucumber, lors de l'exécution de tests pour chaque fichier de fonction, crée un cucumber.json distinct.
Ce fichier contient les objets suivants:
Nom et mot clé du scénario de test:
Tableaux d'éléments - les scripts et les étapes eux-mêmes:
Le champ de sortie contient des informations supplémentaires, par exemple des variables - adresses, liens, comptes d'utilisateurs, etc.:
Les plongements contiennent des captures d'écran que le sélénium prend pendant les tests:
Ainsi, il nous suffit de parcourir les fichiers cucumber.json, de collecter les noms des suites de tests, de tester les scripts, de retirer les étapes, de collecter des informations supplémentaires et des captures d'écran.
Pour que la documentation affiche les demandes qui se produisent en arrière-plan ou pour une action spécifique, nous avons dû demander de l'aide à nos développeurs frontaux. Avec l'aide du proxy, nous avons pu attraper traceId, qui génère des demandes de service frontales. Par le même traceId, les journaux sont écrits en élastique, d'où nous tirons tous les paramètres de requête nécessaires dans le rapport de test et la documentation.
En conséquence, nous avons obtenu un fichier au format Asciidoc - un format de fichier pratique, un peu plus compliqué que l'analogue de démarque, mais a beaucoup plus d'options de formatage (vous pouvez insérer une image ou un tableau, ce qui ne peut pas être fait dans le démarque).
Pour convertir l'Asciidoc résultant en d'autres formats, nous utilisons Ascii doctorj, qui est la version officielle de l'outil Java AsciiDoctor. En conséquence, nous obtenons une documentation prête à l'emploi au format html, qui peut être téléchargée en confluence, envoyée à un collègue ou placée dans le référentiel.
Comment se connecter?
Maintenant, pour générer la documentation frontale de votre projet, il vous suffit de vous connecter au plug-in de documentation et après avoir exécuté tous les tests, exécutez la commande
adoc .
Que voulons-nous améliorer?
- Ajoutez des étapes techniques configurables.
Dans la version actuelle du plugin, il y a des étapes "Et une capture d'écran a été prise ...". Ces étapes ne portent pas de charge sémantique pour la documentation et nous voulons les masquer. Maintenant, nous les avons cousus à l'intérieur du plugin, et ils sont ignorés, mais il y a un inconvénient - chaque ajout de cette étape conduit au fait que nous devons créer une nouvelle version du plugin. Pour éviter cela, nous prévoyons de transférer ces étapes dans le fichier de configuration et de noter ces étapes que nous ne voulons pas voir dans les scripts. - Créez un plugin open sourse.
Quelles équipes conviennent à notre mise en œuvre?
- utiliser du concombre (ou un cadre similaire);
- veulent avoir une documentation à jour pour le front et la base de connaissances;
- Ils veulent engager des analystes dans les tests.
Résultat:
Des projets pilotes sur plusieurs équipes ont montré qu'avec l'aide du plugin, nous parvenons à maintenir la documentation à jour, les analystes n'ont plus besoin de passer leur temps à la maintenir. De plus, l'implémentation de cette fonctionnalité nous a fait penser à continuer d'implémenter le BDD à part entière au sein des équipes. Aujourd'hui, nous menons une expérience - les analystes formulent un chemin positif pour le client, indiquent les restrictions commerciales en utilisant les étapes BDD d'Akita, les testeurs, à leur tour, écrivent des étapes personnalisées et des vérifications supplémentaires pour ces scénarios.
Soit dit en passant, à propos d'Holivar, que le BDD soit nécessaire ou non, nous tiendrons lundi une
réunion spéciale .