Understanding Gherkin: Bridging Behaviour with Code

Rajesh Vinayagam
5 min readJan 8, 2024

In the modern era of software development, delivering high-quality software that meets user needs is paramount. To achieve this, developers and stakeholders need a common language to specify how software should behave. This is where the Gherkin language comes into play. Originating from Behaviour-Driven Development (BDD) methodology, Gherkin is a simple yet powerful language for describing software features and behaviours.

What is Gherkin?

Gherkin is a domain-specific language designed to create clear and executable specifications for software systems. It is a key component in BDD frameworks like Cucumber, SpecFlow, and Behat. The language is designed to be non-technical and human-readable, which helps bridge the communication gap between business stakeholders and the development team.

Key Features of Gherkin

  • Business Readable: Its syntax is English-like and can be understood by all stakeholders, including non-technical ones.
  • Keyword-Based: Utilizes a set of reserved keywords such as Feature, Scenario, Given, When, Then, And, But to structure the behavior descriptions.
  • Multilingual: Supports multiple languages, allowing global teams to write in their native language.
  • Executable Specifications: Gherkin scenarios can be automated and executed using BDD tools.

How Gherkin Works in Practice

  1. Write Scenarios: A developer or a business analyst writes scenarios in Gherkin language. Each scenario is a list of steps for testing a particular aspect of the system’s functionality.
  2. Automate: Tools like Cucumber read Gherkin tests and validate that the software behaves as described. Each step in a scenario is matched to a method in the code that executes the step.
  3. Execute and Report: When Gherkin scenarios are linked with automation code, the scenarios are executed. The tools then report back on whether the software behaved as expected.

Writing Gherkin Scenarios

Gherkin scenarios are written in a structured format using the given keywords:

  • Feature: Describes the overarching feature or functionality.
  • Scenario: Outlines a specific behavior or situation.
  • Given: Provides the context or the state before the event.
  • When: Specifies the event or action.
  • Then: Describes the expected outcome.
  • And, But: Used for adding more conditions or outcomes.

Example of Gherkin Scenario

Let’s illustrate this with a simple example of a login feature.

Objective: Allow users to log into the system using a username and password.

Feature: User Login

Scenario: Successful login with valid credentials

Feature: User Login

Scenario: Successful login with valid credentials
Given the user is on the login page
When the user enters the valid username "user1" and password "password123"
And the user clicks on the login button
Then the user is redirected to the homepage
And a welcome message is displayed

In this example,

  • Feature is “User Login”. It’s a high-level description of the functionality.
  • Scenario is “Successful login with valid credentials”. It’s a specific situation or use case under this feature.
  • Given describes the initial context: The user is on the login page.
  • When describes the action: The user enters their username and password, and then clicks the login button.
  • Then describes the expected outcome: The user is redirected to the homepage and sees a welcome message.

When you write a Gherkin scenario, you’re defining what should happen, but not how it happens. The how is defined in the Glue code. For each step in your Gherkin scenario (Given, When, Then, etc.), there needs to be a corresponding method in your codebase annotated with the step’s text. These methods are what Cucumber will execute when it runs the scenario.

Features of the Glue Code:

  1. Annotations: In Java, annotations like @Given, @When, and @Then are used to link a Gherkin step to a Java method. Each annotated method is responsible for carrying out the action described in the Gherkin step.
  2. Parameters: Glue code methods can take parameters, allowing dynamic values from the Gherkin steps to be passed into the methods. In the example provided, {string} is a placeholder in the Gherkin step that gets replaced by actual values when the test runs.
  3. Execution: When a test is run, Cucumber scans the Glue code for methods matching the steps in the Gherkin scenarios. It then executes the methods in the order they appear in the scenario, passing any parameters as needed.
  4. Flexibility: Glue code can do anything a regular code can do, from interacting with web elements using Selenium, making API calls, or even interacting with databases. It’s the place to integrate whatever tools and libraries are needed to interact with the application under test.

Here’s how it looks in Java for the Cucumber tool (simplified for illustration):

@Given("the user is on the login page")
public void userIsOnLoginPage() {
// Code to navigate to login page

@When("the user enters the valid username {string} and password {string}")
public void userEntersCredentials(String username, String password) {
// Code to enter username and password
@And("the user clicks on the login button")
public void userClicksLogin() {
// Code to click login button
@Then("the user is redirected to the homepage")
public void userIsRedirectedToHomepage() {
// Code to verify user is on homepage
@And("a welcome message is displayed")
public void welcomeMessageIsDisplayed() {
// Code to verify welcome message

When the Gherkin scenario runs, each step is matched with its corresponding step definition. The testing tool executes the code within the step definitions. If all the steps pass (i.e., all assertions in “Then” steps succeed), the scenario is marked as passed. If any step fails, the scenario is marked as failed, and the tool provides information on what went wrong.

How Gherkin Differs from Unit Test Cases

While Gherkin focuses on the behavior of the application from an end-user perspective, unit test cases are concerned with the correctness of the smallest parts of the application, typically at the function level. Here are some fundamental differences:

  1. Level of Testing: Gherkin is used for higher-level testing, often acceptance or integration testing, involving multiple components of the system. Unit tests focus on the smallest units of code in isolation.
  2. Language and Audience: Gherkin is written in a business-readable, domain-specific language, understandable by all stakeholders. Unit tests are written in the same programming language as the application code and are meant for developers.
  3. Scope and Purpose: Gherkin tests ensure that the software meets business requirements and behaves as expected from the user’s perspective. Unit tests ensure that individual components of the code work correctly and as intended.
  4. Tools and Execution: Gherkin scenarios are executed using BDD tools like Cucumber, which map human-readable descriptions to code. Unit tests are executed using unit testing frameworks specific to the programming language.


Gherkin serves as a powerful tool in the BDD process, helping teams define clear and understandable software behaviours that align with business objectives. By enabling the creation of executable specifications, Gherkin bridges the gap between technical and non-technical stakeholders, ensuring everyone is aligned with the expected behavior of the software. When used in conjunction with unit tests, Gherkin can contribute to a comprehensive and effective testing strategy, leading to high-quality and reliable software delivery.