Skip to main content
Version: legacy

BDD Testing Framework (Cucumber integration) in Katalon Studio

Note:
  • For better performance, you should clean up the Katalon workspace frequently. Navigate to File > Clean up.

Behavior Driven Development (BDD) testing framework allows you to create test cases in plain English. BDD testing framework focuses on the behavior of the product and user acceptance criteria. Cucumber is a BDD framework tool to write test cases, which uses Gherkin, an ordinary language parser, that permits writing scripts in English.

With the BDD testing framework in Katalon Studio, you can:

  • Create or add a feature file

  • Define and link steps

  • Set the default package for step definitions

  • Run your feature file

  • Add your feature file to a test case

  • View BDD report files generated from Katalon Studio

  • Upload and view BDD reports on Katalon TestOps

Add Feature Files in Katalon Studio

This section shows you how to add feature files in Katalon Studio. Steps in the scenario will then be defined by step definitions.

To add a new feature files in Katalon Studio, do as follows:
  1. In Katalon Studio, open a Katalon project. Then, navigate to Test Explorer > Include > features. Right click on the features folder and choose New Feature File.
    create new feature file
  2. The New Feature File dialog appears. Give your feature file a name. You can also choose the option to Generate sample Feature template. This option ensures that the created features file matches with BDD convention, reducing your effort in creating features file in the correct format.
    new feature file
    A new feature file is created.new feature file
  3. Add your scenarios to the feature file following the sample format:
    • Feature: List of scenarios.

    • Scenario: Business rule through list of steps with arguments.

    • Scenario Outline: Used where test data is replaced with multiple sets of data for each run of a test script.

    • Given: Precondition step.

    • When: Key actions.

    • Then: Observe outcomes or validation.

    • And, But: Enumerate more Given, When, Then steps.

    • Background: List of steps run before each of the scenarios.

    • Examples: Container for data set.

    • Tags/ Labels: To group relevant scenarios. Using tags is a good way to organize features and scenario. A feature or scenario can have multiple tags.

    For example, we want to test the Login feature of the Katalon Demo Cura System: https://katalon-demo-cura.herokuapp.com/. There are two scenario outlines: login with a valid credential, and login with an invalid credential. In each scenario, there are specific Given, When, Then steps like below:
    log in feature file
    Sample Feature File Script:
    #Author: your.email@your.domain.com
    #Keywords Summary :
    #Feature: List of scenarios.
    #Scenario: Business rule through list of steps with arguments.
    #Given: Some precondition step
    #When: Some key actions
    #Then: To observe outcomes or validation
    #And,But: To enumerate more Given,When,Then steps
    #Scenario Outline: List of steps for data-driven as an Examples and <placeholder>
    #Examples: Container for s table
    #Background: List of steps run before each of the scenarios
    #""" (Doc Strings)
    #| (Data Tables)
    #@ (Tags/Labels):To group Scenarios
    #<> (placeholder)
    #""
    ## (Comments)
    #Sample Feature Definition Template
    @Login
    Feature: Login Feature

    As a user, I want to login to Cura System
    so that I can make an appointment.

    @Valid
    Scenario Outline: Login with a valid credential
    Given I navigate to Cura System homepage
    When I click Make Appointment button
    And I enter username <username> and password <password>
    And I click Log in button
    Then I should be able to login successfully

    Examples:
    | username | password |
    | John Doe | ThisIsNotAPassword |

    @InValid
    Scenario Outline: Login with an invalid credential
    Given I navigate to Cura System homepage
    When I click Make Appointment button
    And I enter an invalid username <username> and password <password>
    And I click Log in button
    Then I should NOT be able to login successfully

    Examples:
    | username | password |
    | Jane Doe | ThisIsNotAPassword |

Maintain Features File

Note:
  • Katalon Studio code inspection can detect and highlight any missing Step Definitions in Features File to help you create the required step definitions.

For better management, you might want to organize your feature files with a multi-level system. A feature file can contain many scenarios. However, you should have one scenario per feature file for easy maintenance.

In Katalon Studio, there are three options to help you maintain the feature file. Right click anywhere in the feature file editor view and choose from the following options:

OptionDescription
Pretty FormatRe-do the format when the current format is not organized properly.
Find Step

Find relevant step of current Gherkin step in existing Step Definitions files.

Recalculate stepsRecalculate steps in the feature file when there are changes in Step Definitions.



Define Steps

Steps definitions in Katalon Studio

After you added your feature files, you need to define and link steps before using that feature file.

Each Gherkin step in the features file needs to be defined as a set of programming code so that Katalon Studio can execute the action of that step. These step definitions can be implemented in the Keyword folder by leveraging the Script Mode. Katalon Studio built-in keywords can also be re-used in Step Definition files as well. When Katalon Studio executes any features files in a test case, it also look for the matching step definitions in the source folder.

