Skip to main content

7 min read

An essential guide to agile testing with BDD inside Jira

Vitor Pelizza
29 August 19 Jira
An essential guide to agile testing with BDD inside Jira
alert2 Icon
The content of this blog is no longer updated

An essential guide to agile testing with BDD inside Jira

Creating great software doesn't just happen by magic. It's not just about having great code either (though that is pretty important). It's about great communication. This is where Behaviour Driven Development (BDD) comes into play.

As well as forming an excellent foundation for robust testing practices, BDD builds a bridge between technology teams and business stakeholders, aligning everyone's views, requirements, and expectations from the start.

If you already use Jira to track and manage development projects, can you add BDD into the mix? The answer is you can, but it's a challenge. For example, with Jira you don't have out-of-the-box capabilities for writing and linking your BDD scenarios and user stories, or integrating with other automated testing tools. But fear not. In this post, we'll walk you through everything you need to know, step-by-step, on how to get started with BDD right inside Jira.

Why have Behaviour Driven Development inside Jira?

If your team is creating BDD test scenarios, it makes sense they should sit alongside related users stories and requirements. Having BDD inside Jira means that everything is connected - epics, stories, tests scenarios, and development data. This way, Jira becomes the project source of truth, improving communication, and creating a shared understanding of what needs to achieved and why.

BDD starts when you define user stories or epics. The intended behaviour of users stories and epics is described using natural language, in the form of test scenarios. Later in their lifetime, these BDD test scenarios will be coded as automated tests, transforming these static documents into a living software specification. A continuous integration server can execute these test scenarios for every change in the codebase. Ideally, these test results would then be published back to Jira, completing the cycle, and providing feedback to testers and business stakeholders on the results.

image2019 1 11 14 49 31

Getting started with BDD using Adaptavist Test Management for Jira

Adaptavist Test Management for Jira (TM4J) provides an easy and intuitive way of using BDD in Jira. As an example, let's say you are developing a web application that is intended to be a calculator. Your calculator may have many different functions, so let's start with a user story to describe one of these functions:

// Code box




As a math student

I want to multiply two numbers and see the result

So that I can save time when doing my homework

This story can now be seen in Jira, in our Agile project:

image2019 7 26 14 22 26

Now that we have our first user story, it's time to flesh out its intended behaviour using BDD.


1) Writing BDD test scenarios

Now that we have our first user story, we need to describe its behaviour using natural language, which is usually done when stories are being defined. This can be during the sprint planning or even earlier than that, during a backlog grooming session, for example. The behaviour we expect to see for that user story can then be described using Gherkin language:

// Code box




Given a calculator I just turned on

When I input the number <a>

And I input the number <b>

And I press the multiplication button

Then I should see the result <c> on the calculator display



Screenshot 2019 08 07 12.03.31


Note that the scenario above is using multiple variations for the same behaviour, by making use of the keyword Examples.

Now we need to create a test case linked to our user story. To create a linked test case, we need to navigate to the user story, and click the + button:

 image2019 7 26 14 22 0

On the test case screen, after typing some standard data on the first tab, we then go to the "test script" tab to type our BDD test scenario:

image2019 7 26 14 20 38

The next step now is automating this BDD test scenario.

2) Coding step definitions

Step definition is the code that will execute tests defined using Gherkin language. It is common to call them the "glue code," given the step definition is the bit that glues the behaviour specification (test scenario) to the actual implementation of automated tests.

All code should be stored in a version control system, like Bitbucket, as will the step definitions. Basically, this Bitbucket repository will have the implementation of the step definitions and a Cucumber test runner configuration:

Step definition implementation:

// Code box




