fbpx

A practical blog on how to write Scenarios using BDD

If you’re like me, you might have heard about Behaviour Driven Development (BDD), but have struggled to understand how to write your Acceptance Criteria in this format. Agile training courses encourage using it, but rarely offer an explanation of how it works in practice.

It wasn’t until I was using BDD on a daily basis within a team that had already adopted the practice, when it all clicked for me. This is why I’m aiming to explain in practical terms how it works, so that you can either begin using it or get a refresher on BDD.

BDD aims to explain the behaviour of a system in easy to understand language1. Using BDD and Scenarios allows requirements and tests to utilise the same approach in documenting system behaviour. In some cases, the Scenarios that are written can be converted into Automated Tests.

The format is fairly simple, but sometimes hard to get your head around how to write in this format. In order to explain how it works in practice, I will be using the Facebook registration page (shown below) as an example within my Scenarios2.

 

Given… When… Then…

In its simplest format, BDD uses three main descriptors to write a Scenario: Given, When, Then. The text that follows after the descriptors is explained below:

Given [context]
When
[event]
Then
 [outcome]

Taking the Facebook example, below is a scenario that goes through the sign-up process:

Given Fred is signing up for Facebook,
When he submits the required details,
Then a Facebook account is created.

Using Ands

When you require more information in a scenario, an ‘And’ can be used after any of the descriptors:

Given [context],
And [more context],
When [event],
And [another event],
Then [outcome],
And [another outcome].

What I found was lacking in my Facebook scenario was the fact that it assumed that Fred had entered the details. I’ve also added a bit more detail of what happens when Fred’s account is created.

Given Fred is signing up for Facebook,
When he enters the required details,
And submits his request,
Then a Facebook account is created,
And account name is set as Fred’s email address,
And a confirmation email is sent to Fred.

Of course, then the question could be asked, what are the required details that Fred needs to enter? Below I have used multiple ‘Ands’ to explain all the events that are required to be met before an account can be created.

Given Fred is signing up for Facebook,
When he enters his First Name,
And enters his Last Name,
And enters his Email,
And re-enters his Email,
And enters a new Password,
And specifies his Gender,
And enters his Birthday,
And submits his request,
Then a Facebook account is created,
And account name is set as Fred’s email address.
And a confirmation email is sent to Fred.

Using tables to summarise variables within a Scenario

As you can see the above example is quite long winded. A technique that can be used to summarise the multiple ‘Ands’ within your scenario is to use a table (or a bullet point list as I’ve used below). When using this format, all of the variables within the table must be met in order for the Scenario to be successful. Below is an example of how to do this:

Given Fred is signing up for Facebook,
When he enters the following required details:

Required details

  • First Name
  • Last Name
  • Email
  • Confirm Email
  • Password
  • Gender
    Birthday

And submits his request,
Then a Facebook account is created,
And account name is set as Fred’s email address.
And a confirmation email is sent to Fred.

One thing to be careful of when using this format is to consider whether your scenarios are going to be converted into Automated Tests. If this is the case, then depending on the tool you’re using the formatting is important, otherwise it will break the build.

 

One final thing…Adding a title to your Scenario

Each of your Scenarios for the Story should have a title. The title explains what the activity is that the user (in this case Fred) will be able to complete when we finish the scenario. This way you will have an idea of what the finished Scenario should look like before you start3. Below I have provided an example Title for the Facebook scenario I have been elaborating:

 

Scenario: 01: Completing sign up form creates Facebook account

Given Fred is signing up for Facebook,
When he enters the following required details:

Required details

  • First Name
  • Last Name
  • Email
  • Confirm Email
  • Password
  • Gender
  • Birthday

And submits his request,
Then a Facebook account is created,
And account name is set as Fred’s email address.
And a confirmation email is sent to Fred. Although this is all I will go through today, I will be continuing to look into how to use BDD in a few weeks time. This will include how to write exception scenarios, and splitting out Scenarios into different Story Cards. If you’re looking for some further information in the meantime, you can refer to the references I used while writing this article.

Credit must also go to Paul Velonis and Rupi Parmar who provided a few tips when writing this article.

 


References:

  1. Behaviour Driven Org
  2. Facebook
  3. What’s in a Story?

 

