An Introduction to Using Cucumber-JVM

Written by Jeff Nyman 15 June 2014 9 Comments

A lot of testers I run into learn Cucumber on Ruby. This tends to be a very easy path since the overhead on a dynamic language like Ruby is generally pretty low. However, some testers need or want to run Cucumber on the Java Virtual Machine. Yes, you can use JRuby to run the Ruby version of Cucumber on the JVM. But you can also use Cucumber-JVM, which is a port of the Ruby version into Java. However, I find many testers have a hard time getting started with it, particularly if they are coming from Ruby. What follows is the tutorial I wanted and either didn’t find or didn’t look hard enough to find.

To follow along, make sure you have a Java development environment set up on your machine. This means the JDK as well as the JRE. I should note that I have done all of the steps below on Java 1.5 up to 1.8.

You are also going to need Maven for what I show you. Note that you can use Ant if such is your preference but many people seem to be using Maven. The setup for Maven is generally simple: unzip the distribution, create an M2_HOME environment variable, and add M2_HOME/bin to your path. To test that Maven is working:

$ mvn -v

If you do want to use Ant, setting it up is quite similar. Create an environment variable called ANT_HOME, add ANT_HOME/bin to your path. To test it:

$ ant -v

There are ways to do everything I do in this post via Eclipse, NetBeans, IntelliJ or whatever editor you prefer for Java. For this post, I’m going to focus on the command line mainly because I believe any test framework should be understandable and easily manipulable via the command line before you bring a graphical user interface into the mix. However, feel free to use whatever method you like.

Creating Your Project, Maven Style

To get started with the Maven approach, first create a project using the following command:

mvn archetype:generate -DgroupId=nostalgic.textadv.voxam -DartifactId=Voxam -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

I don’t want this to turn into a Maven tutorial but basically what this is doing is creating a simple project to get started. The project directory will be called Voxam (which matches the Artifact ID above) and the Java package structure will use what you specify in the Group ID (nostalgic.textadv.voxam, in my case). When the above command runs, you should have this structure:

Voxam
|   pom.xml
|
----src
    ----main
    |   ----java
    |       ----nostalgic
    |           ----textadv
    |               ----voxam
    |                       App.java
    |
    ----test
        ----java
            ----nostalgic
                ----textadv
                    ----voxam
                            AppTest.java

After creating a new Maven project, you’ll generally need to either add some dependencies to your project’s pom.xml file or update the existing ones. We’re going to do both. First change your existing pom.xml file so that it uses JUnit 4 instead of JUnit 3:

...
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.11</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
...

...

<groupId>junit</groupId>

<artifactId>junit</artifactId>

</dependency>

</dependencies>

...

Now, still in the pom, add the dependencies you need to get Cucumber-JVM as part of your project:

...
  <dependencies>
    <dependency>
      <groupId>info.cukes</groupId>
      <artifactId>cucumber-java</artifactId>
      <version>1.1.7</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>info.cukes</groupId>
      <artifactId>cucumber-junit</artifactId>
      <version>1.1.7</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
...

...

<groupId>info.cukes</groupId>

<artifactId>cucumber-java</artifactId>

</dependency>

<groupId>info.cukes</groupId>

<artifactId>cucumber-junit</artifactId>

</dependency>

<groupId>junit</groupId>

...

It doesn’t matter what order you put these dependencies in. I put them above the junit one but it’s up to you.

Incidentally, this is where I start to lose some Ruby purists. Some testers coming from the Ruby world feel that all of the above is much more complicated. On the one hand, I sympathize but on the other hand I try to caution testers about this. Yes, Java is famous for setting up lots of directories that correspond to packages, which is often why you need a high-end IDE to even work with Java. And, yes, XML is a bloated beast and is a bit old-school, compared to upstarts like JSON or YAML. However, once you get past that, the pom.xml is conceptually no different at all than using a Gemfile and Bundler in Ruby. The nice thing is that once you have your pom file structure set, you rarely have to worry about it.

So my advice to Rubyists: don’t judge everything you do with Java against the standard of how you do it in Ruby. If it helps, there’s often just as much culture shock for Java developers going to Ruby.

One thing I should note is that with the specific version numbers referenced in the pom.xml file above, I’m using the most stable versions that exist at the time of writing this post. These may be different by the time you read this. In any event, to make sure everything works, let’s run the following command:

mvn test

If this is your first time using Maven or your first time using these particular dependencies, you will see a long string of files that are being downloaded into the global maven repository. You ultimately should see something like this as output:

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running example.atm.AppTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.063 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

[INFO] --------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] --------------------------------------------------------------
[INFO] Total time: 3.407 s

The actual test that’s being run there is that of the AppTest.java file, which references the App.java file. These pre-generated files are basically in place to make the initial Maven structure work but they also give you a clue as to how your eventual Cucumber project is going to need to be set up.

At this point, get rid of the App.java and AppTest.java files. You certainly aren’t going to use them since they are nothing more than stub files to get you a working Maven Java project. Now let’s make sure that we’ll start out with a clean build. Run the following:

mvn clean

The above path structure, generated by Maven, will provide a location for what Cucumber-JVM calls step definitions as well as for any application logic or test helper code. We’ll get to that in a bit. But first, in order to have something to test, I need an application.

Application Logic

You can use Cucumber-JVM to directly test against the code of a working application or you can use it to test a remote application, without touching the actual application code at all. Here I’ll focus on the former; in another post, I’ll tackle the latter.

So to do this, let’s put a simple application in place and, further, let’s put some unit tests in place for it as well. Then, when we’ve got that, we can put some feature files in front of that application and put Cucumber-JVM through its paces. For this next bit, I’m going to use a simple text parser application I wrote for the purposes of this post. Rather than have you type a whole bunch of stuff in, grab the following two files and put them in src/main/java/nostalgic/textadv/voxam.

