BDD Scenarios Explained: Responsibilities, roles, terminology and fine details in Behavioural Driven Development

Introduction

This article was written for highlighting the differences between jargon terms, roles and generally all the fine details involved with writing Scenarios in Behaviour Driven Development (BDD). It introduces the differences between “Requirements”, “Acceptance Criteria” and “Scenarios”, “Rules”, “Examples” as well as the “what”, “when”, “where” and “how” in writing Scenarios.

What is BDD?

Behaviour Driven Development (BDD) is a set of principles for describing a system’s behaviour by using a common language (Gherkin) for a common goal: “achieve a shared understanding and build it right the first time”.

Shared documents or conversations is not always equal to shared understanding

How does the term “Requirements” differ to “Acceptance Criteria”?

The term Requirements is often used in waterfall development and driven by the client as a list of expected results of a completed project. In its most basic description, requirements are nothing more than a to-do list for a project.

A requirement describes a certain functionality of the application. A requirement is a singular documented physical and functional need that a particular design, product or process must be able to perform. It is most commonly used in a formal sense in systems engineering, software engineering, or enterprise engineering. It is a statement that identifies a necessary attribute, capability, characteristic, or quality of a system for it to have value and utility to a customer, organisation, internal user, or other stakeholders [R]

How teams can collaboratively identify Acceptance Criteria?

Behaviour Driven Development (BDD) and Acceptance Test Driven Development (ATDD) enthusiasts already know how useful it is to have testers, product owners and developers to meet and discuss a new User Story before the development is started.

It’s a great idea, everyone to meet and discuss a User Story. That’s easier to say than done, as what many teams don’t have, is a clear structure for conversations. Meetings often go round in circles and drain the group’s energy. The method of Example Mapping (which I described in a previous post here) can help engineering teams to identify Acceptance Criteria and achieve a shared understanding through structured conversations in quick sessions, lasting up to 25 minutes.

What is a User Story?

A User Story is an informal, natural language description of one or more features of a software system.[R]

How to write a User Story title?

Use the template format of;

As a <type of user>, I want <some goal> so that <some reason>

For example;

As a user, I can indicate folders not to backup so that my backup drive isn’t filled up with things I don’t need saved.

For further reading on this topic, I would recommend you reading this article by Mike Cohn on User Stories.

❗Caution — In some exceptions, the title of a User Story may not be possible to be expressed as seen in the above example. Such User Stories might be those that are related to an API, data functionality or others. That’s totally fine, and in these cases an alternative descriptive format of the author’s choice may take place.

How to write Acceptance Criteria?

In the agile world, the term Acceptance Criteria is normally used by the Product Owner or various stakeholders among themselves as a joint effort. Unlike Requirements, Acceptance Criteria is not a to-do list. It’s a list of conditions that must be fulfilled for a User Story to be accepted as ‘Done’ and the agreement to be considered as finished.

Microsoft Press — “Acceptance Criteria are conditions that a software product must satisfy to be accepted by a user, customer or other stakeholder.”

Google -“Acceptance Criteria are Pre-established standards or requirements a product or project must meet.”

Segutech.com — “Acceptance Criteria should state intent, but not a solution and it should be independent of the implementation, ideally the phrasing should be the same regardless of target platform.” Acceptance Criteria should describe the “what” and not the “how”. [R]

TestingExcellence.com — “Acceptance Criteria are a set of statements, each with a clear pass/fail result, that specify both functional (e.g., minimal marketable functionality) and non-functional (e.g., minimal quality) requirements applicable at the current stage of project integration. These requirements represent “conditions of satisfaction.” There is no partial acceptance: either a criterion is met or it is not”. [R]

An example of an Acceptance Criteria using a bullet point

• We should prevent from selling cats younger than the recommended age

Eventually, by the end of an Example Mapping session all bullet-points of a single user User Story then be converted into “Given-When-Then” (Gherkin) syntax while being verified again by the Product Owner and the team.

An example of an Acceptance Criteria written using Gherkin syntax

Given a cat is younger than its recommended selling age
When we try to sell it
Then we should be told it’s too young

For more comprehensive details on when to write scenarios using Gherkin see the below section on this article, “So, when do we write in “Given-When-Then”?”.

