Gherkin Scenarios: 3 Examples to Follow and 6 to Avoid

September 20, 2023

In this blog post, I’d like to share some insights many software developers overlook. It’s about Gherkin scenarios in Behavior-Driven Development (BDD). The quality of your Gherkin scenarios can make or break your BDD efforts. Yet, few developers understand what constitutes a good or bad Gherkin scenario.

Gherkin Scenarios: 3 Examples to Follow and 6 to Avoid ghercucu-800x457

Gherkin is a simple yet powerful language for describing software behavior. It allows teams to write clear and understandable specifications to share among stakeholders. However, writing effective Gherkin scenarios is as much an art as a science; it’s crucial to understand the right (and wrong) ways to craft them.

This post will delve into the anatomy of good and bad Gherkin scenarios with specific examples. From user login to product search to placing an order, we’ll dissect nine scenarios to help you understand what works and doesn’t.

By analyzing these examples, you will better understand the principles of effective Gherkin scenario writing. You’ll be able to identify common pitfalls and learn how to avoid them in your own scenarios.

Good Gherkin Scenarios

Scenario 1: User Login

Feature: User Login
  As a registered user
  I want to log in to the system
  So that I can access my account

  Scenario: Successful Login
    Given I am on the login page
    When I enter valid credentials
    And I click the login button
    Then I should be redirected to my account dashboard

Why it’s good: This scenario clearly defines the desired behavior of the system when a user attempts to log in with valid credentials. Each step is clear, concise, and directly tied to an action or outcome.

Scenario 2: Adding an Item to the Shopping Cart

Feature: Shopping Cart
  As an online shopper
  I want to add items to my shopping cart
  So that I can purchase them later

  Scenario: Adding an Item to the Cart
    Given I am on a product page
    When I click the "Add to Cart" button
    Then the item should be added to my shopping cart

Why it’s good: This scenario describes a fundamental e-commerce behavior. It’s straightforward, easy to understand, and directly maps to a user action and expected outcome.

Scenario 3: Searching for a Product

Feature: Product Search
  As an online shopper
  I want to search for a product
  So that I can find what I'm looking for quickly

  Scenario: Successful Product Search
    Given I am on the home page
    When I enter a product name into the search bar
    And I click the search button
    Then I should see a list of products that match my search

Why it’s good: This scenario clearly outlines the expected behavior of the search functionality, including the action of searching and the expected outcome.

Bad Gherkin Scenarios

Scenario 1: User Login

Feature: User Login
  Scenario: Login
    Given I am on the site
    When I log in
    Then I am logged in

Why it’s bad: This scenario is too vague, it doesn’t specify what “logging in” means or what it looks like to be “logged in.”

Scenario 2: Adding an Item to the Shopping Cart

Feature: Shopping Cart
  Scenario: Adding an Item to the Cart
    Given I am on the site
    When I add an item
    Then it is added

Why it’s bad: This scenario is unclear and lacks specific actions or outcomes. It doesn’t specify where the user is on the site or what it means for an item to be “added.”

Scenario 3: Searching for a Product

Feature: Product Search
  Scenario: Searching for a Product
    Given I am on the site
    When I search
    Then I get results

Why it’s bad: This scenario is too ambiguous. It doesn’t specify what the user is searching for or what “getting results” looks like.

Scenario 4: User Registration

Feature: User Registration
  Scenario: Registration
    Given I want to register
    When I register
    Then I am registered

Why it’s bad: This scenario is overly simplistic and lacks specific steps. It doesn’t specify how a user registers or what it means to be “registered.”

Scenario 5: Placing an Order

Feature: Placing an Order
  Scenario: Placing an Order
    Given I have items in my cart
    When I place an order
    Then I have placed an order

Why it’s bad: This scenario is too vague. It doesn’t specify the steps involved in placing an order or what it looks like when an order has been placed.

Scenario 6: User Logout

Feature: User Logout
  Scenario: Logout
    Given I am logged in
    When I log out
    Then I am logged out

Why it’s bad: This scenario is overly simplistic and lacks specific steps. It doesn’t specify what “logging out” means or what it looks like to be “logged out.”

Conclusion

Mastering the art of Gherkin scenarios is a critical skill in Behavior-Driven Development. Yet, it’s a skill that many developers, unfortunately, fail to acquire. By understanding the differences between good and bad scenarios, you can significantly improve the effectiveness of your BDD efforts.

Clear and concise Gherkin scenarios lead to better communication, fewer misunderstandings, and better software. So, the next time you write a Gherkin scenario, remember these examples. Because a well-crafted Gherkin scenario is more than just a specification—it’s the blueprint for success in your software development project.

If you want to learn more about this topic, here are two courses I have authored on Pluralsight.

Stay tuned for more insights and tips on improving your software development skills. Until then, happy coding!

Reference: Pinal Dave (https://blog.sqlauthority.com)