You can run the following to make sure those compile:

mvn compile

If you want to make sure the application actually works, you can do this from Maven:

mvn exec:java -Dexec.mainClass="nostalgic.textadv.voxam.Parser"

You can also just run it directly from within the Voxam directory:

java -cp target/classes nostalgic.textadv.voxam.Parser

Somewhere in the output, you’ll see this:

Parse Command: cut tree with chainsaw
Verb: cut
Direct Object: tree
Indirect Object: chainsaw

So with that we know we have a working application. Now let’s put in some unit tests for the app. Again, rather than have you type it out, put the following file in src/test/java/nostalgic/textadv/voxam.

ParserTest.java

Now let’s see if the tests run against the application:

mvn test

You should see that 11 tests are run and you should get no errors.

Now let’s start using Cucumber-JVM to test the application at an an acceptance level.

Feature Files

You have to create a directory structure where Cucumber will expect your features files to be. At minimum, you can create the following:

mkdir src/test/resources

Now here’s an interesting thing. You could just put your feature files right in that “resources” directory. However, you can also create a structure within resources that matches your application code package structure. But it doesn’t seem that you have to. This is an area of Java that I’m still learning, to be honest, so here’s what I did. I created the following directory:

mkdir src/test/resources/nostalgic/textadv/voxam

Just to be clear, that gives me the following directory structure:

----src
    ----main
    |   ----java
    |       ----nostalgic
    |           ----textadv
    |               ----voxam
    ----test
        ----java
        |   ----nostalgic
        |       ----textadv
        |           ----voxam
        ----resources
            ----nostalgic
                ----textadv
                    ----voxam

Now create a file called parser.feature in src/test/resources/nostalgic/textadv/voxam.

Let’s write the start of a simple scenario.

Ability: Parsing User Input

  Background:
    Given the game parser
    
  Scenario: Parse a valid single word command
    When the command "inventory" is parsed
    Then the verb is "inventory"
    And  there is no direct object
    And  the parser response is "Success"

Now we have to execute the feature file, which essentially means parsing it and determining which, if any, of the phrases are matched by step definitions. The feature file is just a text file with English statements, as opposed to source code. Unlike Ruby Cucumber, which serves as its own runner for executing feature files, Cucumber-JVM requires you to create a runner.

Test Runner

With Cucumber-JVM, you run the feature files using a JUnit Runner, which you will already have available to you from the Cucumber-Junit Library that you referenced in your pom file. (You can use other test runners, like TestNG, if you want.)

What this means is that you need to create a test class, and annotate it with JUnit’s @RunWith annotation. So first create a file called TestRunner.java in src/test/java/nostalgic/textadv/voxam. Note I’m keeping everything I do in the same package here. Does that matter? I’m going on the assumption that it does for the moment but I’ll revisit this later. Do note that the actual file name here does not matter; call it whatever you like. Here’s what should go in it:

import org.junit.runner.RunWith;

import cucumber.api.junit.*;

@RunWith(Cucumber.class)
public class TestRunner {}

import org.junit.runner.RunWith;

import cucumber.api.junit.*;

@RunWith(Cucumber.class)

public class TestRunner {}

Now let’s execute what we have and see if anything happens. Run this command:

mvn test -q

This is just running the Maven test goal with the quiet option just to keep the output down to a dull roar. What should happen is that your feature file is read and Cucumber-JVM reports by saying that you have undefined steps and some step definitions are provided for you to use. Also important to note is that your unit tests are still running as part of this. Specifically, you’ll see output like this:

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running nostalgic.textadv.voxam.ParserTest
Tests run: 11, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.078 sec
Running nostalgic.textadv.voxam.TestRunner
UUUUU

1 Scenarios (1 undefined)
5 Steps (5 undefined)
0m0.000s

The ParserTest are the unit tests that I had you put in place. The TestRunner is, of course, the runner we just created to parse the feature files.

Now let’s get into making the feature file executable.

Step Definitions

Okay, so to make this work, create a step definition file. Create ParserSteps.java in the src/test/java/nostalgic/textadv/voxam directory. The name of the file does not matter. The file should look like this:

package nostalgic.textadv.voxam;

import cucumber.api.java.en.Given;
import cucumber.api.java.en.When;
import cucumber.api.java.en.Then;

import cucumber.api.PendingException;

public class ParserSteps {
  @Given("^the game parser$")
  public void the_game_parser() throws Throwable {
    // Write code here that turns the phrase above into concrete actions
    throw new PendingException();
  }

  @When("^the command \"(.*?)\" is parsed$")
  public void the_command_is_parsed(String arg1) throws Throwable {
    // Write code here that turns the phrase above into concrete actions
    throw new PendingException();
  }

  @Then("^the verb is \"(.*?)\"$")
  public void the_verb_is(String arg1) throws Throwable {
    // Write code here that turns the phrase above into concrete actions
    throw new PendingException();
  }

  @Then("^there is no direct object$")
  public void there_is_no_direct_object() throws Throwable {
    // Write code here that turns the phrase above into concrete actions
    throw new PendingException();
  }

  @Then("^the parser response is \"(.*?)\"$")
  public void the_parser_response_is(String arg1) throws Throwable {
    // Write code here that turns the phrase above into concrete actions
    throw new PendingException();
  }
}

package nostalgic.textadv.voxam;

import cucumber.api.java.en.Given;

import cucumber.api.java.en.When;

import cucumber.api.java.en.Then;

import cucumber.api.PendingException;

public class ParserSteps {

@Given("^the game parser$")

public void the_game_parser() throws Throwable {