This post is part of the “Behavior Driven Development (BDD): Value Through Collaboration” series.
The previous post explained narrative as a format to describe feature or requirement. Even though narratives can be written by anyone, it is often the result of conversations between the product owner or the business analyst and business stakeholder.
Scenarios describe interactions between user roles and the system. They are written in plain language with minimal technical details so that all stakeholders (customer, developers, testers, designers, marketing managers, etc) can have a common base for use in discussions, development, and testing.
Scenarios are the acceptance criteria of the narrative. They represent the definition of done. Once all scenarios have been implemented, the story is considered finished. Scenarios can be written by anyone, with testers leading the effort.
The whole process should be iterative within the sprint; as the development of the BDD story progresses, new scenarios can be written to cover cases not thought of before. The initial set of scenarios should cover the “happy path”. Alternative paths should be added progressively during the duration of the sprint.
Scenarios consist of a description and given, when, and then steps.
The scenario description is a short explanation of what the scenario does. It should be possible to understand the scenario from its description. It should not contain details and should not be longer than ten words.
Steps are a sequence of preconditions, events, and outcomes of a scenario. Each step must start with words given, when or then.
The given step describes the context or precondition that needs to be fulfilled.
Given visitor is on the home screen
The when step describes an action or some event.
When user logs in
The then step describes an outcome.
Then welcome message is displayed
Any number of given, when and then steps can be combined, but at least one of each must be present. BDD steps increase the quality of conversations by forcing participants to think in terms of preconditions that allow users to perform actions that result in some outcomes. By using those three types of steps, the quality of the interactions between team members and stakeholders increases.
The following process should be followed.
- Write and discuss narrative.
- Write and discuss short descriptions of scenarios.
- Write steps for each scenario.
- Repeat steps 2 and 3 during the development of the narrative.
Following narrative shall be used as an example
Narrative: In order to have a customized experience As a site visitor I want to be able to login
Once this feature has been discussed with representatives of the role (in this case a site visitor) the following initial conclusions can be drawn.
- Visitors should be able to register.
- Existing users should be able to log in.
- There should be an option to retrieve a password.
These conclusions should be written as scenario descriptions.
Scenario: Visitors are able to register Scenario: Users are able to log in Scenario: Users are able to retrieve their password
By starting only with scenario descriptions, we are creating a basis that will be further developed through steps. It allows us to discuss different aspects of the narrative without going into the details of all the steps required for each of the scenarios. Do not spend too much time writing descriptions of all possible scenarios. New ones will be written later. Once each scenario has been fully written (description and steps) new possibilities and combinations will be discovered, resulting in more scenarios.
At this point we can start working on our first scenario. It could look as follows:
Scenario: Visitors are able to register Given the visitor is on the home screen When the visitor clicks the register button Then login screen is loaded When the visitor types his email When the visitor types his password When the visitor clicks the register button Then confirmation screen is loaded
Each action or set of actions (when steps) is followed by one or more outcomes (then steps). Even though this scenario provides a solid base, several steps are still missing. This situation is fairly common because many steps are not obvious from the start. Additional preconditions, actions, and outcomes become apparent only after first version of the scenario has been written.
Does this scenario apply to users who are already logged in? It does not. This scenario applies only to users who are not logged in, so an additional given step should be added.
Given the visitor is not logged in
We might want the visitor to repeat his password in order to make sure that there was no typo.
When the visitor types his password again
The modified story would as follows:
Scenario: Visitors are able to register Given the visitor is on the home screen Given the visitor is NOT logged in When the visitor clicks the register button Then the login screen is loaded When the visitor types his email When the visitor types his password When the visitor types his password again When the visitor clicks the register button Then the confirmation text is displayed
There is still something missing. What happens if email format is incorrect? What happens if the password length is too short? We can fix that by putting example values in our scenario.
Scenario: Visitors are NOT able to register Given the visitor is on the home screen Given the visitor is NOT logged in When the visitor clicks the register button Then the login screen is loaded When the visitor types the email firstname.lastname@example.org When the visitor types the password mysecret When the visitor types the validation password mysecret When the visitor clicks the register button Then the confirmation text Welcome email@example.com is displayed
This scenario covers one of many different combinations. It describes the “happy path” where all actions have been performed successfully. To specify alternative paths, we can copy this scenario and modify it a bit.
Scenario: Visitors are NOT able to register Given the visitor is on the home screen Given the visitor is NOT logged in When the visitor clicks the register button Then the login screen is loaded When the visitor types the email firstname.lastname@example.org When the visitor types the password secret When the visitor types the validation password secret When the visitor clicks the register button Then the text Password must be at least 8 characters long is displayed
The problem with this approach is that all registration combinations might end with many scenarios that have different variations of the same steps. For example, we are still missing the case where the email format is incorrect. Later on we could probably come up with several more variations of this scenario.
Teh examples table can be used to handle this situation in a shorter and easier way. The examples table provides the means to describe different iterations of the same scenario by moving values that change from one iteration to another into a table.
Scenario: Visitors are able to register Given the visitor is on the home screen Given the visitor is NOT logged in When the visitor clicks the register button Then the login screen is loaded When the visitor types the email <email> When the visitor types the password <password> When the visitor types the validation password <validationPassword> When the visitor clicks the register button Then the text <text> is displayed Examples: |email |password |password2 |text | |email@example.com |mysecret |mysecret |Welcome firstname.lastname@example.org | |email@example.com |secret |secret |Password must be at least 8 characters long| |firstname.lastname@example.org |mysecret |something |Validation password is NOT the same | |john.doe |mysecret |mysecret |Email is incorrect |
With this one scenario, we have covered four different cases: “happy path”, incorrect password, validation password, and incorrect email. Each row in the examples table represents one iteration of that scenario. The table is a tabular structure that holds rows of example data for parameters named via the column headers. Values surrounded with < and > are replaced with the corresponding values in the table.
This scenario was not written and fully perfected at the first attempt but through several iterations. With each version of the scenario, new questions were asked and new possibilities were explored. The process of writing one scenario can take several days or even weeks. It can be done in parallel with code development. As soon as the first version of the scenario has been completed, development can start. As development progresses, unexpected situations will arise and will need to be reflected in scenarios.