The main features of Cucumber is Gherkin and Step Definitions.


Gherkin is a simple set of grammar rules that makes plain text structured enough for Cucumber to understand. Gherkin serves multiple purposes like below:

  • Documents the system’s actual behavior
  • Unambiguous Executable specification understandable by everyone
  • Automated Testing

Gherkin exists in different spoken languages so that people can use their own language. The documents are stored in .feature files (e.g. LoginTest.feature).

If the team is practicing TDD (Test Driven Development), it is best if developers write the feature files. If Cucumber is used only for running automated tests, both developers and testers can contribute in writing the feature files.

Gherkin uses special keywords to give structure and meaning to the Feature files. The Gherkin lines start with one of the following primary keywords:

  • Feature
  • Scenario
  • Given, When, Then, And, But (for the steps)
  • Background
  • Scenario Outline
  • Examples

The secondary keywords are:

  • “”” (Doc Strings)
  • | (Data Tables)
  • @ (Tags)
  • # (Comments)

Sample Gherkin file:

# This line is a comment
Feature: Google Launch and Search

Scenario: Test to validate successful Google launch and search from Chrome browser
  Given user opens the "Chrome" browser in desktop
  When user opens the URL ""
  Then user is able to successfully search for the item "Testing"
  And user is able to view the "Testing" related URLs

Let’s talk about each Keyword in detail:

The purpose of the Feature keyword is to provide a high level description of a software feature and to group related scenarios. Feature should be the first primary keyword in a Gherkin document, followed by a “:” and then a short text describing the feature. Free-form text can be written below to add some more description to the feature (which are ignored at runtime but available for reporting).

Feature: Google Launch and Search
about Testing

The Scenario keyword describes a definitive example that illustrates a business rule. Each scenario consists of a list of steps. You can write as many steps under a scenario as you like, but a lot of steps usually mean that the scenario is actually losing its specification power.

Each scenario consists of steps arranged in the following pattern:
Given steps (Describing an initial context or precondition)
When steps (Describing an action or an event)
Then steps (Describing an expected result or outcome) And/But step (Helps to divide a large Given/When/Then condition into smaller, understandable and brief steps)

Cucumber executes each step in a scenario one at a time in a sequential manner. While trying to execute a step, it searches for a matching Step Definition present in the code file of the programming language. You cannot have duplicate step definitions present in your code for a single step.

In a Feature, you might find some initial steps getting repeated for all the scenarios. Those steps are not essential to describe the scenario, but they are the incidental details. In such cases they can be grouped in the Background section, placed after the Feature description and before the first Scenario. The Background section allows you to add some context to the scenarios. It can contain one or more Given steps. It runs before each scenario execution. Also, remember that you can have only one set of background steps per Feature. If you need different Background steps for different scenarios, you might need to include those steps inside the individual Scenarios itself or you might need to split them into different feature files. Do not use Background to set up complicated steps, keep the Background short and clear.

    Given a testing blogger named "Sam"
    And a blog named "Sam’s Testing Blog"

Scenario Outline and Examples
It can be used to run the same Scenario multiple times, with different combinations of values. We can collapse two or more similar, repetitive scenarios into a Scenario Outline. A Scenario Outline must contain an Examples section. Its steps are interpreted as a template which is never directly run. Instead, the Scenario Outline is run once for each row in the Examples section beneath it (not counting the first header row).

In Scenario Outline, the steps can use <> delimited parameters that reference headers in the example table. Cucumber will replace these parameters with values from the table before it tries to match the step against a Step Definition.

Given there are <start> cucumbers
  When I eat <eat> cucumbers
  Then I should have <left> cucumbers

    | start | eat | left |
    |    12 |   5 |    7 |
    |    20 |   5 |   15 |

Doc Strings
These are useful for passing a large text to Step Definition.
The text should be offset by delimiters “”” marks on lines of their own.

Given a blog post named "Random" with Markdown body
  Some Title, Eh?
  Here is the first paragraph of my blog post. Lorem ipsum dolor sit amet,
  consectetur adipiscing elit.

Data Tables
They are useful for passing a list of values to a step definition. They will be passed to the Step Definition as the last argument.

Given the following users exist:
  | name     | email              |
  | Sam      |       | 
  | Richard  |   | 
  | Tom      |       |


The trailing portion (after the keyword) of each step is matched to a code block called Step Definition.

Step Definitions map or glue each Gherkin step to programming code to carry out the action that should be performed by the step. Here, the programming language that we will use is Java. For example, taking into consideration the feature that we wrote above, the step definitions are:

user opens the "Chrome" browser in desktop
user opens the URL
user is able to successfully search for the item "Testing"
user is able to view the "Testing" related URLs