Gherkin is a domain-specific language used in Behaviour-Driven Development (BDD) to create clear, plain-language scenarios outlining expected system behaviour before development. It facilitates communication and collaboration between technical and non-technical stakeholders, reducing misunderstandings and ensuring a clear definition of the delivered product.

In this post, we will explore 

  1. Reasons for Using Gherkin in our Team
  2. Gherkin best practices
  3. How we have incorporated Gherkin into our workflow
  4. Tips for practical Gherkin usage
  5. Final thoughts

Reasons for Using Gherkin in our Team

  • To bridge the communication gap between all stakeholders: Gherkin closes the communication gap among all stakeholders. It allows product managers, engineering managers, and developers to work together. They use a shared language to outline business requirements. Using the Given-When-Then format for test scenarios helps all stakeholders understand the desired feature before development starts.
  • To align engineering and business needs: we use Gherkin scenarios to define expected behaviours. It helps us reduce rework, identify edge cases early, and ensure that they meet business needs.
  • To aid test automation and prevent regression: we use Gherkin as one of the tools for our test automation. We create reliable, automated tests that help prevent regressions and ensure long-term stability.

Gherkin best practices

  1. Follow the `Given - When -Then` structure properly. Each scenario should deliver only one business logic.  
    • Use Given to set up the initial state - this should cover any preconditions for your test.
    • Use When to describe the action performed
    • Use Then to assert the expected outcome

Poor example:

Feature: Product filtering
  
  Scenario: Filter products, apply discount and add to cart
    Given I am on children shopping page
    When I filter by category "Toys"
    And I should see "Toy 1, Toy 2"
    And I add "Toy 1" to cart
    And I apply "HELLO15" discount code
    Then I should see "Discount applied successfully"
    And I proceed to checkout
    And the total price should be reduced by "15%"

Issue: More than one business logic in a single scenario - there is filtering, adding items to cart, applying discounts and checking out.

Best practice:

Feature: Children product page

Scenario: Filter product by category
  Given I am on children shopping page
  When I filter by Category "Toys"
  Then I should see "Toy 1" and "Toy 2"

Scenario: Add filtered product to cart
  Given I have filtered items by category "Toys"
  When I add "Toy 1" to cart
  Then I should see "Toy 1" in my cart

Scenario: Proceed to checkout with welcome discount
  Given I have "Toy 1" in my cart
  When I apply discount "Hello15"
  And I proceed to checkout
  Then the total price should be reduced by "15%"
  1. Scenarios should be clear, concise, and business-oriented. It should focus mainly on “WHAT” the user is trying to achieve and “NOT” how they achieve it. 

Poor example:

Feature: Product filtering

   Scenario: Filter products by different types
     Given I am browsing the product catalog
     When I click on "Shop" button
     And I click on "Children" button
     And I see "Show results for"
     And I click on "Filter by" dropdown icon
     And I click on "Category" button
     And I select "Toys"
     And I click on "Age" button
     And I select "Child(1-2years)"
     And I click on "Type"
     And I select "Playsets"
     Then I should see "Playset ABC, Playset Toot-Toot"

Issue: Focus on UI details (describes UI interactions) and has repeated steps.

Best practice:

Feature: Product filtering

    Scenario: Filter products by different types
      Given I am browsing the product catalog
      When I filter by <type> and <value> 

        | type        | value           |
        | Category    | Soft toys       |
        | Age Range   | Child(1-2years) |
        | Type        | Playsets        |

      Then I should only see products matching my selected criteria

Benefits: Focuses on business logic, easy to maintain and avoids implementation specifics, ensuring scenarios remain unaffected by design or implementation changes.

  1. Avoid using multiple "When" and "Then" pairs in a Gherkin scenario. This practice often signals that the scenario is attempting to cover several distinct behaviours simultaneously, which can diminish the clarity and focus of its intended purpose.

Poor example:

Scenario: User adds and removes items from the shopping cart
    Given I am browsing the product catalog
    When I add a product
    Then the shopping cart should contain 1 item
    When I remove the product
    Then the shopping cart should be empty

Best practice:

Scenario: User adds to the shopping cart
    Given I am browsing the product catalog
    When I add a product
    Then the shopping cart should contain 1 item

Scenario: User remove item from shopping cart
    Given my shopping cart contains 1 item
    When I remove the product
    Then the shopping cart should be empty
  1. Leverage Backgrounds for shared context - When multiple scenarios have the same setup, use a Background section to avoid repetition.

Poor example:

Feature: Children product page
  
  Scenario: Filter product by Toys
    Given I am on children shopping page
    And I filter by preschool
    When I filter by Category "Toys"
    Then I should see "Toy 1, Toy 2"


  Scenario: View product details
    Given I am on children shopping page
    And I filter by preschool
    When I select a product
    Then I should see product details page

  Scenario: Add product to cart
    Given I am on children shopping page
    And I filter by preschool
    When I add a product to the cart
    Then cart count should increase by 1