What is the difference between Acceptance Criteria (rules) and Scenarios (examples)?

Some common confusion involves the difference between Acceptance Criteria (a.k.a rules) and a Scenario (a.k.a examples). Acceptance Criteria are a set of rules which cover aspects of a system’s behaviour, and from which scenarios can be derived. A Scenario is an example of the system’s behaviour from one or more users’ perspectives. [R]

As suggested earlier, during the beginning of an Example Mapping the Acceptance Criteria can be expressed as a set of rules using bullet points as shown below;

• We should prevent from selling cats younger than the recommended age

• Customers should be encouraged to return when the cat is old enough to be sold

Eventually, by the end of the Example Mapping session the bullet points can then be converted to Gherkin syntax. For more details check the section “So, when do we write in “Given-When-Then”?” below.

An example of an Acceptance Criteria for a User Story A is shown below

Given a cat is younger than its recommended selling age
When we try to sell it
Then we should be told it’s too young

A Scenario is an example that describes the system’s behaviour from one or more users’ perspectives. In the above case, even though the Gherkin syntax is used, this is not a Scenario. It’s an Acceptance Criteria — a specification of behaviour expressed in gherkin syntax. Often, people write criteria this way and then get confused when they can’t treat it like a real scenario, e.g. breaking it down in detail, identifying negative scenarios and edge cases, automating it. Discussing through scenarios is one of the most important aspects of BDD. By using specific examples to illustrate common understanding, one can discover whether people in a team have shared understanding.

An example of a User Story A Scenario is given below.

Given a cat called Felix is 2 months old
When we try to sell Felix
Then we should be told Felix is too young.

“By talking about both Acceptance Criteria and Scenarios, asking why, and using scenarios to illustrate the criteria, we find out more about our domain. We can also automate them later on, where they’ll help to provide living documentation and act as regression tests.” [R]

Since Gherkin v6, The (optional) Rule keyword has been included. Although, not all Cucumber implementations have finished implementing support for the Rule keyword. See this issue for latest status. In the table below, it is shown how the use of Rules (Acceptance Criteria) and Examples (Scenarios) can be used combined in a .feature file. [R]

# -- FILE: features/gherkin.rule_example.feature
Feature: Highlander

  Rule: There can be only One

    Example: Only One -- More than one alive
      Given there are 3 ninjas
      And there are more than one ninja alive
      When 2 ninjas meet, they will fight
      Then one ninja dies (but not me)
      And there is one ninja less alive

    Example: Only One -- One alive
      Given there is only 1 ninja alive
      Then he (or she) will live forever ;-)

  Rule: There can be Two (in some cases)

    Example: Two -- Dead and Reborn as Phoenix
      ...

📣 Note — For further reading, I would recommend you reading the article “Acceptance Criteria vs. Scenarios” by Liz Keogh here. as well as the Gherkin Reference by Cucumber here.

Who writes what?

The product owner — This person is most concerned with the scope of the application’s normal use. This involves translating user stories into Features and Acceptance Criteria. As the developer comes with detailed Scenarios and the tester with edge Scenarios, the product owner is responsible for deciding what is within scope. [R]

The developer — This person will think of the details that go into each feature. How will this application execute? What are some of the roadblocks or requirements behind the scenes? What are some of the scenarios of abnormal but reasonable use? [R]

The tester — This person will be generating lots of Scenarios, and lots of edge scenarios. How will the application break? What user stories have we not accounted for within these Features? What are some of the scenarios of abnormal but unreasonable use? [R]

So, when do we write in “Given-When-Then”?

During the Example Mapping sessions, the person who attend the meeting with the least understanding of the story will write up the “minutes” of the meeting as Gherkin scenarios and share back to check her understanding. It would be even better to do it in pairs. [R]

The product person would need to spend time and energy in the Example Mapping session, and leave the actual writing in Gherkin to the developers and testers. Once they’ve drafted a “Given-When-Then” specification, the product person can provide feedback.

It is preferable that the first draft of any User Story be written by, or with, a “domain expert”. This person is typically a non-programmer, and someone who knows the feature’s domain from a user or business perspective.

Then the programmer(s) and tester(s) will go over the scenarios, to refine the steps for clarification and increased testability. The result is then reviewed by the domain expert to ensure the intent has not been compromised by the programmers’ reworking.

