Overview

In this tutorial, we will create some tests in Cucumber using Java.

Cucumber is mainly a collaboration framework used in BDD context in order to improve shared understanding within the team, usually during "3 Amigos" sessions. That's its main fit.

However, some teams use it in other contexts (e.g. after sofware has being built) for implementing automated tests and take advantage of Gherkin syntax to have visibility/abstraction of the underlying automation code and have reusable automation code.

(Test) Scenarios derived from Cucumber are executable specifications; their statements will have a corresponding code implementation. These test scenarios are feature and more business oriented; they're not unit/integration tests.

Your specification is made using Gherkin (i.e. Given, When, That) statements in Scenario(s) or Scenario Outline(s), eventually complemented with a Background. Implementation of each Gherkin statement (i.e.  "step") is done in code; the Cucumber framework finds the code based on a regular or cucumber expression.

Usage scenarios

Cucumber is used in diverse scenarios. Next you may find some usage patterns, even though Cucumber usage is mostly recommended only if you are adopting BDD.

1. Teams adopting BDD, start by defining a user story and clarify it using Cucumber Scenario(s); usualy, Cucumber Scenario(s)/Scenario Outline(s) are specified directly in Jira, using Xray
2. Teams adopting BDD but that favour a more Git based approach (e.g. GitOp). In this case, stories would be defined in Jira but Cucumber .feature files would be specified using some IDE and would be stored in Git, for example
3. Teams not adopting BDD but still using Cucumber, more as an automation framework. Sometimes focused on regression testing; sometimes, for non-regression testing.
   1. With a user story or some sort of "requirement" described in Jira
   2. Without any story/"requirement" described in Jira

You may be adopting, or aiming to, one of the previous patterns.

Before moving into the actual implementation, we need to decide which workflow we'll use: do we want to use Xray/Jira as the master for writing the declarative specification (i.e. the Gherkin based Scenarios), or do we want to manage those outside using some editor and store them in Git, for example?

Requirements

• Java
• Add the dependency of cucumber-jvm (i.e. cucumber-java) to your maven "pom.xml" file

Examples

For the purpose of this tutorial, we'll use a simple, dummy Calculator implemented in a Java class as our target for testing.

package com.xray.tutorials;

public class Calculator
{
// Square function
public static int Square(int num)
{
    return num*num;
}
// Add two integers and returns the sum
public static int Add(int num1, int num2 )
{
    return num1 + num2;
}
// Add two integers and returns the sum
public static double Add(double num1, double num2 )
{
    return num1 + num2;
}
// Multiply two integers and retuns the result
public static int Multiply(int num1, int num2 )
{
    if ((num1==1) || (num2==1)) {
        return 0;
    } else {
        return num1 * num2;
    }
}



public static int Divide(int num1, int num2 )
{
    return num1 / num2;
}

// Subtracts small number from big number
public static int Subtract(int num1, int num2 )
{
    if ( num1 > num2 )
    {
    return num1 - num2;
    }
    return num2 - num1;
    }
}

Using Jira and Xray as master

This section assumes using Xray as master, i.e. the place that you'll be using to edit the specifications (e.g. the scenarios that are part of .feature files).

The overall flow would be something like this, assuming Git as the source code versioning system:

1. define the story (skip if you already have it)
2. create Scenario/Scenario Outline as a Test in Jira; usually, it would be linked to an existing "requirement"/Story (i.e. created from the respective issue screen)
3. implement the code related to Gherkin statements/steps and store it in Git, for example. To start, and during development, you may need to generate/export the .feature file to your local environment
4. commit previous code to Git
5. checkout the code from Git
6. generate .feature files based on the specification made in Jira
7. run the tests in the CI
8. obtain the report in Cucumber JSON format
9. import the results back to Jira

Note that steps (5-9) performed by the CI tool are all automated, obviously.

To generate .feature file(s) based on Scenarios defined in Jira (i.e. Cucumber Tests and Preconditions), we can do it directly from Jira, by the REST API or using a CI tool; we'll see that ahead in more detail.

Example

All starts with a user story or some sort of “requirement” that you wish to validate. This is materialized as a Jira issue and identified by the corresponding issue key (e.g. CALC-7931).

We can promptly check that it is “UNCOVERED” (i.e. that it has no tests covering it, no matter their type/approach).

