Spock's @Narrative and @Title annotations

Question

Spock provides @Narrative and @Title annotations that you can use to provide a class-level description of your test, e.g.

@Narrative('description of spec')
@Title('title of spec')
class ExampleSpec extends Specification {

  // tests omitted
}

What is the difference between these two? In other words, why do we need both of them, when they seem to serve the same purpose?

Answer 1

Title is expected to be a single line (short description)

Narrative should be full paragraphs (using a Groovy multi-line string)

They are mostly used in big projects where Narrative text could be read by business analysts, project managers e.t.c.

As Opal said these will be more useful once some reporting tools actually use them.

Update: The Spock reports project now supports these annotations.

Answer 2

The purpose of both annotations is purely informational - and they're named very well. Think about a specification as if it was a movie ( :D ). Movie has a title and may have a description or a review. In this particular case @Title may be Specification for Example validation and @Narrative This specification checks how Example validation works under various input data - especially malformed. Now if a member of the project responsible for quality (or whatever) reads this descriptions he/she may point out that some specifications are missing base on the descriptions he/she read. To be honest, I wouldn't put much attention to these annotations unless they're really needed.

What's more, such descriptions may be used for docs generation.