Cucumber(一): Preparation

Every time I wrote some code in ruby and executed our cucumber features I craved for something similar in Java. I knew that there were several BDD frameworks for Java like JBehave, JDave, and EasyB, but none of them was right for me: either it used another language - like groovy -, had some unnecessary dependencies, or was hard to integrate with eclipse. A couple of weeks ago, I was looking for something in the source code of cucumber and found out that Aslak Hellesøy - author of cucumber - is working on a pure Java based implementation. It hasn’t been released yet, but I decided to give it a try and see what it can do.

The Basics

If you are not familiar with the BDD concept I recommend to read Dan North’s article before continuing. BDD means Behavior Driven Development, and in a nutshell, it means that you specify on a higher level, in a readable form, how the system is supposed to work. Programmers tend to call BDD the big brother of TDD, because TDD works on a class level, and BDD on the system level, but this isn’t 100 percent true: for me TDD defines what an entity - system or class - should exactly do, and BDD defines how it should work. There is a tiny difference, but it is recognizable.

Let’s see a very simple example:

Feature: simple text munger kata
Scenario: Do nothing with a two-letter word
  Given I have an instance of my class
   When I call my method with "an"
   Then I receive "

The snippet above is self-explanatory: what my feature is supposed to do is described in Gherkinlanguage.

The Test Classes

When I try out a new framework, I use a Kata exercise. This time, I’ll try to implement a simple version of the famous text munger kata. Given an input sentence, modify it in the following way: in each word keep the first and the last letter, but the rest shall be returned in reverse order - in the original kata the rest should be randomized. For example:

In:   And the spice must flow
Out: And the scipe msut folw

As you can see, it will be simple, because my goal is to learn how to use cucumber under Java - I’ll refer to it as cucumber-jvm -, not to finish the kata exercise properly. Enough talking, let’s take out our eclipse and start working.

The first thing is to save the feature above into a .feature file where cucumber can find it. I’ll use the standard directory layout and create a simple_text_munger.feature file with the content above in src/test/resources:

Every feature should have its own .feature file. A feature may have multiple scenarios, and every scenario may have multiple steps. A step can be used in different scenarios and even across different features. This is not cucumber-jvm specific, this is how cucumber organizes its files.

Having a single .feature file has no use. Somehow the system should interpret this file and execute the referenced steps:

SimpleTextMunger_Test.java

package com.zsoltfabok.blog;

import cucumber.junit.Cucumber;
import cucumber.junit.Feature;
import org.junit.runner.RunWith;

@RunWith(Cucumber.class)
@Cucumber.Options(features = "classpath:simple_text_munger.feature")
public class SimpleTextMunger_Test {
}

Java is not a dynamic language like ruby and it cannot “execute” a plain .feature file: it requires a wrapper file which loads the feature and executes it. Based on the examples ofcucumber-jvm, let’s name this file after the .feature and use the _Test suffix. The underscore differentiates the file from a regular Test file (update: after writing a couple of more features, I felt more comfortable with the Feature suffix, but for this example I kept the _Test in order keep the consistency between the posts and the source code). There is no need to put anything into the body of the wrapper class.

In cucumber, every ”sentence” is considered as a step which needs to be implemented. For example:

SimpleTextMungerStepsdef.java

import cucumber.annotation.en.Given;
import cucumber.annotation.en.Then;
import cucumber.annotation.en.When;

public class SimpleTextMungerStepsdef {
  @Given("^I have an instance of my class$")
  public void I_have_an_instance_of_my_class() {
    // Express the Regexp above with the code you wish you had
  }

  @Then("^I receive \"([^\"]*)\"$")
  public void I_receive_(String arg1) {
    // Express the Regexp above with the code you wish you had
  }

  @When("^I call my method with \"([^\"]*)\"$")
  public void I_call_my_method_with_(String arg1) {
    // Express the Regexp above with the code you wish you had
  }
}

Exactly like in cucumber, cucumber-jvm maps each ”sentence” to a step. When I run my .feature, it will call the proper step method. If a step definition cannot be found, cucumber-jvmwill generate it for you and write it to the console. Mind the Stepdef suffix in the name of the class. It is not mandatory - everything works without it, because cucumber-jvm finds the definitions using reflection -, but it looks like a reasonable convention.

Compiling

The test classes are in place, let’s run the test cases. We’ll need the jar files of cucumber-jvm. They can be installed with maven, but since I’m not a huge fan of maven, and I need something easy to use for this example, I’m going with ivy. You can download and set the dependencies using the command line or the ivyDE eclipse plugin:

blog.cucumberjvm % ivy
...
  confs: [compile, test]
  found junit#junit;4.10 in public
  found org.hamcrest#hamcrest-core;1.1 in public
  found info.cukes#cucumber-java;1.0.14 in public
  found info.cukes#cucumber-core;1.0.14 in public
  found info.cukes#cucumber-jvm-deps;1.0.3 in public
  found info.cukes#gherkin;2.11.2 in public
  found info.cukes#gherkin-jvm-deps;1.0.2 in public
  found info.cukes#cucumber-junit;1.0.14 in public
:: resolution report :: resolve 519ms :: artifacts dl 26ms
  ---------------------------------------------------------------------
  |                  |            modules            ||   artifacts   |
  |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
  ---------------------------------------------------------------------
  |      compile     |   8   |   0   |   0   |   0   ||   14  |   0   |
  |       test       |   8   |   0   |   0   |   0   ||   14  |   0   |
  ---------------------------------------------------------------------
blog.cucumberjvm %

Run the First Test

No compilation errors, let’s run the SimpleTextMunger_Test as a JUnit test. It looks good to me:

In the next post I’m going to continue with more scenarios and see how the cucumber-jvmhandles tables in a .feature file. Until then, you can find the source for this post under the episode_1 branch of the repository on github. Stay tuned!