This cycle is repeated until everyone involved is satisfied that the Scenarios accurately describe what is wanted in a testable manner. [R]

When writing scenarios in “Given-When-Then” format, the user interface (UI) details, or user interactions such as mouse clicks should not be included. If such details are included, it won’t be long before a team starts getting bored and eventually give up with BDD. Scenarios written in this style are not only noisy, long, and boring to read, but they are also easy to break and expensive to maintain.

Where to write the “Given-When-Then” scenarios?

After the Example Mapping session is completed, the Acceptance Criteria written in Gherkin syntax can be used to identify Scenarios (also written in Gherkin syntax) under the description field of a User Story.

Hmm, then how do we capture UI details?

The user interface and user interaction details should be written as text references by the designer next to the corresponding screens with a design tool, such as Sketch/Zeplin. When a User Story includes UI/UX elements then the designer should also be involved in Example Mapping sessions.

📣 Note — For more ideas and different opinions on this topic, read the discussion here.

How do we write Scenarios in “Given-When-Then”?

The rule of thumb of BDD; One Scenario, One Behaviour! If larger flows are written as a single example, it’s often hard to keep track of the context and the example can become ambiguous and easily be misunderstood. A template for writing Scenarios is shown below.

Given a precondition happened (in the past)
When an action happens (in present time)
Then the following post-condition(s) will be satisfied (in the future)

Given — is used to describe the initial context of the system — the scene of the scenario. It is typically something that happened in the past. [R]

When — is used to describe an event, or an action. This can be a person interacting with the system, or it can be an event triggered by another system. It’s strongly recommended you only have a single “When” step per Scenario. If you feel compelled to add more, it’s usually a sign that you should split the scenario into multiple scenarios. [R]

Then — is used to describe an expected outcome, or result.

The step definition of a Then step should use an assertion to compare the actual outcome (what the system actually does) to the expected outcome (what the step says the system is supposed to do). [R]

As a rule of thumb, one scenario should include one behaviour. One of the violations of this rule, is when a Gherkin scenario includes multiple “When-Then” pairs as shown below.

📣Note — In the examples below, you will notice that the keyword Feature has been used. This keyword is used by Cucumber to provide a high-level description of a software feature, and to group related scenarios. Since in your project you may be structuring software features using Epics > Features > User Stories then you can think of the keyword Feature is synonymous with the title of a single User Story instead. Also, the keyword Scenario is a synonym to the keyword Example.

Feature: As a user, I would like to search online using keywords so I can easily retrieve any information I am seeking.

Scenario: Google Image search shows pictures

Given the user opened a web browser
And the user navigates to “https://www.google.com/"
When the user enters “tuna” into the search bar
Then links related to “tuna” will be shown on the results page
When the user clicks on the “Images” link at the top of the results page
Then images related to “tuna” will be shown on the results page

📣 Note — Additional available keywords (other than the Given, When, Then, And) that can be used when writing in “Given-When-Then” are the following; But, Background, Scenario Outline (or Scenario Template), Examples. For more, check the Cucumber document here.

A “When-Then” pair denotes a unique behaviour. In this example, the behaviours of performing a search and changing the search to images could and should clearly be separated into different scenarios, like this;

Feature: As a user I would like to search online using keywords, so I can easily retrieve any information I am seeking.

Scenario: Search for articles from the search bar

Given a user opened the Google homepage
When the user enters “tuna” into the search bar
Then links related to “tuna” will be shown on the results page

Scenario: Image search

Given Google search results for “tuna” were shown
When the user clicks on the “Images” link at the top of the results page
Then images related to “tuna” will be shown on the results page

❗Caution — There might be cases where a single Acceptance Criterion might not be possible to be broken down into Scenarios. That’s fine, the Acceptance Criterion can simply be used as a Scenario as well.

❗ Caution — In some exceptions the Acceptance Criteria of a User Story (as used in the structure of Epic > Feature > User Story) might not be possible to be expressed in “Given-When-Then” format, e.g. a User Story that relates to data, API or other system level area. In these cases Acceptance Criteria can be written using a bullet point within verification lists.[R]. For more, see the section “How to write Acceptance Criteria?” below.