In this case, we'll create a Cucumber Test, of Cucumber Type "Scenario".

We can fill out the Gherkin statements immediately on the Jira issue create dialog or we can create the Test issue first and fill out the details on the next screen, from within the Test issue. In the latter case, we can take advantage of the built-in Gherkin editor which provides auto-complete of Gherkin steps.

After the Test is created it will impact the coverage of related "requirement", if any.

The coverage and the test results can be tracked in the "requirement" side (e.g. user story). In this case, you may see that coverage changed from being UNCOVERED to NOTRUN (i.e. covered and with at least one test not run).

Additional tests could be created, eventually linked to the same Story or linked to another one (e.g. multiplication).

The related statement's code is managed outside of Jira and stored in Git, for example.

The tests related code is stored under src/test directory, which itself contains several other directories. In this case, they're organized as follows:

• cypress/integration/common: step implementation files, in JavaScript.

The steps "glue-code" is defined in a class.

package calculator;

import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;
import com.xray.tutorials.Calculator;

import static org.junit.Assert.*;

public class StepDefinitions {
    private Integer int1;
    private Integer int2;
    private Integer result;


    @Given("I have entered {int} into the calculator")
    public void i_have_entered_into_the_calculator(Integer int1) {
        this.int2 = this.int1;
        this.int1 = int1;
    }
    
    
    @When("I press add")
    public void i_press_add() {
        this.result =  Calculator.Add(this.int1, this.int2);
    }

    @When("I press multiply")
    public void i_press_multiply() {
        this.result =  Calculator.Multiply(this.int1, this.int2);
    }


    @Then("the result should be {int} on the screen")
    public void the_result_should_be_on_the_screen(Integer int1) {
        // Write code here that turns the phrase above into concrete actions
        assertEquals((Integer)(this.int1 + this.int2), this.result);
    }
    

}

You can then export the specification of the test to a Cucumber .feature file via the REST API, or the Export to Cucumber UI action from within the Test/Test Execution issue or even based on an existing saved filter. A plugin for your CI tool of choice can be used to ease this task.

So, you can either:

• use the UI
  • 
• use the REST API (more info here)

  • #!/bin/bash   rm -f features/*.feature curl -u admin:admin  "http://jiraserver.example.com/rest/raven/1.0/export/test?keys=CALC-7905;CALC-7906&fz=true" -o features.zip unzip -o features.zip  -d features

• use one of the available CI/CD plugins (e.g. see an example of Integration with Jenkins)

Description

We will use the code from the Github repository "cucumber-java-skeleton", with slight changes in order to make the dummy Test pass.

The first step is to create a Cucumber Test, of Cucumber Type "Scenario", in Jira. The specification would be exactly the same as the one provided in the original repository.

After creating the Test in Jira and associating it with requirements, etc., you can export the specification of the test to a Cucumber .feature file via the REST API or the Export to Cucumber UI action from within the Test Execution issue.

The created file will be similar to the original, but will contain the references to the Test issue key and the covered requirement issue key.

 @ABC-100
 Feature: Belly

  @ABC-122
  Scenario: a few cukes
    Given I have 42 cukes in my belly
    When I wait 1 hour
    Then my belly should growl

You can change the implementation of the steps in order to make them pass quickly.

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

public class Stepdefs {
    @Given("^I have (\\d+) cukes in my belly$")
    public void I_have_cukes_in_my_belly(int cukes) throws Throwable {
        Belly belly = new Belly();
        belly.eat(cukes);
    }
    
    
    @When("^I wait (\\d+) hour$")
    public void I_wait_hours(int hours) throws Throwable {
        Thread.sleep(hours*0);
    }
    
    @Then("^my belly should growl$")
    public boolean my_belly_should_growl() throws Throwable {
        return true;
    }
}

After running the tests and generating the Cucumber JSON  report (e.g., data.json), it can be imported to Xray via the REST API or the Import Execution Results action within the Test Execution.

mvn compile test -Dcucumber.options="-p json:data.json"

The execution screen details will provide information on the test run result.

References

• Sample project cucumber-java-skeleton
• Official Cucumber documentation
• Cucumber installation instructions for Java
• Cucumber API
• Cucumber expressions
• Testing in BDD with Gherkin based frameworks (e.g. Cucumber)
• Automated Tests (Import/Export)
• Exporting Cucumber Tests - REST