So what do cucumbers have to do with requirements anyway

So both Cucumber and Gherkin are closely related, they are both members of the Cucumis sativus species of vegetable but that still doesn’t explain what they have to do with functional requirements.

If you have recently been exposed to an Agile/XP project, you most likely would have heard the term Cucumber and possibly Gherkin thrown around as the new way of specifying your requirements.

Reading this most of you probably come from a background specifying your functional requirements using Use Case Specifications. Should this be the case for you, you will be happy to know that cucumber/gherkin will not be a big step for you as much of the syntax/format will seem very familiar.

Lets get into it.


The Feature Files contain your functional requirements, and these functional requirements are specified using Gherkin.  Gherkin is a DSL (Domain Specific Language) and it is used to specify the behaviour of your system in the form of scenarios and steps.  The feature files for the time being are actually physical files that usually live in a source control repository somewhere.  You should have a file for each feature in your system that contains all the specification for that feature. It should be named appropriately and you should be able to read it to gain an understanding of the way that feature works on the system under development.

Diving into the Feature file, we come to the Gherkin language/syntax that is used to describe the functionality.

Gherkin starts with a section at the beginning that describes the feature. This will conform to what you may have seen used floating around as the format used on your User Stories.  This section is mainly to set the context for the feature, and does not form part of the executable section of the feature file.


<Feature Name>
<Main user of the feature>
<Description of the Feature>
<Description of the main need for the feature>

Following the feature description is a series of scenarios that describe the behaviour of the system under development.

< Description of the particular scenario behaviour required >
< Some pre-condition that exists before the scenario can occur >
< The trigger that initiates the system behaviour(s) >
< An assertion that describes intended system behaviour(s) >
< Additional assertions that describe intended system behaviour(s) >
< Negative assertions that describe non-intended system behaviour >


Here is an example of a high-level cucumber to illustrate how the tags fit together to describe the system behaviour.

As a bank customer
I want to transact on my accounts
So that I can manage my finances and go about my daily business
Withdraw money from account
a user has an account with the bank
the account has an opening balance
the user withdraws a given amount from the account
And the user chooses to receive a receipt
the system will dispense the given amount
the system will deduct the given amount from the accounts opening balance
the system will dispense a receipt

In practice during development your gherkins will be at a more granular level than this as your development scope will be a lot smaller, but I used the above example as it is one that is often used in the Use Case world, which you might already be familiar with.  With that being said it is still a valid cucumber.

You may also see some words in the feature file that are prefixed with the ampersand symbol e.g.  @in_progress,  @non_implementable, @manual

These are tags, and tags are an unfortunate byproduct of being on the bleeding edge. Much of the tooling around Cucumber/Gherikin is still very immature, so you will find yourself operating down at the development artifact level you need to be aware of these tags. Tags are a multi-purpose method to annotate the cucumber and can be used for indicating progress, tracking versions, and really anything else you may need to identify, group, delineate your feature files with.  Tagging is a very powerful and flexible feature of cucumber, which helps you manage some of the limitations living down in the bowels of the source repository.


Coming to Phase 2 of the diagram above we have Cucumber itself.

Cucumber is probably best described as a testing tool.  It is created by Aslak Hellesoy and is the latest and greatest in a series of testing tools created by the RoR (Ruby on Rails) community to help teams move to a more TDD (Test-Driven Development) and BDD (Behaviour Driven Development) way of development.  As this is an introduction to Cucumber/Gherkin I will leave a definition of BDD to another post.  Allen is one of the authors of The RSpec Book which is considered the bible for TDD and BDD.  If you are of a technical nature, I recommend reading this book.

Using the steps specified in the feature in phase 1, development teams following BDD will typically write the step implementations to match the scenarios, watch them fail and then use the tests to drive the design to make the code pass.

Cucumber will execute all these steps in all the feature files on the latest deployed build and show green for the steps that pass and red for the steps that fail.

Here is a high-level depiction attempting to show this in action, but just imagine cucumber running all the feature files one after the other.  Like a living breathing executable spec.


In phase 3, the cucumbers can be instrumented and added to your continuous integration server and build light.  The build will then fail whenever any of your @completed cucumber tests fail indicating you have recently introduced a regression into your system.

So now that we have covered a little about what cucumber/gherkin are, why should you use them to specify your requirements.

Well the main reason is to build a ubiquitous language.   As the Gherkin is written in a Business DSL, which is used to implement the tests and then drive the design of the code, you will naturally end up pushing your business domain concepts all the way through your tests and your code making your code and tests easier to understand. This provides two main benefits.  Firstly, the development team and business teams will be speaking in the same language, and will therefore understand each other better.  Secondly, it minimizes the translation that was previously required between requirements and code.

In addition, as you create your Gherkin you are moving away from a static view of your requirements in some document that quickly goes out of date, into a living and breathing feature specification which describes the current behavior of your system that is validated every time the build runs.

These feature specifications also provide traceability from your requirements into your tests and code, which should please the audit-minded folk within you.

This was a high-level introduction to cucumber/gherkin and was the first blog in a series of blogs we plan to write on the topic to try and demystify it for you the business folk.


Leave a Reply

Your email address will not be published. Required fields are marked *