Step Definitions can be written in any Cucumber-supported programming languages including Groovy and Java.

For example, we have two scenario outlines: Login with a valid credential and login with an invalid credential. With two scenario outlines, we have totally 6 steps like below:

  • Given I navigate to Cura System homepage

  • When I click Make Appointment button

  • And I enter username <username> and password <password>

  • And I click Log in button

  • Then I should be able to login successfully

  • Then I should NOT be able to login successfully

step definition

Step Definitions Sample Script

class MyStepDefinition {

/**
* The step definitions below match with Katalon sample Gherkin steps
*/

@Given("I navigate to Cura System homepage")
def I_navigate_to_Cura_System_homepage() {

WebUI.openBrowser("https://katalon-demo-cura.herokuapp.com/")
//WebUI.waitForPageLoad(30)
}

@When("I click Make Appointment button")
def I_click_makeAppointment_button() {

WebUI.click(findTestObject('Page_CURA Healthcare Service/a_Make Appointment'))
}

@And("I enter username (.*) and password (.*)")
def I_enter_valid_username_password(String username, String password) {

WebUI.setText(findTestObject('Page_CURA Healthcare Service/input_userName'), username)
WebUI.setText(findTestObject('Page_CURA Healthcare Service/input_password'), password)
}

@And("I click Log in button")
def I_click_login_btn() {

WebUI.click(findTestObject('Page_CURA Healthcare Service/button_Login'))
}

@Then("I should be able to login successfully")
def I_login_successfully() {

WebUI.click(findTestObject('Page_CURA Healthcare Service/button_Login'))
WebUI.verifyTextPresent('Make Appointment', false)
WebUI.closeBrowser()
}

@And("I enter an invalid username (.*) and password (.*)")
def I_enter_invalid_username_password(String username, String password) {

WebUI.setText(findTestObject('Page_CURA Healthcare Service/input_userName'), username)
WebUI.setText(findTestObject('Page_CURA Healthcare Service/input_password'), password)
}


@Then("I should NOT be able to login successfully")
def I_login_unsuccessfully() {

WebUI.verifyTextPresent('Login failed! Please ensure the username and password are valid.', false)
WebUI.closeBrowser()
}

}

How to define steps in Katalon Studio

Steps in the feature files must be defined before use.

To create new step definitions, do as follows:

  1. In Test Explorer, navigate to the Include/scripts/groovy folder. Right-click and choose New > Step Definition.
    The Keyword dialog appears.
  2. Choose your Package, then enter your Class Name. You can also enable the option to Generate sample @Given, @When, @Then steps.
    keyword
  3. Once you are done, click OK.
A new step definition is created.

new step definition

Set the default package for step definitions in Katalon Studio

Note:
  • Available from version 7.8.0 onwards.

You can define the location of a step definitions for Cucumber by using CucumberKW.GLUE = ['package1', 'package2']. The default value of CucumberKW.GLUE = [''] is all packages, which means the test engine takes time to scan all the packages. Defining specific locations narrows down the packages to find the steps definitions before executing feature files; hence, reducing the execution time.

We recommend putting the script of directing to a package in a test listener.

import com.kms.katalon.core.annotation.AfterTestCase
import com.kms.katalon.core.annotation.BeforeTestCase
import com.kms.katalon.core.context.TestCaseContext
import com.kms.katalon.core.cucumber.keyword.CucumberBuiltinKeywords as CucumberKW

class NewTestListener {
@BeforeTestCase
def sampleBeforeTestCase(TestCaseContext testCaseContext) {
CucumberKW.GLUE = ['package1', 'package2']
}
}

Using a Feature File in Katalon Studio

Once you create your feature files and define steps in that feature file, you can run this feature file or add it into a test case.

Run a Feature File in Katalon Studio

Katalon Studio allows you to run the feature file instantly by itself to make sure it works properly. To do so, open the desired Features file, then click the Run button on the main toolbar.



Include a Feature File In Test Cases

To include a Cucumber feature file in Katalon Studio test case, you can use Cucumber keywords in your test case. Katalon Studio supports Cucumber keywords along with the original built-in keywords. You do not have to import Cucumber libraries into Katalon Studio.

Use casesCucumber keywords
Execute a single Feature File (with or without tags)
Execute multiple Feature Files (with or without tags)
Execute using Cucumber Runner
For example:
CucumberKW.runFeatureFile('Include/features/logIn.feature')

feature file in a test caseAfter you execute your BDD tests, you can view BDD report files generated from Katalon Studio or upload and view reports on Katalon TestOps. See View BDD reports.