Guide to using BDD framework and Gherkin syntax in 3 Amigos Guide to using BDD framework and Gherkin syntax in 3 Amigos
Skip to main content
woman writing the software development strategy on a whiteboard

How to use BDD framework & Gherkin syntax with the 3 Amigos

  • 26 July 2019

Our recent blog post explained what the 3 Amigos sessions were and the benefits this can bring to a development team. The premise of the concept suggests that to really build a shared understanding, different perspectives need a common way to devise requirements and document them in a manner accessible to both technical and non-technical project members. This is where Behaviour Driven Development and Gherkin Syntax come in.

Let’s start with Behaviour Driven Development or BDD as it is commonly called. BDD is essentially a framework for thinking about software and specific requirements that we might expect the software to exhibit in certain scenarios or examples. Due to this, you may have heard it referred to as Specification by Example. To illustrate let’s take the concept of a simple login form with separate fields such as username, password and a submit button. If we wanted to think about this in terms of behaviour, the first step would be to try and think of all the scenarios or examples in which a user might interact with this login form. A quick brainstorm of examples might produce something like this…

Scenario 1: User enters correct details and clicks submit

Scenario 2: User enters correct username and incorrect password and then clicks submit

Scenario 3: User enters incorrect username and correct password and then clicks submit

Scenario 4: User clicks submit with empty username and password fields

This list above is not necessarily exhaustive but illustrates the concept of scenarios and their usefulness in terms of thinking about the login story we are implementing.

The point here is to take these examples and then think about how the software should behave in each scenario. This is Behaviour Driven Development.

Once the team has done an initial brainstorm in terms of scenarios, the next step is to translate these scenarios into a format accessible to the whole team regardless of technical understanding. The point here is that business stakeholders, product owners, developers, testers or designers understand the story and its expected output. This is where Gherkin Syntax can play a useful role.

Gherkin Syntax is basically a format for expressing software behaviour using a convention known as ‘Given, When, Then.’ We use this convention when we flesh out our scenarios. In abstract terms it looks something like this…

GIVEN some initial state

WHEN an action is performed

THEN this happens

Let's try this out on one of our examples from earlier.

Scenario 1: User enters correct details and clicks submit

GIVEN I am on the login form

WHEN I submit my correct username and password

THEN I am logged in successfully

AND I am taken to the homepage

In the example above we see the “GIVEN” step lays out the initial state where this user is on the login form. “WHEN” they perform an action such as submitting their correct details “THEN” they are logged in successfully, “AND” the software behaves by taking them to the homepage. You will also notice the “AND” statement above. This is often used to supplement the scenario where additional context is needed. It can be used anywhere after the GIVEN statement such as in the example below…

Scenario 2: User enters correct username and incorrect password and then clicks submit

GIVEN I am on the login form

AND I have entered my correct username and incorrect password

WHEN I submit my details

THEN I am not logged in

AND I see an appropriate error message

The examples above demonstrate how Gherkin allows us to express behaviour in a simple and common format that is easily accessible to both technical and non-technical stakeholders. It also helps to clear up ambiguity amongst the team which in itself can often create waste. That being said there are a few basic pointers to keep in mind when drafting examples and using Gherkin.

Here are our five top tips to help you get started with BDD framework and Gherkin

Get your scenarios down first
If you are unsure where to start then a good starting point is brainstorming the scenarios first before writing any Given, When, Thens. Firstly this will give you a sense of what’s involved in the story and secondly this will provide a clear separation between areas of functionality which will help when it comes to drafting small and testable Given, When, Thens.

Keep your Given, When, Thens small and lean
You want your examples to be small testable chunks of acceptance criteria. If you’re moving into the realm of several ‘AND’ statements after a ‘THEN’ statement it’s likely you’ve rolled several scenarios into one. This would be a good time to think about breaking the example down into further scenarios.

Keep your scenarios and syntax as jargon free as possible
Remember the goal is to create common understanding amongst technical and non-technical stakeholders and so try and remove any jargonistic language. The point here is that anyone should be able to read the user story and understand clearly the functionality and value that is intended to be delivered.

Not everything needs an Example or Given, When, Then
There are times when drafting a scenario is wasteful, overkill or just not entirely necessary. It might just be a simple copy amend, changing the colour of a button or an implementation detail. In that case simple bullet points will work just fine and then you can use specific examples when merited.

Add and amend as needed
You won’t always think of every scenario upfront. That’s ok. AC’s are not gospel and subject to change. Don’t be afraid to amend or update as needed when changes are agreed. Just remember to keep the team in the loop!

Want to know more?

Click here to get in touch