Agile, frisch gebackene Dokumentation – Teil 3: Getestete Anforderungen mit JBake

1 Kommentar

In den ersten beiden Teilen habe ich JBake und die Integration von PlantUML vorgestellt. Nun möchte ich mich dem Thema Testautomatisierung und Dokumentation widmen. Hierzu wird Spock als Testframework in den vorhandenen Stack integrieren.

Was ist denn nun Spock? Und warum ein weiteres Testframework?

Spock ist in der JVM-Sprache Groovy geschrieben und nutzt eine eigene Domain-Specific Language (DSL) für die Beschreibung der Tests. Genau diese DSL fördert die Übersichtlichkeit und Lesbarkeit der Tests. Natürlich lässt sich auch reiner Java-Code mit Spock ausführen.
Eine weitere Besonderheit von Spock ist die Darstellung von fehlgeschlagenen Tests. Hiermit wird die fehlgeschlagene Bedingung bis in ihre Einzelkomponenten visualisiert.

Von der Anforderung über den Test zur „getesteten“ Dokumentation

Jeder Test in der Softwareentwicklung entsteht aus einer Anforderung heraus. In der Regel extistieren diese Anforderungen in einem Wiki. Wie kann der Entwickler auf direkte Änderung der Anforderung innerhalb eines Sprints reagieren? Lassen sich Anforderungen auch durch Product Owner ohne Entwicklungshintergrund als „as Code“ abbilden?
Um das beschriebene Ziel zu erreichen, kommt Gherkin, eine sogenannte „Business Readable DSL“, zum Einsatz. Gherkin ist eine zeilenorientierte Sprache, welche Einrückungen für die Strukturierung benutzt.

Mittels eines selbst geschriebenen Gradle-Tasks können nun die einzelnen Gherkin-Specifications in Spock-Specifications transformiert werden. Für den Blogpost umfasst der Gradle-Task nur die Transformation der einfachsten Gherkin-Struktur.

Das Groovy-Skript stellt eine erste Basisumsetzung der Gherkin-Spezifikation dar. Durch Gherkin können wir nun einen Workflow zwischen dem Produkt Owner und den Entwicklern umsetzen, der zu weniger Iterationen zwischen einer Anforderung und deren Umsetzung innerhalb eines Sprints beitragen kann.

Wenn nun der Entwickler aufgrund der transformierten Anforderungen die testgetriebene Entwicklung mittels Spock vorantreibt, stellt sich die Frage, wie wir die Ergebnisse mit JBake abbilden können. Hierzu werden wir Spock Reports verwenden.
Mit Spock Reports haben wir die Möglichkeit, die Ergebnisse des Spock Tests mit Hilfe von Templates in AsciiDoc darzustellen. Um diese Templates anpassen zu können, müssen wir eine properties-Datei unter test/resources anlegen.

In der Version 2.6 von JBake ist es nun möglich mittels einer .jbakeignore möglich, Dateien bei Dokumentationserstellung auszuschließen. Dieses Feature benutzen wir nun für die Erstellung der Testreports, da diese über ein include eingebunden werden. Wir möchten aber nicht, dass diese inkludierten Dateien als separate HTML-Dateien erstellt werden, sondern dass deren Inhalte einfach innerhalb der index.html eingefügt werden. Um dies innerhalb des kontinuierlichen Prozesses zu erreichen, muss ein Gradle Task für die Erstellung der ignore-Datei erstellt werden.

Dieser Task soll nun nach dem Gradle Test Task ausgeführt werden, was wir durch die Verwendung von test.finalizedBy(createjbakeignorefile) erreichen.

Ausgelöst durch den Test-Task innerhalb des Gradle Build wird der Report direkt in das Quellverzeichnis der Dokumentation geschrieben, und durch den Eintrag build.finalizedBy(bake) wird die Dokumentation mit JBake zum Ende des Builds erzeugt.
Auf diesem Wege werden die getesteten Anforderungen nun ein fester Bestandteil der Dokumentation.

Daniel Kocot

Von Oktober 2016 an ist Daniel ein Teil des Teams der codecentric am Standort in Solingen. Schon seit Anfang der 2000er Jahre widmet er sich dem Thema der „Digitalen Transformation“. Neben den aktuellen Schwerpunkten innerhalb der codecentric, ist er auch Experte für den Einsatz von Produktinformationssystemen (PIM) und Database-Publishing mit Hilfe von Rendering-Technologien.

Artikel von Daniel Kocot

Chaos Engineering GameDay

Architektur

Chaos Engineering GameDay

Weitere Inhalte zu Agiles Testen

Kommentare

  • Angelo Veltens

    28. Februar 2018 von Angelo Veltens

    Coole Idee Gherkin als Basis für Spock Tests zu nutzen! Ein Bild von der fertig gebackenen Dokumentation wäre noch nett 😉

Kommentieren

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.