Writing First-Class Features: BDD and Gherkin.
As our product evolves, there is the need to adopt a common vocabulary, interpreted by all the moving parts of our organization: business users, analysts, managers, engineers, etc. A technique like BDD and the Gherkin language can help us to achieve this goal.
“Simple things should be SIMPLE, complex things should be POSSIBLE”
- The search of a common language
- What is Behavior Driven Development?
- What is Gherkin?
- Real World Example
- Tips for Writing User Stories
The title of this article might be a bit confusing…but in this post we are not going to talk about programming languages or architecture…
I do not want to break your expectations though, in essence, we are going to go a bit technical…but we will mostly focus on a Core Part of Product Development:
How to write First Class Features, always keeping in mind Engineering and its impact on the rest of the organization.
We are going to use the term Functionality, Feature and User Story interchangeably.
You can find more info on these definitions here.
The search of a common language
One of the problems that arise and that I see in organizations is global communication. Something that on paper should be easy to manage is most of the time compromised because of the lack of frameworks, tools or common language/vocabulary, thus, leading to misundestandings, incoordination and of course creating stress, pressure and friction.
As our product evolves, there is the need to adopt a common vocabulary/language, interpreted by all the moving parts of our organization: business users, analysts, managers, engineers, etc. The idea is to effectively bridge communication gaps between different areas of an organization.
BDD (framework) and Gherkin (language) could help us to achieve this goal by favoring a more consistent communication channel, so let’s define both and see how we can make a good use of them.
What is Behavior Driven Development?
Let me quote Wikipedia here, which perfectly describes this concept:
Behavior-driven development (BDD) is a process that encourages collaboration among developers, QA and non-technical or business participants in a software project. It encourages teams to use conversation and concrete examples to formalize a shared understanding of how the application should behave.
Fundamentally BDD advocates the usage of a common vocabulary to create a domain specific language (DSL) in order to convert structured natural language statements into scenarios with acceptance criteria for a given function, and the tests used to validate that functionality.
Here is a representation if you are comming from the technical side of things:
What is Gherkin?
Gherkin is a Business Readable, Domain Specific Language created especially for behavior descriptions. It gives us the ability to remove logic details from behavior tests, which turns it into a language that could be understood by anyone without getting deep into implementation details (from an Engineering Perspective).
It serves two main purposes:
- Project’s documentation.
- Automated tests.
As we can see, there is a strong relationship between Gherkin and BDD, so for instance, we can also agree that Gherkin is an implementation of BDD, thus, reponding very well to the approach GIVEN-WHEN-THEN and THREE AMIGOS collaboration:
Do not worry if you are a bit confused and you did not get it yet, an example and a real case scenario will make it more clear. Keep reading :).
The most basic building block consists of a feature description plus an scenario. This scenario consists of a list of steps, which must start with one of the keywords Given, When, Then. But or And are also allowed keyboards.
Here a quick example for a login functionality:
FEATURE: User Login In order to use our mobile client, users should be able to authenticate. SCENARIO 1: Login with email GIVEN there is a login screen AND I have introduce my email and password WHEN I press the login button THEN I should be authenticated AND taken to the welcome screen
It is very common to have multiple scenarios that satisfy a functionality. Let’s take our example above to a new level by adding 2 more scenarios:
FEATURE: User Login In order to use our mobile client, users should be able to authenticate. SCENARIO 1: Login with email GIVEN there is a login screen AND I have introduce my email and password WHEN I press the login button THEN I should be authenticated AND taken to the welcome screen SCENARIO 2: Login with phone number GIVEN there is a login screen AND I have introduce my phone number and pin WHEN I press the login button THEN I should be authenticated AND taken to the welcome screen
When we have similar scenarios with similar information, copying and pasting can become tedious and repetitive. There is a way to avoid this given the following example:
FEATURE: Tip Calculator After calculaing the total of the check, users should be able to optionally provide a tip. SCENARIO 1: Tip out 5% of the total GIVEN the total of the bill is 100 euros WHEN I tip out 5% of the total THEN I should pay 105 euros SCENARIO 2: Tip out 10% of the total GIVEN the total of the bill is 200 euros WHEN I tip out 10% of the total THEN I should pay 220 euros SCENARIO 2: Tip out 15% of the total GIVEN the total of the bill is 100 euros WHEN I tip out 15% of the total THEN I should pay 115 euros
By using scenario outlining, we translate our previous example into:
FEATURE: Tip Calculator ... SCENARIO OUTLINE: Calculating tips GIVEN the total of the bill is <TOTAL> WHEN I tip out <TIP> of the total THEN I should pay <PAYMENT> euros EXAMPLES: | TOTAL | TIP | PAYMENT | | 100 | 5% | 105 | | 200 | 10% | 220 | | 100 | 15% | 115 |
Backgrounds allows us to add some context to all scenarios in a single feature:
FEATURE: Conversation Administrator Role ... BACKGROUNG: GIVEN A global administrator named "Fernando" AND A conversation group called "Android" AND a user called "Antje" not belonging to any conversation SCENARIO 1: Fernando rename conversation GIVEN I am logged in as Fernando WHEN I change the conversation name to "iOS" THEN I should see the new conversation name "iOS" AND I should see a message "Conversation name changed" SCENARIO 2: Fernando add member to conversation GIVEN I am logged in as Fernando WHEN I add "Antje" to the "Android" conversation THEN I should see a message "Antje added to the conversation"
Real World Example
@Wire is secure collaboration platform and as part of leadership, one of my responsibilities is to contribute with product coordination between stakeholders and mobile engineering. Currently we are in the process of improving the platform, and in this case, I wanted to share the re-writing of one of our functionalities: Email Verification.
Step 1: Feature Description
The global description of the functionality is in plain english and has an overview of it. There is no scenario definition and we can add here any kind of useful information that we consider useful for the understanding and further development.
Step 2: Tasks Break Down
It is worth mentioning that level of granularity in terms of breaking down tasks into smaller ones, will depend on the complexity of the feature. Always keep in mind the Divide and Conquer approach.
Step 3: Define Scenarios
At this point, we can fully apply what we have learned so far: Scenario definition and acceptance criteria with Gerkin at sub-task level.
Tips for Writing User Stories
Writing features is not straightforward: many different people profiles are involved and they ALL should understand what they mean.
As an Extra Ball, here are some useful tips, which could help in order to write better Feature/Functionalities/Issues/User Stories, apart from the ones reviewed so far:
- Create Features in a collaborative way. You might start by yourself but involve stakeholders as much as possible without creating a communication overhead.
- Users Come first. A Feature/User Story describes how a potential user utilizes the functionality.
- Keep Features simple and concise. As mentioned, they should be short and easy to understand using a commong language.
- Start with Epics. You might start simple and move towards complexity, you get the global picture and afterwards you can refine it by breaking it down into smaller Features/User Stories.
- Refine the Stories until they are ready. A good technique would be by using a Product Backlog Refinement Session.
- Add Acceptance Criteria. This is a must since it will allow you to describe the conditions that have to be fulfilled so that the story/feature is done.
- Keep everything visible. Use a board or a tool like an Isuues Tracker which is accessible and visible for everyone in the organization.
Communications is very important and it dictates how well structured and coordinated an organization is.
In this post we have seen how a Cross-Communication Framework like BDD in combination with A DSL like Gherkin can help us to mitigate communication issues. Gherkin is also adaptable and flexible, we can even establish your own rules to take it to the next level.
Are you using BDD or Gherkin? As usual, I will finish this way: Any Feedback is more than welcome, feel free to ping me in order to share your thoughts and ideas.