In this tutorial, we will learn how to write User Stories for your product using a Gherkin Syntax.
If you’re part of an Agile product team, you are probably already familiar with user stories. User Stories are the human-readable descriptions of how features in your app should work from the perspective of one of your user profiles.
Traditionally user stories have been written using the format of the Connextra template. Which looks like this:
As a <role> I can <capability>, so that <receive benefit>
When planning the requirements of your product, the user story provides the criteria for your “Definition of Done”. The definition of Done is the product owner’s criteria to confirm the feature is complete.
While the old Connextra template is very flexible, it often falls short. Developers and testers need something more prescriptive to build and test the feature, which is where Gherkin Syntax comes in.
Gherkin Syntax is a plain language format for describing user behaviour. The format uses the main keywords; Given, When and Then. Gherkin allows developers to follow BDD (Behavior Driven Development), which focuses on real-world test cases of how people will use your app.
The main benefits of using Gherkin are:
- Getting you to think with empathy for the user and the possible scenarios they will encounter while using your product.
- The team know when the story is Done because they have clear acceptance criteria.
- They provide a consistent language across stories which helps the team focus on delivering user value.
When writing with Gherkin, there are only a few keywords to remember:
- Scenario – used to set the scene of your test.
- Given – used to describe the initial context of the system.
- When – used to describe an event or an action.
- Then – used to describe an expected outcome or result.
- And or But- used to make your writing more fluid when you have successive Given’s, When’s, or Then’s.
Here’s an example of a user story written with Gherkin syntax.
Scenario:
Adding to shopping cart
Given that I am on a product page
When I click the add to cart button
Then I’m taken to my cart page to see the product has been added
And the total has been updated
Now we know what Gherkin Syntax is and why it’s useful. Let’s get into the tutorial of writing user stories with Gerkin syntax.
Grab A Basic Writing Tool
When writing user stories, it’s important not to get bogged down in complexity. To keep distractions to a minimum, go for a simple tool rather than complex software – a physical notepad and pen will do the job.
Pick One Feature at a Time
Start with only one feature from your hitlist, don’t try to do them all at once. It can be helpful to pick a simple feature, to begin with so you get used to writing user stories in this way. An excellent feature to start with would be the user login.
Think About Who Feature Is For
Many apps will have multiple types of users that are based on your user profiles. So before you write your user story think about who the feature is for. For example in an e-commerce product, your Buyers will have very different requirements from a Store Manager or, Administrator. So it helps to start the user story off with who will be using the feature. For example:
As a Customer
Otherwise, if the feature is for everyone the generic ‘User’ will work.
As a User
Think About The Possibilities For The User
Remember to write from a users’ perspective. So, think about what they can do and the “what if” questions. For example, happens if the user has forgotten their password? What happens if they have mistyped their email? What happens if they log in for the first time on a new device?
You may not have all the answers, but you can clarify them later with your team and stakeholders.
Write the Given/When/Then for each Scenario
Now that you have the feature and its possibilities, you can break the information down into the Gherkin structure, using the keywords; `Given`, `When`, and `Then`. For our login feature, it would look something like the following.
Scenerio:
Logging in to the app.
As a User
Given that I am registered but not logged in
When I open the app
Then I see a screen asking for my login details
Review all your When/Then conditions
Read back through your user story and review how often you use `Then`, `AND`, `When` keywords. If you are using them a lot, then it’s a sign that you may need to break them into smaller stories. An example of a story that needs breaking down will look something like this:
Then the user sees the dashboard
And sees new notifications
And sees their recent orders.
Edit For Clarity and Conciseness
With the user storey drafted in the Gherkin format, take the time to make sure it’s clear, concise and makes sense. Remember, these user stories need to be understandable by the whole team.
Tip: You may find it helpful to work with a tool like Grammarly to get your grammar and conciseness on-point.
Input the User Stories into your tracking software
With the user stories written, you can add them to your tracking system. Once inputted, they can be sorted and processed as part of your agile product development process.
If you’re working as part of a product team, you’ll likely need some software designed for Agile development. One of the most common is Jira by Atlassian.
Final Thoughts
Now that you’ve seen how to write user stories with Gherkin Syntax, you should be feeling confident in taking your user stories to the next level. It may take a bit of practice to get used to writing this way, but once you do, you’ll wonder why you never did them like this before.
