Unrolling Spock: Advanced @Unroll Usages in 0.4

Some of the Spock Framework 0.4 features are starting to see the light of day, with the Data Tables being explained last week in a nice blog post from Peter Niederwieser. One of the new features that I had not seen before is the new advanced @Unroll usage. Mixed with Data Tables, it produces some very cool results, and it can still be used with 0.3 style specs as well. Here's the juice:

JUnit Integration and @Unroll
Spock is built on JUnit, and has always had good IDE support without any effort from you as a user. For the most part, the IDEs just think Spock is another unit test. Here's the a Spock spec for the new Data Tables feature and how it shows up in an IDE.

import spock.lang.*

class TableTest extends Specification {

  def "maximum of two numbers"() {
     expect:
     Math.max(a, b) == c

     where:
     a | b | c
     3 | 7 | 7
     5 | 4 | 5
     9 | 9 | 9
  }
}

The assertion will be run 3 times: once for each row in the data table. And JUnit faithfully reports the method name correctly, even when the method names has a space in it:

The problem with data driven tests and xUnit is poor error location. When a test fails you will receive an error stating which method is the culprit... but what if the method runs an assertion across 50 or 60 pieces of data? The cause of a failure is almost never clear with data driven tests. At it's worst you have to step through several iterations of code waiting for an exception. Good tests have a clear point of failure, but good tests also do not repeat themselves with boilerplate. This is exactly why Spock has the @Unroll annotation. As a test author you get to write one concise unit test, and JUnit does the work of reporting results that help you isolate failures. Consider the same test method with the @Unroll annotation and the accompanying IDE output.

@Unroll
def "maximum of two numbers"() {
   expect:
   Math.max(a, b) == c

   where:
   a | b | c
   3 | 7 | 7
   5 | 4 | 5
   9 | 9 | 9
}

When executed, JUnit sees three test methods instead of one: one for each row in the data table:

The end result for you as a test writer is accurate failure resolution. You can pinpoint exactly which row failed. This feature is available in Spock 0.3 and you can use it today. What is new in 0.4 is the ability to change the test name dynamically. Here is a full @Unroll annotation that changes the method name:

@Unroll("maximum of #a and #b is #c")
def "maximum of two numbers"() {
   expect:
   Math.max(a, b) == c

   where:
   a | b | c
   3 | 7 | 7
   5 | 4 | 5
   9 | 9 | 9
}

Notice the #variable syntax in the annotation parameter. The # produces a sort of GString-like variable substitution that lets you bind columns from your data table into your test name. The annotation parameter references #a, #b, and #c, which aligns with the data table definition of a | b | c. Check out the IDE output:

Previously, the test name was just the iteration number within the test. The new @Unroll parameter allows you to make the test name much more meaningful. Your tests will improve because failures become more descriptive. Unrolled failure messages before simply had the iteration name embedded in them, while now they can have meaningful data that you prescribe.

My favorite part of playing with the new @Unroll was to see the default value of the parameter within the Spock source code:

java.lang.String value() default "#featureName[#iterationCount]";

Talk about eating your own dog food... the default value is a test name template, just like you could have written in your own test. Makes you wonder what other variables are in scope, huh?

Spock snapshot builds for 0.4 are available at: http://m2repo.spockframework.org. Get it before the link breaks.