Agile, oven-fresh documentation. Part 3: Tested requirements with JBake

No Comments

In the first two parts of this blog series, I introduced JBake and discussed the integration of PlantUML. In this post, I will move on to test automation and documentation, integrating Spock into the existing stack as a test framework.

What is Spock? And why another test framework?

Spock is written in the JVM language Groovy and uses its own Domain-Specific Language (DSL) to describe the tests. Thanks to this DSL, the tests are clearly structured and readable. Needless to say, it is also possible to execute pure Java code with Spock.
What’s also special about Spock is the way it displays failed tests, visualizing the failed condition down to its individual components.

From requirement to test to “tested” documentation

Every test in software development emerges from a specific requirement. Typically, these requirements are kept in a wiki. Now, how can the developer react to direct changes in a requirement within a sprint? Can requirements be mapped “as code” even by Product Owners who do not have any development background?
To reach this objective, we use Gherkin, a so-called “Business Readable DSL”. Gherkin is a line-oriented language that uses indentation to define structure.

Using a self-written Gradle task, the individual Gherkin specifications can now be transformed into Spock specifications. For this post, the Gradle task only includes the transformation of the simplest Gherkin structure.

The Groovy script is the first basic implementation of the Gherkin specification. Thanks to Gherkin, we can now implement a workflow between the product owner and the developers, which in turn can help reduce iterations between a requirement and its implementation within a sprint.

Now if, because of the transformed requirements, the developer chooses to pursue test-driven development using Spock, it is worth wondering how we can map the results with JBake. For this purpose, we will use Spock Reports.

Spock Reports offers the option to display the results of the Spock test in AsciiDoc, using templates. To adjust these templates, we need to create a properties file under test/resources.

In JBake v2.6 it is now possible to exclude files from the documentation generation process using .jbakeignore. We now use this feature to create the test reports, since they are integrated via include. However, we do not want these included files to be separate HTML files; rather, their contents should simply be pasted into the index.html. To make this part of the continuous process, we need to create a Gradle task to generate the ignore file.

This task will now be executed after the Gradle Test task, which we will achieve by using test.finalizedBy(createjbakeignorefile).

Triggered by the test task within the Gradle build, the report is written directly into the source directory of the documentation, and the build.finalizedBy(bake) entry creates the documentation with JBake at the end of the build.
In this way, the tested requirements become an integral part of the documentation.

Daniel has been part of the codecentric team since October 2016 and since the beginning of 2022 as Senior Solution Architect at the Dortmund branch. Starting as a consultant with a focus on application lifecycle management, his focus shifted more and more towards APIs. In addition to numerous customer projects and his involvement in the open source world around APIs, he is also a frequent speaker as Head of API Experience & Operations.


Your email address will not be published.