Issue: repeated preconditions.

Best practice:

Feature: Children product page
  
  Background:
   Given I am on children shopping page
   And I filter by preschool

  Scenario: Filter product by Toys
    When I filter by Category "Toys"
    Then I should see "Toy 1, Toy 2"

  Scenario: View product details
    When I select a product
    Then I should see product details page

  Scenario: Add product to cart
    When I add a product to the cart
    Then cart count should increase by 1

How we have incorporated Gherkin into our workflow

Gherkin is an essential part of our development process. Our team's workflow incorporates the following steps:

  • Define scenarios during refinement
    During the refinement phase, developers, engineering managers, and product managers work together to define scenarios for each feature. These scenarios are documented directly within the ticket description, adhering to the Given-When-Then format. This approach facilitates a shared understanding of feature requirements and expected behaviours among developers and all stakeholders. It serves as a guide throughout development and provides documentation for future reference.
  • Code implementation for Gherkin statements
    Developers write step definitions based on the scenarios in each ticket. These definitions turn the easy-to-read Gherkin statements into executable code. This ensures alignment between business requirements and technical implementation, achieving the intended functionality.
  • Run tests in the CI/CD pipeline
    The implemented step definitions are integrated into our continuous integration pipeline. Upon submission of a merge request, the system executes these tests to verify that the new code fulfils the business requirements specified in the Gherkin scenarios. This automation prevents regressions and maintains application integrity.
  • Refactoring and maintenance
    Our development team regularly reviews and updates feature files to keep them aligned with current business requirements. This ongoing maintenance ensures our test suites remain relevant and valuable. For example, consider a navigation feature that uses breadcrumbs. Now, they have updated the design to use side navigation. Whilst the business functionality hasn’t changed, we need to update our feature files. This will reflect the new interface design and ensure our tests represent the current system accurately and meet business needs.

Through this workflow, Gherkin has become a valuable tool for our team, providing clarity, facilitating agreement, enhancing code quality, and documenting application behaviour.

How Gherkin Transformed Our Team Dynamics

Since adopting Gherkin as part of our refinement process, our team has discovered benefits that extend far beyond improved test coverage. One of the most significant values to us has been about how we communicate and collaborate around feature development.


Catching misunderstandings early
One of the most valuable benefits for my team is the ability to discover requirement gaps during refinement rather than during development, testing, or, worse, in production. When we write scenarios in plain language, questions emerge naturally: "What happens if the user does this before that?" or "Should this behaviour differ for different user types?" These discussions happen while change is still inexpensive.


Promoting collaboration over siloed working
Our traditional way of working before Gherkin was for product owners to share requirements, and developers would interpret them in isolation. Now, using Given-When-Then scenarios, we can define our features and agree on them during refinement sessions. This creates a single source of truth that everyone references, helps promote clarity, and reduces misunderstandings in our deliverables. We can think through edge cases before any code is written.

Enabling confident changes across teams
Our Gherkin feature files serve as living documentation of our application's behaviour. New team members can read through them to quickly understand what the application does. When incidents occur, people outside the original team can trace business requirements to executable tests, making troubleshooting more efficient. This would have taken much longer with traditional documentation approaches.


Increasing confidence in releases
We now have significantly higher confidence in what we release to customers. With Gherkin, we know our critical user journeys are validated automatically with every merge request. Everyone, from developers to product managers, shares greater confidence that we're delivering what we promised. The reduced anxiety around deployments has been a genuine quality-of-life improvement for the entire team.

Tips for practical Gherkin usage

To maximise the benefits of Gherkin in your development process, consider these guidelines:

  • Prioritise business value: Concentrate on the 'what' from a business perspective, not the 'how' of the user interface. For example, say "When the user logs in with valid credentials" instead of detailing button clicks or field entries.
  • Ensure clarity and precision: Make sure scenarios are clear and precise. Write them so there is no room for misunderstanding.
  • Keep scenarios concise and focused: Each scenario should validate a single business value or requirement.
  • Maintain consistent language: Use the same terminology throughout your feature files. If you choose a term like "user," stick with it to avoid confusion.
  • Utilise tags for test management: Create scenarios that both technical and non-technical team members can understand easily.
  • Promote understanding for all stakeholders: Write scenarios that technical and non-technical team members can easily understand.
  • Focus on high-impact areas: Not all scenarios are suitable for automation. Prioritise automating tests for critical, high-risk business requirements.

Final thoughts

Gherkin effectively improves cross-functional collaboration, establishes clear acceptance criteria, and enables behaviour-driven test automation. By adhering to best practices that emphasise readability, maintainability, and alignment with development goals, teams can develop more robust applications, mitigate miscommunication early in the development cycle, and promptly identify issues.