Automating Specification with Cucumber & Grails

Specification by Example is an interesting approach to build a specification in collaboration with a customer. One part of it is to automate the specification without changing it and to build a living documentation system that is always in sync with the software.

One possibility to automate the specification is to describe it using Cucumbers Given, When & Then style and writing some glue code to connect the steps with the system we build.

I will introduce you to a new cucumber grails plugin (grails.org/plugins, documentation) that make it a lot easier to automate cucumber specifications of a Grails application.

The plugin is a functional test plugin for grails and it is only available in grails functional test phase. It is interesting because it runs cucumber inside a running grails application which allows us to use the grails api in the cucumber step implementations. We can call GORM stuff like dynamic finders, services and controllers.

To make the magic work, the plugin is based on Cucumber-JVM the native JVM implementation of cucumber. Cucumber-JVM does support many JVM languages. Groovy is one of them which makes it a perfect fit for grails.

As we will see in the following introduction, the plugin integrates into grails standard test infrastructure which makes it quite easy to use. The full source code of the example and the plugin itself is online in my github repository (example source code, plugin source code).

We will walk through a very simple example that will use cucumber to test two scenarios against a grails web application. We will implement the steps under the skin of the application, i.e. below the ui.
I have written another article (here) that runs the same example against the ui using Geb in the steps to remote control a web browser (Note: because of my latest changes in the plugin the article is no longer 100% up to date).

Let us start with the setup…

setup

First, create a grails app with: grails create-app Books (I am using grails 2.0.3). Next, add the plugin dependency to grails-app/conf/BuildConfig.groovy in the plugins section:

plugins {
   test ":cucumber:0.4.0"
}

Done, setup complete.

.feature files

By convention, the plugin expects all cucumber files (features and steps) in test/functional (you can change it in the configuration, see the documentation).

Create the following two .feature files in test/functional which describe the functionality of the example application:

NewBook.feature:

Feature: new book entry
    As a book owner
    I want to add books I own to the book tracker
    so that I do not have to remember them by myself

Scenario: new book
   Given I open the book tracker
    When I add "Specification by Example"
    Then I see "Specification by Example"s details

ListBooks.feature:

Feature: list owned books
    As a book owner
    I want to list my books
    so that I can look up which books I own

@ignore
Scenario: list existing books
   Given I have already added "Specification by Example"
    When I view the book list
    Then my book list contains "Specification by Example"

Specification by Example: Website, amazon.com

running the features

I already mentioned that the plugin properly integrates into grails and that it is a functional test plugin. To run the cucumber features only we can use the usual grails test-app command using one of the following variations:

grails test-app functional:cucumber
grails test-app :cucumber
grails test-app functional:

Running it we will see the typical cucumber output for missing step implementations:

You can implement missing steps with the snippets below:

Given(~"^I have already added \"([^\"]*)\"$") { String arg1 ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}
When(~"^I view the book list$") { ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}
Then(~"^my book list contains \"([^\"]*)\"$") { String arg1 ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}
Given(~"^I open the book tracker$") { ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}
When(~"^I add \"([^\"]*)\"$") { String arg1 ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}
Then(~"^I see \"([^\"]*)\"s details$") { String arg1 ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}

tagging features

To concentrate on implementing the steps for the NewBook feature we will disable the second one by adding an @ignore tag to it and by telling the plugin to ignore the scenarios tagged with @ignore:

ListBooks.feature:

Feature: list owned books
    As a book owner
    I want to list my books
    so that I can look up which books I own

@ignore
Scenario: list existing books
   Given I have already added "Specification by Example"
    When I view the book list
    Then my book list contains "Specification by Example"

The plugin will pick up a couple of configuration options from grails-app/conf/CucumberConfig.groovy, so we create it and add a tags configuration like this:

cucumber {
    tags = ["~@ignore"]
}

tags is list of strings and each item corresponds to a standard cucumber --tags option.

Running grails test-app :cucumber again, we will only get the missing steps message for the NewBook feature:

You can implement missing steps with the snippets below:

Given(~"^I open the book tracker$") { ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}
When(~"^I add \"([^\"]*)\"$") { String arg1 ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}
Then(~"^I see \"([^\"]*)\"s details$") { String arg1 ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}

