✦Template Printable Ideas Insights

Mastering Gherkin: Top User Story Examples for Behaviour-Driven Development

By

In the realm of project management and software development, user stories are a vital tool for communicating and understanding the needs of users. A well-crafted user story can cascade down to influence a variety of other assets, such as tasks, estimates, and tests. One of the most widely used formats for writing user stories is the Gherkin format, thanks to its simplicity and clarity. Let's dive into the world of Gherkin format user stories, providing examples along the way.

The Gherkin format, used in Behavior-Driven Development (BDD), follows a simple structure: Given [some context], When [an event occurs], Then [an outcome is observed]. This structure helps in creating more concrete and testable user stories. In this article, we'll explore the intricacies of the Gherkin format, providing real-world examples to illustrate its benefits.

Understanding the Gherkin Format

The Gherkin format is characterized by its three-act play metaphor. Each act corresponds to one word in the format: Given, When, and Then. Let's dive into each act, exploring its role and significance.

User Story writing frameworks Courtesy: Agilemania | Janakiram PMP®, ACP®
User Story writing frameworks Courtesy: Agilemania | Janakiram PMP®, ACP®
Writing User Stories With Gherkin
Writing User Stories With Gherkin
Jira User Story Template - A Step-by-Step Guide
Jira User Story Template - A Step-by-Step Guide

**Act 1: Given - Setting the Scene** The 'Given' act sets the stage for the story. It provides necessary background information and context. Imagine you're watching a play; without context, you'd be lost. The same applies here. A well-crafted 'Given' act ensures that everyone involved understands the scenario.

Example: A Simple Login Scenario

Given that the user is on the login page And the user has not entered any credentials yet The login page displays the username and password fields without error messages.

this user is fictionkin on the green background with an image of a star
this user is fictionkin on the green background with an image of a star
User Stories Definitive Guide
User Stories Definitive Guide
Description Ideas Profile, Text Boxes, User Boxes, This User, Fictional World, Describe Me, Get To Know Me, Everyone Else, Just In Case
Description Ideas Profile, Text Boxes, User Boxes, This User, Fictional World, Describe Me, Get To Know Me, Everyone Else, Just In Case

Exploring the 'Given' Act

As you can see, the 'Given' act in this example sets the stage for the next acts. It details the context of the user and the state of the system. This allows us to clearly understand the initial conditions for our story.

Act 2: When - Initiating Action

The 'When' act triggers the event that we want to observe. It's the action that the user takes, causing something to happen in the system. Without the 'When' act, there'd be no story to tell!

The 'When' act is where the user performs an action. In our previous example, this could be entering invalid credentials and clicking the login button. Now, let's see how we can include this in our Gherkin format user story.

Free User Story Templates: Epic, Thematic & SAFe - All Formats
Free User Story Templates: Epic, Thematic & SAFe - All Formats
User Story for Agile Development Projects: Why create user stories? How to Write User Stories?
User Story for Agile Development Projects: Why create user stories? How to Write User Stories?
Tips for writing good user stories
Tips for writing good user stories
Client Challenge
Client Challenge
a diagram showing the different types of user interfaces
a diagram showing the different types of user interfaces
a sticky note with the words user story written on it
a sticky note with the words user story written on it

Refining Our Example: Invalid Login Attempt

Given that the user is on the login page And the user has not entered any credentials yet When the user enters "invalid_username" as the username And "invalid_password" as the password And the user clicks the "Login" button Then the system displays an error message "Invalid credentials".

Delving into the 'When' Act

In this example, the 'When' act clearly describes the user's actions. This helps in ensuring that everyone understands what will trigger the result we're interested in.

Act 3: Then - Observing the Outcome

The 'Then' act is where we describe the outcome of the action. It's the result we want to see after the 'When' act. It's crucial to make these descriptions unambiguous, as they'll be used to verify that the story has been implemented correctly.

Music Userboxes, This User Loves Header, Pink Banner With Emoji Text, This User Loves Their Gf Banner, Fluttershy Twitter Header, Fluttershy Banner Discord, Fluttershy Banner Twitter, This User Loves Her Bf Banner, User Boxes Aesthetic
Music Userboxes, This User Loves Header, Pink Banner With Emoji Text, This User Loves Their Gf Banner, Fluttershy Twitter Header, Fluttershy Banner Discord, Fluttershy Banner Twitter, This User Loves Her Bf Banner, User Boxes Aesthetic
INVEST in your User Stories – Nimesh Soni
INVEST in your User Stories – Nimesh Soni
Made by us
Made by us

The 'Then' act is typically the most critical part of the story. It's where we describe the observable result. Let's look at one more example to illustrate this.

Adding Another Scenario: Successful Login

Given that the user is on the login page And the user has not entered any credentials yet When the user enters "valid_username" as the username And "valid_password" as the password And the user clicks the "Login" button Then the system should navigate the user to the dashboard And the system should display a welcome message to the user.

The Role of the 'Then' Act

As you can see, the 'Then' act in this example describes not just one, but two outcomes. This is a common practice in Gherkin format user stories, as it allows us to verify multiple aspects of the system's behavior with a single story.

Benefits of Using the Gherkin Format

Now that we've explored the Gherkin format in detail, let's look at some of its key benefits:

**Clarity**: The Gherkin format's clear and concise structure ensures that everyone involved understands what needs to be done.

**Testability**: The specific, measurable outcomes described in the 'Then' act make Gherkin format user stories perfect for automated testing.

**Traceability**: The concrete, actionable language used in Gherkin format user stories makes it easy to trace a requirement from its initial description to its final implementation.

Finally, using the Gherkin format encourages a more collaborative and transparent approach to software development. It facilitates communication between developers, QA testers, business analysts, and other stakeholders. By promoting a shared understanding of the software's behavior, it helps to ensure that everyone is working towards the same goal.

In conclusion, the Gherkin format provides a powerful tool for creating user stories that are clear, testable, and traceable. Whether you're a seasoned developer or just starting out, understanding and utilizing the Gherkin format can greatly enhance your software development process. So why not give it a try in your next project and experience the benefits for yourself?