Wahrscheinlich kennt jeder Schmerz diesen Schmerz - irrelevante Dokumentation. Egal wie sehr sich das Team bemüht, in modernen Projekten werden wir so oft veröffentlichen, dass es fast unmöglich ist, alle Änderungen zu beschreiben. Unser Testteam hat zusammen mit Systemanalysten beschlossen, unsere Projektdokumentation zu revitalisieren.
Die Webprojekte der Alfa-Bank verwenden das
Akita- Testautomatisierungsframework, das für BDD-Skripte verwendet wird. Bisher hat das Framework aufgrund seiner niedrigen Einstiegsschwelle, Benutzerfreundlichkeit und der Möglichkeit, das Layout zu testen, große Popularität erlangt. Wir haben uns jedoch entschlossen, weiter zu gehen - auf der Grundlage der beschriebenen Testszenarien, um Dokumentation zu generieren, wodurch die Zeit, die Analysten für das ewige Problem der Aktualisierung der Dokumentation aufwenden, erheblich reduziert wird.
Zusammen mit Akita wurde bereits ein Plug-In zur Dokumentationsgenerierung verwendet, das die Schritte in den Skripten durchlief und sie in das HTML-Format hochlud. Um dieses Dokument jedoch populär zu machen, mussten wir Folgendes hinzufügen:
- Screenshots
- Werte von Variablen (Konfigurationsdatei, Benutzerkonten usw.);
- Status und Abfrageparameter.
Wir haben uns unser vorhandenes Plug-In angesehen, bei dem es sich tatsächlich um einen statischen Analysator handelte, und eine Dokumentation basierend auf den in den .feature-Dateien beschriebenen Skripten erstellt. Wir haben beschlossen, Lautsprecher hinzuzufügen, und um das Plug-In nicht wie ein Plug-In aussehen zu lassen, haben wir beschlossen, unsere eigenen zu schreiben.
Zunächst wollten wir herausfinden, wie wir Screenshots und Werte von Variablen, die in Testskripten verwendet werden, aus Feature-Dateien sammeln können. Alles stellte sich als recht einfach heraus. Wenn Cucumber Tests für jede Feature-Datei ausführt, wird eine separate cucumber.json erstellt.
Diese Datei enthält die folgenden Objekte:
Name und Schlüsselwort des Testfalls:
Arrays von Elementen - die Skripte und Schritte selbst:
Das Ausgabefeld enthält zusätzliche Informationen, z. B. Variablen - Adressen, Links, Benutzerkonten usw.:
Die Einbettungen enthalten Screenshots, die Selen während der Tests macht:
Daher müssen wir nur die Dateien cucumber.json durchgehen, die Namen der Testsuiten sammeln, Skripte testen, die Schritte ausführen, zusätzliche Informationen und Screenshots sammeln.
Damit in der Dokumentation Anforderungen angezeigt werden, die im Hintergrund oder für eine bestimmte Aktion auftreten, mussten wir unsere Frontentwickler um Hilfe bitten. Mithilfe von Proxy konnten wir traceId abfangen, die Front-End-Serviceanfragen generieren. Mit derselben traceId werden Protokolle elastisch geschrieben, von wo aus wir alle erforderlichen Abfrageparameter in den Testbericht und die Dokumentation ziehen.
Als Ergebnis haben wir eine Datei im Asciidoc-Format erhalten - ein praktisches Dateiformat, das etwas komplizierter als das Markdown-Analogon ist, aber viel mehr Formatierungsoptionen bietet (Sie können ein Bild oder eine Tabelle einfügen, was beim Markdown nicht möglich ist).
Um das resultierende Asciidoc in andere Formate zu konvertieren, verwenden wir Ascii doctorj, die offizielle Version des AsciiDoctor Java-Tools. Als Ergebnis erhalten wir eine vorgefertigte Dokumentation im HTML-Format, die in Konfluenz heruntergeladen, an einen Kollegen gesendet oder in das Repository gestellt werden kann.
Wie verbinde ich mich?
Um nun eine Front-End-Dokumentation für Ihr Projekt zu generieren, müssen Sie nur noch das Dokumentations-Plugin daran anschließen und nach dem Ausführen aller Tests den Befehl
adoc .
Was wollen wir verbessern?
- Fügen Sie konfigurierbare technische Schritte hinzu.
In der aktuellen Version des Plugins gibt es Schritte "Und ein Screenshot wurde gemacht ...". Solche Schritte enthalten keine semantische Last für die Dokumentation, und wir möchten sie ausblenden. Jetzt haben wir sie in das Plugin eingenäht und sie werden übersprungen, aber es gibt einen Nachteil - jede Hinzufügung dieses Schritts führt dazu, dass wir eine neue Version des Plugins erstellen müssen. Um dies zu vermeiden, planen wir, solche Schritte in die Konfigurationsdatei zu übertragen und die Schritte aufzuschreiben, die wir in den Skripten nicht sehen möchten. - Erstellen Sie ein Open-Sourse-Plugin.
Welche Teams eignen sich für unsere Implementierung?
- Verwenden Sie Gurke (oder ein ähnliches Framework).
- möchten eine aktuelle Dokumentation für die Front und die Wissensbasis haben;
- Sie wollen Analysten in Tests einbeziehen.
Ergebnis:
Pilotversuche in mehreren Teams haben gezeigt, dass es Analysten mithilfe des Plugins gelingt, die Dokumentation auf dem neuesten Stand zu halten, und dass Analysten ihre Zeit nicht mehr damit verbringen müssen, sie zu warten. Darüber hinaus hat uns die Implementierung dieser Funktion dazu veranlasst, weiterhin vollwertige BDD in Teams zu implementieren. Heute führen wir ein Experiment durch - Analysten formulieren einen positiven Pfad für den Kunden, geben Geschäftsbeschränkungen mithilfe von Akita BDD-Schritten an, Tester schreiben wiederum benutzerdefinierte Schritte und zusätzliche Überprüfungen für diese Szenarien.
Übrigens, über holivar, ob BDD benötigt wird oder nicht, werden wir am Montag ein
besonderes Treffen abhalten.