Programming for fun and profit

Programming tutorials, problems, solutions. Always with code.

Documenting Spock Framework Tests


Main feature of tests is their readability. How to use Spock Framework documenting features to increase readability of test reports.


Probably not many people know, but there is a lot of features that make documenting Spock Framework tests a breeze:

  • @Title: for short, one-line descriptions of specifications.
  • @Narrative: for longer, more verbose descriptions. They usually have a form of User StoriesAs…, I want…, to…“.
  • @Subject: clearly indicates what is being tested.
  • @See: a link to one or more references to external resources.
  • @Issue: a link to an issue.
  • Comments along Spock’s labels (expect, and, then, etc.).

Either @Narrative or @Title should be used, not both at once. It depends for whom you write the description and who is going to read test reports.

In the following example we’re going to show the annotations in action:

package com.farenda.spock

import spock.lang.Issue
import spock.lang.Narrative
import spock.lang.See
import spock.lang.Specification
import spock.lang.Subject
import spock.lang.Title

@Title('This test will test documenting features of Spock Framework')
As a Developer using Spock Framework for testing,
I want to be see Specifications documented,
so that my Business Analyst understand what is this all about.
class DocumentingSpecTest extends Specification {

    // Clearly indicates System Under Test:
    @Subject controller = new UserController()

    def 'should have controller'() {
        controller != null

        and: 'comments can be put here'
        controller.userService == null

    def 'should fix known math issue'() {
        2 + 2 == 4

By themselves the documenting annotations have no meaning to Spock Framework, but they are for consumption by external tools that generate test reports. For Spock there is Spock Reports library, which generates the report as you can see below:

Spock test reports

Spock test reports

Now you should know to document Spock Framework tests/specifications. ;-)

Share with the World!