Case studies for understanding how to write scenarios (aka examples) using Gherkin syntax

Case Study 1

Scenario: Redirect user to originally requested page after logging in (Suggested approach)

Given I am an unauthenticated User
When I attempt to view some restricted content
Then I am shown a login form
When I authenticate with valid credentials
Then I should be shown the restricted content

PROS — The beauty of this style is that it is not coupled to any specific implementation of the UI

The scenario can be applied to a web client or a mobile client application. The words used are not technical and are instead written in a language clearly understood by any stakeholder interested in security.

Scenario: Redirect user to originally requested page after logging in (Avoid this approach — Do not use)

Given a User Johnexists with password 123456
And I am not logged in
When I navigate to the home page
Then I fill in Usernamewith John
And I fill in Passwordwith 123456
And I press the blueLogin button
Then I should be on the home page

PROS — It uses very generic step definitions, like “fill in”, “with” , which means you can write a lot of scenarios in this manner without having to create many step definition codes. We could also argue that it acts as a guide to what the user interface will look like, since it names the fields and buttons that will be used in the login form.

CONS — Well, it won’t be long before the team starts experiencing the pain with boring-to-read scenarios. Scenarios written in this style are not only noisy, long, and boring to read, but they are also easy to break and expensive to maintain. If the UI team decides to change the “Login” button to “login”, or change its colour from blue to green, then the scenario will fail, for no good reason at all.

Case Study 2

Scenario: Check inbox (Suggested approach)

Given I have received an email from John
When I sign in
Then I should see 1 email from Johnin my inbox

PROS — A simple three-step scenario that’s clear and concise. This approach is also more maintainable — If the Product Owner wants to change the authentication mechanism, the underlying step definition (code) can be altered without having to touch the features

Scenario: Check inbox (Avoid this approach — Do not use)

Given a User Dave with password password
And a User Johnwith password secret
And an email to Davefrom John
When I sign in as Davewith password password
Then I should see 1 email from John in my inbox

CONS — Remember, that scenarios (examples) should only describe the system’s behaviour. Avoid writing details in scenarios (incidental details) that have no relevance to the purpose of the scenario.

Case Study 3

Scenario (1/2) : Article publication (Suggested Approach)

Publication of an article Article 1 which contains 3 photos is published on April 1 and then re-published on April 3, followed by a change on article's publication date to April 1

Given an article with title Article 1 was published on April 2, 2020
And the article contains photos A, B, C
And the article is re-published on April 3, 2020
When the user edits the article’s publication date to April 1, 2020,
Then the article Article 1 publication date for v1 v2becomes April 1, 2020
And photos A, B, C’s publication date becomes April 1, 2020

Scenario (2/2) : Article publication (Suggested Approach)

Expected search results after publishing article Article 1 and searching for all items with publication date April 1

Given the admin user has published the article Article 1
When the admin user searches for all items with publication date April 1, 2020
Then search results will contain Article 1 versions of v1 v2
And the search results will contain the photos A,B,C

PROS — Each scenario has a unique title. The steps are brief, easy to read with precise expected assertions and written in third person. Additionally, the role of the user is exclusively defined to avoid any ambiguities when compared with other system users.

Scenario: Article publication (Avoid this approach — Do not use)

Given an article was published on April 2, 2020
And it contains photos A, B, and C
And the article is re-published again on April 3, 2020
When I edit the article’s publication date to April 1, 2020,
Then the article’s publication date for v1 and v2 becomes April 1, 2020,
And photos A, B, C’s publication date becomes April 1st 2020
When I search for all items with publication date on April 1 2020
Then I will find v1, v2 and photos A, B, C

CONS — This scenario is written in first-person, too long and complicated to read and understand.

Case Study 4

Scenario: The whole system —(Avoid this approach — Do not use)

Given the application exists
When I use it
Then it should be working, perfectly without issues

PROS — Hmm, I can’t think of any…

CONS — By removing so much of the details from a scenario, it is unable to tell a story. This scenario, of course, is ridiculous, but it illustrates what happens when the level of abstraction is so high that it doesn’t tell the reader anything interesting at all.

It’s recommended to push a team towards a more abstract and declarative end of the spectrum, but as always, the most important thing is to work with non technical stakeholders to get the level right for them.