Writing First-Class Features: BDD and Gherkin.

Posted in Engineering on Processes
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”

Introduction

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.

Writing First Class Features Dealing with communication is one of the most challenging parts in an organization.

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:

Writing First Class Features GIVEN-WHEN-THEN are fundamental in BDD.

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:

Writing First Class Features Three amigos working together to get the best possible outcome.

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 :).

Basic Syntax

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

TIP: I tend to use Gherkin keyboards in uppercase in order to distinguish between COMMON LANGUAGE and DSL.

Multiple Scenarios

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

Scenario Outlines

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

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.

Writing First Class Features Human-readable feature description with extra information.

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.

Writing First Class Features Diving and Conquer and Keep it simple are very important in sub-diving tasks.

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.

Writing First Class Features Gherkin is a Business Readable, Domain Specific Language created especially for behavior descriptions.

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.

Writing First Class Features Writing Features in a collaborative way is a must.

Conclusion

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.

References