public class CalculatorTest {
    private Calculator c;
    @Given("^a calculator I just turned on$")
    public void aCalculatorIJustTurnedOn() {
        c = new Calculator();
    @When("^I input the number (\\d+)$")
    public void numbersAreMultiplied(long numberInput) {
    @And("^I press the multiplication button$")
    public void numbersAreMultiplied() {
    @Then("^I should see the result (\\d+) on the calculator display$")
    public void numbersAreSummedUp(int expectedResult) {
        assertEquals(expectedResult, c.getDisplayResult());

Cucumber test runner configuration:

// Code box




        features = "src/test/resources/calculatorFeatures"
        ,plugin = {"json:target/cucumber/calculator.json"}

The examples above are available here.

From this point, there are two options for executing tests using the BDD scripts defined in TM4J, and then publishing the test results:

  1. Use the public API to download the feature files to the folder specified on the Cucumber test runner implementation (src/test/resources/calculatorFeatures) and then publish the test results to TM4J. The API documentation is available here. 
  2. Configure a Jenkins job to run tests automatically and have this process of downloading feature files and publishing test results handled by the TM4J Jenkins plugin.

For option one, a bit of coding will be necessary to make the REST API calls. The second approach is more automatic, since it delegates all the work to the TM4J Jenkins plugin.

Setting up continuous integration with Jenkins

Now that stories are created in Jira, and linked to BDD test cases. And the step definitions (or glue code) is already implemented, Jenkins can finally be configured to run the tests. The requirements for this step are:

  1. Jenkins is installed, up and running
  2. The TM4J Jenkins plugin is installed on Jenkins


The TM4J Jenkins plugin is available for all Jira deployments: Server, Data Center and Cloud.

Once those requirements are met, a new Jenkins job will be configured in order to:

  1. Checkout project source code (step definitions and test runner configuration)
  2. Download feature files from TM4J
  3. Execute all BDD tests
  4. Publish test results back to TM4J

The first step is configuring the TM4J plugin on Jenkins. All you need to do is to navigate to "Manage Jenkins > Configure System", and scroll down to the Test Management for Jira section. On that section, the only requirement is to add a Jira instance with URL and credentials. This Jira instance is where feature files will be downloaded, and later where test results will be published. Note that this Jira instance must have TM4J installed and running:

image2019 7 26 14 17 19

Once this configuration is done, you are ready to create a Jenkins job. Navigate to "Jenkins home" and click "New item". Any job type will work, but let's pick the Freestyle project:

image2019 7 26 14 23 28

Click OK and off you go to the job configuration. Here we need to do a number of configurations. The first one is our code repository, where the source code will be pulled from:

 image2019 7 26 15 14 39

You then need to download the feature files from TM4J. For that, you need to add a build step called "Test Management for Jira: Download Feature Files". Also, you will invoke some Maven goals in order to clean the target directory and run the tests, using a build step called "Invoke top level Maven targets". This is how the build configuration will look:

image2019 7 26 15 14 40 

You are ready to run our Jenkins job for the first time now! Navigate back to the Jenkins job and click "Build Now".

4) Publishing test results to Jira

At this point, all your tests have been run. Now it's time to publish results back to TM4J, so that you can generate and analyse the test reports. When the BDD tests are executed, they will produce a JSON file containing all test results, and that is the file that will be uploaded to TM4J. Once TM4J receives that file, a new Test Cycle will be created with those results.

Configuring this integration is easy. In order to do that, navigate to our Jenkins job, click "Configure", and add a post-build step called "Test Management for Jira: Publish Test Results". Here is how its configuration will look:

Post build

Now that everything is configured, build the Jenkins job one more time. After the Jenkins job has finished executing, the Jenkins job log file should have printed out the link to the newly created Test Cycle.

// Code box




[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.861 s
[INFO] Finished at: 2019-07-26T14:40:20Z
[INFO] ------------------------------------------------------------------------
[Test Management for Jira] [INFO] Publishing test results...
[Test Management for Jira] [INFO] Test Cycle created with the following KEY: VIT-C146. https://my-jira-instance/secure/Tests.jspa#/testPlayer/VIT-C146
[Test Management for Jira] [INFO] Test results published to Test Management for Jira successfully.
Finished: SUCCESS

The newly created Test Cycle will have all the test results from the tests that have just run. When clicking on the TM4J link present in the log files, the test player with the newly created test cycle will pop up, and it is possible to see the passing test execution:


From here, all TM4J reports will show the execution data that comes from Jenkins. This can be displayed within the reporting gadgets as well.

Realising the full value of Behaviour Driven Development

BDD is a powerful way to bridge the gap between business stakeholders, developers and testers, to ensure everyone is on the same page. Writing test cases in a human language helps document epics and user stories, and create a shared understanding of what is required, and expected. In addition to clear communication benefits, BDD tests can be considered a form of living specification for your project, as the behaviour described by your BDD test can be executed automatically.

Using BDD combined with Jira is a powerful way to realise the full value of BDD. Having test cases described alongside user stories (Jira issues) is the best way to communicate them to a wider audience and make them accessible to business stakeholders, developers and testers. TM4J helps you achieve this, and is a complete solution for implementing BDD right inside of Jira. Not only will your test cases be documented in the right place, your execution results will also be displayed in Jira as well. 

Ultimately BDD unites everyone through a common approach to developing great software. By working as a team through real-life user examples and scenarios and sharing everyone's different perspectives, BDD helps clarify what you're trying to achieve, how you're going to achieve it and most importantly why.

Ready to get started with BDD using Test Management for Jira? Follow the link below and get a 30-day free trial:  

copy_text Icon