top of page

How to Write Perfect Gherkins for Testers


Gherkin is a business-readable language used in Behavioral Driven Development (BDD) for writing acceptance tests. It helps to bridge the communication gap between business stakeholders and the development team. It allows testers, developers, and business analysts to understand the system's functionality using simple, natural language.

Structure of a Gherkin Document:

A typical Gherkin document has the following structure:

  • Feature

  • Background

  • Scenario Outline or Scenario

  • Given, When, Then, And, But

Let's take a closer look at each part:

  1. Feature: This is a high-level business or product requirement.

  2. Background: This contains the steps that are common to all the scenarios in a feature file.

  3. Scenario Outline or Scenario: A scenario contains a sequence of steps under a particular situation. A scenario Outline is used when the same scenario needs to be executed for multiple sets of data.

  4. Given, When, Then, And, But (GWTAB): These are keywords used to describe a step in the scenario.




Describes the initial state of the system.


Describes an event or action.


Describes the expected outcome or result.

And, But

These can be used to chain multiple Given, When, or Then steps.

Guidelines for Writing Perfect Gherkins:

Having understood the basics, here are some crucial guidelines for writing perfect Gherkin scripts:

  1. Write from the User's Perspective: The scenario should be written from the user's point of view and focus on what the user does, not how the system reacts.

  2. Keep it Simple: Each statement should be clear and concise.

  3. Use Declarative Language, Not Imperative: Describe what the outcome should be, not how to reach it.

  4. Avoid Technical Jargon: Gherkin is designed to be understood by non-technical stakeholders as well. Use plain and simple language.

  5. Each Scenario Should be Independent: Each scenario should be able to be run independently of others and should not depend on the state from a previous scenario.

  6. Use Background Wisely: If there are common steps that need to be executed for all scenarios in a feature, put them in the 'Background'. But remember, a long 'Background' might indicate that your scenarios are not independent.

  7. Use Scenario Outlines for Repetitive Scenarios: If a scenario needs to be run for different data sets, use 'Scenario Outline'. This helps to avoid duplicating the same steps.

  8. Avoid Using Too Many 'And' Steps: Using too many 'And' steps can make your scenario less readable. Try to limit the steps under 'Given', 'When', and 'Then' clauses.

Here's an example of a well-written Gherkin script:

Feature: Password Reset

  Scenario: Successful password reset
    Given a user exists with an email ""
    When the user requests a password reset
    Then the user should receive a password reset link

  Scenario Outline: Password strength check
    Given a user is on the "change password" page
    When the user sets their password as "<password>"
    Then the password strength should be "<strength>"

      | password | strength |
      | 123456   | Weak     |
      | abcdef   | Weak     |
      | Abc123!  | Strong   |

Additional Examples

Here are a few more examples to demonstrate various scenarios:

Example 1: Login Functionality

Feature: User Login

    Given a user is on the login page

  Scenario: Successful login
    When the user enters a valid username and password
    And clicks on the login button
    Then the user should be redirected to the homepage

  Scenario: Login attempt with invalid credentials
    When the user enters an invalid username or password
    And clicks on the login button
    Then an error message "Invalid Credentials" should be displayed

Example 2: Shopping Cart

Feature: Shopping Cart

    Given a user is logged in
    And the user is on the product listing page

  Scenario: Add a product to the cart
    When the user selects a product
    And adds the product to the cart
    Then the product should be displayed in the cart

  Scenario: Remove a product from the cart
    Given the user has a product in the cart
    When the user removes the product from the cart
    Then the product should not be displayed in the cart

Example 3: Using Scenario Outlines for testing different form inputs

Feature: Registration Form

  Scenario Outline: Input validation
    Given the user is on the registration form
    When the user inputs "<input>" in the email field
    And the user clicks on the submit button
    Then the system should display "<message>"

    | input              | message             |
    |   | Registration Success |
    |   | Invalid Email Format |
    |                    | Email is Required   |

Each of these examples demonstrates the use of Gherkin syntax to describe different types of user scenarios. It should provide a comprehensive overview of how to structure your Gherkin scripts to cover all possible scenarios.

By following these simple guidelines and practices, you'll be well on your way to writing clear, effective Gherkin scripts that will help facilitate communication and understanding across your team and stakeholders.


Gherkin's simple, business-readable language offers a robust approach for writing acceptance tests in Behavioral Driven Development. Its ability to simplify and articulate complex scenarios, especially in non-technical language, sets it apart. Furthermore, Gherkin allows us to capture real-life scenarios and handle different datasets efficiently, making it a popular choice among testers.

However, to leverage Gherkin's potential to its fullest, it's crucial to follow some guidelines while writing your scripts. Ensure to keep the scenarios user-focused, simple, and independent. Use declarative language, avoid technical jargon, and utilize the 'Background' and 'Scenario Outline' constructs wisely.

The examples and practices provided in this blog should offer a strong foundation to start writing effective Gherkin scripts. Remember, the primary goal is to improve communication and understanding between all stakeholders in a project. So, strive to keep your Gherkin scripts clear, concise, and meaningful. Happy Testing!

82 views1 comment

1 Comment

Rated 0 out of 5 stars.
No ratings yet

Add a rating
Oct 04, 2023
Rated 5 out of 5 stars.

Nice article

bottom of page