implementing steps, part one

Create a new file test/functional/steps/Book_steps.groovy and

• copy the step templates into it
• add an import for PendingException
• mixin the EN language of Gherkin
• escape the $ at the end of the regular expression because in groovy it is a special character in GStrings. Alternativly you can replace the double quotes with single quotes.

Finally it should look like this:

import cucumber.runtime.PendingException

this.metaClass.mixin (cucumber.runtime.groovy.EN)


Given (~"^I open the book tracker\$") { ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}

When (~"^I add \"([^\"]*)\"\$") { String arg1 ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}

Then (~"^I see \"([^\"]*)\"s details\$") { String arg1 ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}

Running again will throw a PendingException. To implement the steps we will need a domain class, a service and a controller. That is what we will do next, step by step…

Given (~‘^I open the book tracker$’)

This step is easy. We want to test under the skin ignoring the ui, so we simply do nothing in this step. In a real project we would probably check that the controller has an action that returns the entry page of our application.

Given (~"^I open the book tracker\$") { ->
    // nop
}

When (~‘^I add “([^"]*)”$’)

In this step we want to add a book. We need a controller with an add action that we will call in the step implementation.

Create a BookController with an add action method. It will get the book details we enter in the ui form and it will return the new Book as JSON that will be shown in the ui. We don’t care what the ui does with it, we will only check that we get the correct JSON.

As is usual in grails the controller will just delegate the work to a service and prepare the result for the ui. In this case rendering the Book as JSON. Here is the controller code:

package books

import grails.converters.JSON

class BookController {
    def bookService

    def add () {
        render bookService.add (params) as JSON
    }
}

The service:

package books

class BookService {
    Book add (Map params) {
        def newBook = new Book (params)
        newBook.save ()
        newBook
    }
}

And finally the Book domain class:

package books

class Book {
    String author
    String title
}

After creating the grails artifacts we can finally implement the step like this:

import books.BookController
import data.Data

// Scenario State
BookController bookController

When (~"^I add \"([^\"]*)\"\$") { String bookTitle ->
    bookController = new BookController ()
    bookController.params << Data.findByTitle (bookTitle)
    bookController.add ()
}

Note the additional imports and the bookController variable we will need to call the controller we create in the Then step.

If you are familiar with Grails you will probably understand most of it. We are simply using grails standard integration test logic for controllers.

Data is a small helper class that will lookup all the properties of a book identified by the bookTitle. This has the advantage that we do not have to list all properties of a book in the .feature file and the feature is more robust against changes like adding an additional property. That the additional property gets handled properly would be tested on the integration or unit test level.

Here is the source for test/functional/data/Data.groovy:

package data

import books.Book


class Data {
    static def books = [
        [title: "Specification by Example", author: "Gojko Adzic"]
    ]

    static public def findByTitle (String title) {
        books.find { book ->
            book.title == title
        }
    }

    static void clearBooks () {
        Book.findAll()*.delete (flush: true)
    }
}

Running the features now will still fail with a rather obscure java.lang.IllegalStateException exception (I guess at least for most of us, count me in). We are calling the controller outside of a real http request and to fix this we have to add a few simple lines of setup and tear down code.

Before & After

If we are building normal integration tests for a controller, grails will take care of setting up the test environment in a way that we will not get the IllegalStateException, that we have a mock request and response etc. and that we can set the request parameters with bookController.params = ... .

When we run cucumber we have to take care of this ourself. Let’s create a new file test/functional/hooks/env.grooy with the following content:

import org.codehaus.groovy.grails.test.support.GrailsTestRequestEnvironmentInterceptor

this.metaClass.mixin (cucumber.runtime.groovy.Hooks)


GrailsTestRequestEnvironmentInterceptor scenarioInterceptor

Before () {
    scenarioInterceptor = new GrailsTestRequestEnvironmentInterceptor (appCtx)
    scenarioInterceptor.init ()
}

After () {
    scenarioInterceptor.destroy ()
}

Running cucumber now will fail with a PendingException from our last step in this scenario. We still have to check that the result is correct to finish our first scenario.

Then (~‘^I see “([^"]*)”s details$’)

We need to assert that the returned JSON has an id (so we know it was save()d) and author and title with the same values we passed to the BookController:

Then (~"^I see \"([^\"]*)\"s details\$") { String bookTitle ->
    def expected = Data.findByTitle (bookTitle)
    def actual = bookController.response.json

    assert actual.id
    assert actual.title  == expected.title
    assert actual.author == expected.author
}

Next run and we see:

> grails test-app :cucumber --stacktrace
| Server running. Browse to http://localhost:8080/Books
| Running 1 cucumber test...
| Completed 1 cucumber test, 0 failed in 1623ms
| Server stopped
| Tests PASSED - view reports in target/test-reports

Great, the scenario passed! Now let’s finish our example application by implementing the steps for the ListBooks feature. There is a little bit more :-)

implementing steps, part two

First remove the @ignore tag from the list existing books scenario and run it again to get the templates for the missing steps and copy them to the BookSteps.groovy file (don’t forget to escape the ‘$’):

Given(~"^I have already added \"([^\"]*)\"$") { String arg1 ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}
When(~"^I view the book list$") { ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}
Then(~"^my book list contains \"([^\"]*)\"$") { String arg1 ->
    // Express the Regexp above with the code you wish you had
    throw new PendingException()
}

Given (~‘^I have already added “([^"]*)”$’)

We want to pre-populate our database. We will reuse our BookService to create a new Book in the database. Reusing our business code to setup test data looks like a good idea to make sure that the we get proper data into the database without duplicating the code for our tests.

Here is the code:

Given (~"^I have already added \"([^\"]*)\"\$") { String bookTitle ->
    def bookService = appCtx.getBean ("bookService")
    bookService.add (Data.findByTitle (bookTitle))
}

Now that we have two features running and interacting with the database we should also take care of cleaning up the database after each scenario.

more Before & After

Here is the additional code for test/functional/hooks/env.groovy:

import data.Data

Before () {
    ....
    Data.clearBooks ()
}

After () {
    ....
}

You can also add the the cleanup to the After hook. I have choosen to add it to the setup because if a scenario fails we can still look at its database state. Maybe it will help to diagnose the problem.

When (~‘^I view the book list$’)

Not much new here, we have to deliver the full list of books. We get it by adding a new all() action method to the controller that will return the list as JSON.

Here is the step code:

When (~"^I view the book list\$") { ->
    bookController = new BookController ()
    bookController.all ()
}

Here the new methods for the controller:

....    
class BookController {
    ....    
    def all () {
        def books = bookService.all ()
        render books as JSON
    }
}

.. and the service:

class BookService {
    ....
    List<Book> all () {
        Book.findAll ()
    }
}

Running again fails with the now common PendingException in the last step.

Then (~‘^my book list contains “([^"]*)”$’)

We check that the returned list contains the book we have pre-populated to the database in the Given step.

Here is the code:

Then (~"^my book list contains \"([^\"]*)\"\$") { String bookTitle ->
    def expected = Data.findByTitle (bookTitle)
    def all = bookController.response.json
    actual = all.getJSONObject (0)

    assert actual.id
    assert actual.title  == expected.title
    assert actual.author == expected.author
}

It is nearly the same as the previous Then check in the first feature, we just have to extract the object from the list first. We should probably refactor the assertions to a method and use that in both Then steps. We will keep that as an exercise for you ;-)

Running the test will report two passed cucumber features:

> grails test-app :cucumber --stacktrace
| Server running. Browse to http://localhost:8080/Books
| Running 2 cucumber tests...
| Completed 2 cucumber tests, 0 failed in 1612ms
| Server stopped
| Tests PASSED - view reports in target/test-reports

In case you have not noticed, we are done! ;-)

Summary

Congratulations, you have succesfully implemented two features for our example application! :-)

We have implemented a couple of cucumber steps using a grails domain class, a service, a controller and a few lines of code for the before and after hooks. We have seen were to put the feature files and the step implementations and how we can configure @tags.

This should cover the basics to get you started with cucumber and grails. :-)

Happy Cuking!