Boiled Gherkin: BDD at Friday, Part 1

Nick Dunn

4 minute read

At Friday we develop software following principles of Behaviour Driven Development (BDD) to ensure that we're not only building the right thing, but also building the thing right.

We develop software by first deciding what the customer-facing behaviour needs to be before we write any code. One way of reaching this consensus is to use a technique known as Specification by Example where real-world examples of customer journeys, content and data are used to drive out how the software needs to behave.

The output of using this technique is a set of acceptance criteria — an agreement of exactly how it should work — which are written down and documented as scenarios. We write these in the Gherkin language, which is a set of simple rules that result in a series of statements starting Given–When–Then.

Documenting acceptance criteria in a formal, consistent and clear way is essential to getting value from BDD in two ways:

  1. A single specification that business people, developers and testers all share. Removes the need for messy spreadsheets and annotated wireframes that quickly get out of date.
  2. The potential to augment this specification with code to produce a set of automated acceptance tests. Keeps the tests as close to the specification as possible to reduce deviation and encourage broad coverage.

Boiled gherkin

The Gherkin language is deceptively simple. It only stipulates a handful of formatting rules and grammars you need to stick to, such as starting each new line with "given", "when", "and" and "then". Beyond that, it's up to you... which means there can be wild variations in how scenarios are written based on the author's writing style.

Here are two examples of documenting the same scenario using Gherkin:

Which is clearer to you?

The first example is very literal in that it describes the exact steps required to complete a login. Every UI interaction and input value is listed in sequence. This is commonly referred to as the "imperative" style, and is often found in Cucumber test suites where scenarios are written by developers or test engineers for developers and test engineers. The imperative style isn't wrong per se, but the specification has a limited audience because of how wordy it is. It's not something we'd expect our clients to read, understand and contribute to.

Friday teams prefer to use the "declarative" style of the second example. The "how" is removed and scenario is boiled down to the "what" — the outcome that the user sees their welcome greeting. The email address they used to log in and the exact welcome message are implementation details that aren't so important to the specification.

Sliced and diced

The differences between the imperative and declarative styles has been discussed at length elsewhere, but with little discussion of the actual benefits beyond subjective opinion that one is better than the other.

Because we prefer to keep scenarios short and readable, they are more likely to be shared with clients. The Gherkin scenarios are used as:

  • The specification for developers, describing what needs to be built. Having the detail here ensures wireframes, visual designs, spreadsheets and Post-Its don't become the master specification.
  • The delivery scope for clients to understand what is going to arrive from the team. In a world of agile delivery where scope and priorities can change week to week, a specification that always matches the product backlog is essential to avoid confusion.
  • The test scenarios and acceptance criteria for testers in the delivery team, but also for UAT teams who haven't been at the coal-face of the delivery but quickly need to understand how the product works.

Two for one

Modern digital services are seldom delivered via a single channel, rather they reach users through multiple web and mobile applications.

We recently developed a service that spanned both web and mobile apps, with about 90% feature parity between the two — the website as a JavaScript single page application and the mobile app as an Ionic hybrid app deployed for both iOS and Android. Although there were two separate development teams delivering these two components, they were working from the same shared specification that described how each feature should work. By writing our scenarios using Gherkin in a declarative style we removed any reference to implementation details specific to websites or mobile apps, which meant the whole service could be described from a single set of feature files.

The outcome of this approach was an automated Cucumber test suite that can be run against both web and mobile components. Each scenario was given a @web or @mobile tag that describe which component it is applicable for. The majority of scenarios have both tags. The complexity of running the tests is hidden away in the step definitions — Selenium drives a browser for the website, and Appium drives device emulators for iOS and Android.

This approach proves there is strategic value and a genuine ROI in writing our Gherkin scenarios in such a restrained way. We have a single specification to refer to, and a well-defined automation framework to enable feature parity across web and mobile apps.

Too many cooks

Because the Gherkin documentation is being shared by clients, business people, developers and testers, it is vital that everyone can see and edit them. The BDD approach falls apart if the specification is locked away and only visible to the developers, or if the Test Lead is a bottleneck as the only person authorised to make changes.

Our teams tend to use collaborative Specification by Example workshops during project kickoffs, and/or Three Amigos sessions during sprints to ensure the right people are in the room to feed into the initial scenarios. These are captured by a nominated "scribe", usually a member of the QA team, and committed to the project's code repository alongside application code. Any member of the delivery team can make changes that are then peer reviewed before merging. This ensures the whole team stays up to date about what is changing without reliance on a single owner.

Finally, the scenarios are shared back to clients either by inviting the more tech-savvy to the code repository — the barrier to entry on GitHub these days is very low — or by embedding files in highly visible places like Jira or Confluence.

Cheque, please

At Friday, we transform the customer experience by digitising core products and services at speed. Writing crystal clear, concise specifications is a critical component in our being able to rapidly deliver digital solutions that work.

If you want to hear more about BDD or any of our methods, then please do get in touch at

Nick Dunn

Technical Director
View all thinking