One of the new features of the latest Jnario release are specification suites. They are a great way to structure and document your specifications (if you haven't heard of Jnario yet, it is a new language for testing Java applications, read my my previous post for a general introduction). In this post I want to give you a quick overview about Jnario suites and show you how we use them for the development of Jnario.
We completely bootstrapped the implementation of Jnario. This means we write all tests for Jnario with Jnario. One feature of Jnario we are using heavily is the possibility to convert specs to html documents. The complete Jnario documentation is created that way. Each documentation page is generated from an executable spec. Generating the documentation from specs saves a lot of time as you can use the same examples for testing and documenting your application. Furthermore, it ensures that all code samples in the documentation are correct. For example, here is a specification:
and this is what the generated documentation looks like:
However, at one point during the development of Jnario I had the problem that I needed to create an overview page for the documentation. The overview page was supposed to describe the structure of the documentation with links to the different subtopics. Creating it manually felt wrong as it takes away the advantage of being able to just generate the documentation without having to touch it. Furthermore, whenever I change the name of a specification file I would need to manually update the links in the overview page. Considering my forgetfulness, this would mean broken links galore.
When I thought about it, I realized that the underlying use case is actually pretty common: being able to group tests based on certain criteria. In JUnit you would use test suites for this. To solve my problem, I just had to take this concept one step further and add the possibility to provide additional documentation. This is exactly what you can do now with Jnario Suites. A suite looks like a normal document written in markdown syntax, but you have the possibility to reference other specs or suites. These references are actual links to the existing spec files, which means the editor provides code completion for available specs and shows validation errors if specs are missing. Even better a Jnario suite compiles into a normal JUnit test suite. This means you can execute Jnario suites like any other test suite. Here is the suite file for the overview page of the Jnario documentation:
Having to explicitly reference all specs in a project can become quite tedious over time. This is why it also possible to reference multiple specs at once by matching the qualified name of a specs using a regular expressions. Here is another suite from the Jnario code base that we are using to execute all Jnario specs in our test project:
So far I am really happy with the result. Jnario suites fill the gap between being able to write executable specs and being able to generate usable documentation from them. They are also useful during development, for example, I started using suites as todo lists for features that I need to implement (pro tip: there is a quickfix in the suite editor to add missing specs).
If you want to learn more about Jnario visit the official homepage www.jnario.org. There is also a mailing list available for questions and discussions. Follow me on twitter if you want to stay up-to-date with Jnario.
