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 Stories “As…, 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')
@Narrative('''
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()

    @See('https://farenda.com/spock-framework-tutorial')
    def 'should have controller'() {
        expect:
        controller != null

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

    @Issue('https://issues.farenda.com/PROJ-42')
    def 'should fix known math issue'() {
        expect:
        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:

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