18 comments

  • David J C Morris

    A very nice introduction for people who are new to BDD.

    Some people struggle with any formulaic approach to writing, including — As a [role] I need [feature] so that [benefit].

    However, I normally politely point out to them that having 200 statements all beginning with "The system shall …: is just as formulaic and nowhere near as helpful.

  • Ryan McKergow

    Thanks for the feedback David.

    You definitely make a good point about using statements. This is how I documented Acceptance Criteria on my last project, and I’m starting to prefer using BDD. It helps to understand the flow of how some one is expected to interact with the system, as apposed to saying the system should just do a bunch of things.

  • sudhindra

    Great article and l really like the example being used..

  • James Billson

    Interesting that this agile approach is looping back around to quite like a use case in the end. The requirements analysis process has actually been well and truly nailed long ago, but for some reason analysts seem to suffer from the not-invented-here fallacy more than the other players in the software development world. In my experience there is only one thing that works for both clients and developers, and that is the narrative. Mix it with some formality to capture the details needed, and you have use cases. Or keep shaping new wheel.

  • Faten Ben Ameur

    Good evening
    Please, can we use more than one WHEN and THEN in one secanrio!!
    I need a response 🙁
    Thank you

    • Ryan McKergow

      Hey Faten,

      My apologies for the late response!

      From my experience, the short answer is yes. To me, do what works best for you. Yes, there can be lots of rules with using BDD, but I’m always an advocate for just get the job done, rather than being perfect with syntax and the like. Though I know others would disagree, perhaps very strongly disagree.

      These references may help:
      http://stackoverflow.com/questions/12060011/is-it-acceptable-to-write-a-given-when-then-when-then-test-in-gherkin
      https://gojko.net/2015/02/25/how-to-get-the-most-out-of-given-when-then/

      One aspect I would consider is whether your BDD syntax is being turned into automated tests. If it is, I’d have a chat with the people they are doing the automation to get their opinion on this.

      I hope this helps.

      Cheers,

      Ryan

    • Liam

      no – if you have multiple when clauses it means your scenario is two complex to be handled in once scenario and indicates you should split this into two – this is best practice according to many experts I have spoken with on this topic

      • Liam

        However, Multiple Givens and Thens are fine. I agree, just get the job done but that is best practice and you may find yourself with issues of the scenario no longer being described accurately when you come to write your code.

  • pedro

    thanks

  • Volodymyr Rybalkin

    Good article. When there are multiple tests for a story i.e. alternative flows, exception flows, etc how do you recommend grouping multiple scenarios together to ensure their readability?

    Would you use a table where the column headers would be given when then and each row would represent a test or you would suggest some other format?

  • Smita

    I feel all the pre-requisite data should be part of GIVEN clause.
    For this example, Fred entering required details should be part of GIVEN and not WHEN. I would write this scenario like this:

    SCENARIO: Fred is signing up for Facebook
    GIVEN Fred enters the following required details:
    First Name
    Last Name
    Email
    Confirm Email
    Password
    Gender
    Birthday
    WHEN he submits his request,
    Then a Facebook account is created,
    And account name is set as Fred’s email address.
    And a confirmation email is sent to Fred

    • Daniel Trezub

      Hi, Smita. I disagree: GIVEN clauses must be used to set up the environment prior to the tests, not to describe ACTIONS taken during the test. Unless you are only testing the SUBMIT button, but even though the GIVEN should read like:

      GIVEN Fred is on Facebook sign up page
      AND the following info is filled up
      (table with required info)
      WHEN he submits his request
      THEN blablabla

      What do you think?

      • Varsha Mathad

        I would say it has to be as follows:

        GIVEN Fred is on Facebook sign up page
        When the following info is filled up
        (table with required info)
        AND he submits his request
        THEN blablabla

  • Keerthi Ravi

    Informative and understandable one! Thanks

  • Swathi

    Very well explained…
    I am totally new to BDD

  • Siddhi Oak

    I would like to add a point here.. Why is ‘OR’ not a keyword in BDD. I wonder if we had ‘OR’ as a keyword, it would simplify and optimize the use of repeating the scenario while writing in user stories.
    For Example:
    Feature: As a user I want to write an api that will be able to upload an input file for runoff algorithm and generate the output in the csv format.
    Scenario: BAD REQUEST response for ‘invalid’ POST request
    Given: I set API endpoint as algorithm/runoff/upload
    When: I set HEADER param request content type as “multipart/form-data”
    And set request body as invalid input file with incorrect sequence of fields
    Or set request body as invalid input with non-csv file ——————————————— if it was a keyword, now just to check this condition we again need to repeat the conditions.
    And send POST HTTP request
    Then: I receive invalid HTTP response code 400
    And Response body is non-empty with error message

Leave a Reply to Varsha Mathad Cancel reply

Your email address will not be published. Required fields are marked *