Examples of Writing User Stories in Gherkin Format

Introduction

In this article, we explore the widely used Gherkin format for writing user stories and analyze whether it truly deserves the title of being the best method. User stories play a pivotal role in software development as they serve as a communication tool between stakeholders and development teams. They help capture user requirements and expectations in a concise and understandable manner.

The Gherkin format, popularized by the Behavior-Driven Development (BDD) community, is designed to improve the clarity and effectiveness of user stories. It is a structured language that uses a simple, easy-to-read syntax, predominantly based on the concept of Given-When-Then (GWT). Under this format, user stories are written in a more narrative style, making it accessible to both technical and non-technical stakeholders. But is it truly the best way to write user stories? Let’s delve deeper to find out.

The Gherkin Format Explained

The Gherkin format, as mentioned earlier, follows a Given-When-Then structure. Each user story is broken down into three parts:

1. Given

The Given section sets up the initial context for the user story. It describes the existing state or the precondition that must be fulfilled before the user story can be executed. This part aims to provide clarity about the starting point of the story.

2. When

The When section defines the action or the event that triggers the user story. It represents the user’s interaction with the system or the application under development. This step focuses on capturing the user’s intent and what they want to achieve.

3. Then

The Then section outlines the expected outcome or result of the user story. It highlights what the user expects from the system after the action defined in the When section has been performed. This part ensures that all stakeholders have a clear understanding of the end goal.

Examples:

Gherkin Format: Banking Example

Given that  I am a primary applicant

When I complete the loan application and click submit

Then I want to receive a decision on the loan

Advantages of the Gherkin Format

1. Clarity and Readability

The Gherkin format’s greatest strength lies in its clarity and readability. The simple and consistent language allows both technical and non-technical stakeholders to comprehend the user stories easily. This reduces misinterpretation and enhances communication among team members.

2. Collaboration and Inclusivity

As Gherkin is accessible to a broader audience, it promotes collaboration among all stakeholders involved in the software development process. This inclusivity fosters a better understanding of user needs and expectations, leading to a more refined product.

3. Test Automation

The structured nature of Gherkin makes it highly suitable for automated testing. It serves as a bridge between business requirements and test scenarios, enabling the automatic generation of test scripts. This accelerates the testing process and increases overall efficiency.

4. Focused on User Value

Gherkin encourages the focus on the user’s perspective and value. By defining clear user goals and expected outcomes, the development team can prioritize features that directly impact the end-users, leading to a more user-centric product.

Limitations of the Gherkin Format

1. Overhead in Complexity

For simpler user stories, the Gherkin format can introduce unnecessary overhead in terms of complexity. It might be more appropriate to use a more straightforward, traditional format for straightforward requirements, as Gherkin could add unnecessary verbosity.

In other words, using Gherkin can be more lengthy for no reason.

For example a simple login functionality with Gherkin is much more verbose than using a custom approach. Using Gherkin format does not always result in any gains in the team having clraity on what to build than with a custom approach.

Consider this example for being able to show a dashboard after login:

Given that I am on the login screen

When I enter  my username and password

And I am successfully authenticated

Then I want to be able to see the dashboard.

This same functionality could be written much more directly like this:

• The user must be able to see the dashboard after successful login

2. Learning Curve

While Gherkin’s syntax is designed to be simple, there is still a learning curve for stakeholders unfamiliar with the format. Training and education might be required to ensure everyone can effectively use and understand the language.

It can be easy to grasp for simple cases, but as the functionality become more complex it gets hard and harder to fit it into a Gherkin format.

3. Ambiguity in Scenario Outlines

In some cases, Scenario Outlines within Gherkin can lead to ambiguity. These outlines allow for parameterization of scenarios, but without proper documentation or guidelines, they might become challenging to interpret correctly.

4. Narrow Focus on Behavior

As the Gherkin format is closely tied to Behavior-Driven Development (BDD), it might not be the best fit for projects following other development methodologies. In such cases, a more adaptable approach might be preferred.

Conclusion

In conclusion, while the Gherkin format undoubtedly offers numerous benefits, it might not always be the best way to write user stories, as its effectiveness depends on the project’s complexity and the stakeholders’ familiarity with the language. It excels in enhancing clarity, readability, and collaboration, making it an excellent choice for many software development projects.

However, to determine the most appropriate format, teams should consider their specific project requirements, the level of complexity, and the stakeholders’ expertise. Being open to various user story writing approaches allows for greater flexibility and adaptability in delivering successful software products.

So, in the quest to find the best way to write user stories, it’s essential to evaluate the unique needs of each project and choose a format that aligns most effectively with those requirements.

Remember, the success of user stories lies not only in the format but in the continuous refinement and improvement of the communication process between all stakeholders.

If you want to read more information about user stories and Gherkin format checkout my course on writing user stories.