Please note, as of August 2015, this article is superseded by the The Behaviour Specification Handbook

[Updated in April 2015]


As a long-time advocate of Behaviour-Driven Development (BDD), and being the technical lead and coach of BDD enterprise software development teams for more than 5 years, I have tried many different variations of the process of BDD and the writing and implementation of scenarios. The following is my suggested, prescriptive methodology for writing Behaviour Specifications (also known as Scenarios in the Gherkin language), including tips and suggestions that have repeatedly proven to me to be worthwhile practices.

Why BDD?

There are many articles that discuss the beginnings and benefits of BDD, so instead repeating similar information, here are some good starting materials:


There are two important prerequisite inputs to a Behaviour Specification writing session - the requirements and an initial low-level technical design. I cannot stress enough how important these prerequisites are to hosting a successful Behaviour Specification writing session!

Requirement Analysis Complete

Before your team meets to determine the Behaviour Specifications (typically for a User Story, if your team is following an Agile methodology), ensure that the requirements analysis is as complete as possible. The nemesis of a Behaviour Specification writing session is unknown, unclear or incomplete requirements. Unclear requirements are the primary cause of elongated discussions, frustration and confusion in a Behaviour Specification writing meeting.

During the behaviour writing meeting, if missing requirements are identified, I recommend that you simply make a note of them for later and carry on - if possible. On the other hand, if there is a critical requirement missing, it is wiser to postpone the meeting until the relevant details of the requirement can be determined.

If a team ever walks away from a Behaviour Specification writing session exhausted or thinking that the process is difficult, I can almost guarantee that there was a lack of requirements analysis performed before the meeting. The requirements gathering, analysis and clarification is the difficult work that requires and causes the most discussion, time, effort and agreement. Requirements analysis is thus defined as a prerequisite that should remain a very separate process from behaviour writing.

I have witnessed many Behaviour Specification writing sessions turn into requirements analysis workshops. This in itself is not a bad thing - indeed the Behaviour Specification writing meeting has just succeeded in facilitating, identifying and initiating other important discussions. However, if this happens in your meetings, please be careful to clearly communicate to your team that the Behaviour Specifications have been postponed and the team instead is now performing more requirements analysis. If your boss thinks the team has been “doing Behaviour Specifications” for days with none of the expected outputs produced because all the effort has been requirements analysis, then your boss is not receiving accurate information for tracking and planning purposes. It is unfair to tarnish the name of and blame the process of BDD due to an unfulfilled prerequisite. Additionally, it is counter-productive for stakeholders to start questioning the process of BDD because they incorrectly heard that BDD takes a long time and is difficult - when the culprit really was requirements analysis.

Core Business Requirements

There are different types and ways of describing requirements. For the purpose of the Behaviour Specification writing meeting, it is most useful to have the “core business requirements” understood and documented before the behaviour writing meeting.

A “core business requirement” has a clear purpose and business value, and it explicitly does not contain a description or specification of the implementation details.

If a “requirement” includes implementation detail, then there is the awkward situation where non-technical business colleagues are effectively dictating the implementation design to the technical experts. The technical folk however may think of a better implementation option, if they were empowered and given the opportunity.

Sometimes the “core” requirements are already known, but many times the author of a requirement has innocently encoded implementation-specific details within the requirement. A common example is with User Interface requirements. The User Interface requirement may, for instance, specify the need for a new textbox on a screen. That however is not a “core business requirement” because both “textbox” and “screen” are implementation details.

It is more beneficial to take these implementation-specific requirements and convert them back to “core business requirements”. The “5 Whys” principle can be used to find the “core” or root requirement. By iteratively asking “Why?” or “What is the real underlying business need for doing XYZ?” the “core business requirement” can be uncovered.

Below is a contrived example.

Let’s assume that the documented requirement is: “Display a new textbox on screen XYZ so we can enter data for ABC”.

“Because we want to enter data for ABC and screen XYZ has related stuff on it.”

Why do you need the data for ABC?
“We need that data for ABC to calculate MNOP.”

Why do you need to calculate MNOP?
“To correctly invoice the customer.”

With this understanding we can now state that the “core business requirement” is: “To receive information about ABC so that the customer can be invoiced correctly”.

It is this type of business language that I highly recommend be used in the Behaviour Specifications / scenarios - not implementation-specific language about a textbox!

I highly recommend that, as overarching style guideline, all wording that is used in a Behaviour Specification should only need to change if there is a change to the “core business requirement” - and should not need to be changed if there is a change to the technical implementation. If you follow this recommendation, your Behaviour Specifications will live and stand strong through the passage of time.

Draft Low-Level Technical Design Complete

After sufficient requirements have been gathered, the solution/technical architects, designers and gurus in the team should have met, discussed and sketched out an initial, draft version of a low-level technical design that identifies the likely systems and components that will be involved in the story.

During the Behaviour Specification writing meeting, the team will focus on defining the behaviours of each of the components that were identified in this low-level technical design.

In Behaviour Specification Writing Methodology - Part 2, I discuss how to successfully run a Behaviour Specification writing meeting.

Please leave below any comments, feedback or suggestions, or alternatively contact me on a social network.

comments powered by Disqus