BDD Cucumber cover image
Behavior Driven Development (BDD) has been around in software industry since Dan North mentioned it in 2003. Cucumber is not a BDD and it is not even a testing framework. Many developers think of Cucumber as another alternative testing frameworks like JUnit, TestNG, etc. but it’s official guide clearly describes Cucumber as just a tool that supports BDD. It operates in the specification phase of BDD. We can use it to describe product requirements, acceptance criteria, use cases, and all features we want in our final product. Some of us might be used to something like a use-case template. Cucumber is similar in this regard with its own templating document called Gherkin. Gherkin is a plain structured text system consisting of simple grammar rules, with each line preceded by special keywords. It can be written in many languages. The recommended practice is to ask a product owner and business analyst to join Example Mapping sessions, then let developers (or testers) translate whatever specification is agreed into Gherkin. It is easy for a team to make common mistakes when they start using Cucumber in their BDD. Here are some common Cucumber usage mistakes, and how to avoid them:
  1. Using Cucumber for a product that already exists

Even though Cucumber can be used in any development stage, it can be a mistake to use it after the product has already been created (perhaps to add test automation). There are already plenty of better tools available for that purpose.

The alternative:

Use Cucumber early in the product specification stage. Write down all the features that should be in the final product, and what kind of failure should be covered, etc. Not all team members need to know about Gherkin. One or two should be enough to write and present to the other team members until everyone agrees on the specification.

  1. Using Cucumber as a replacement for another test suite

If you’re looking for a replacement of JUnit, you should probably look somewhere else. Similarly, if you’re looking for the next generation of Selenium, Cucumber might not be your best choice.

Cucumber is simply not a testing framework. It lacks many of the sophisticated features that a good test framework has. It’s only a plain document. It aims to be a collaborative tool which everyone involved in the product can read and understand easily. It cannot assert a condition as other test tools can. It will only check which step has been implemented, and which are yet to be added.

The alternative:

Integrate Cucumber with your specialist test tools. Ideally, you could write step definitions in Cucumber, then check or assert them with unit test tool. Cucumber can be used as a plugin for a complete test suite or it can just hook and run a simple assertion using that tool.

  1. Using Cucumber after a feature has been developed

Imagine we have built a payment feature for an e-commerce site, but haven’t yet agreed what kind of payment we want. There is a temptation to skip over it, since we can just write the final specification later. We might think “we have defined the specification in our head, so there is no need to write it down”. The problem is that we cannot guarantee that what we thought yesterday can be explained well to others today, or that we could remember exactly what we thought later.

The alternative:

Use Cucumber as a “single source of truth”. When we develop a feature, always refer to the Gherkin document. What scenario it defines, what steps it needs, and what result it’s expected. That way, we capture exactly what everyone wanted (or at least agreed to) for the future.If the requirement changes (be it from the creative team or the product owner), everyone needs to sit down and discuss it again, and document the revised specification. It might result in a new feature or minor changes that can be included in the next development phase. After all, that’s what BDD aims for - collaboration.

  1. Writing Cucumber specifications only for developers

Consider the following Gherkin example:

Scenario: Ask for credentials when attempting to access a restricted page

Given: I’m a guest

When I type “http://localhost/admin-dashboard” in the URL

Then the error message “You’re not authenticated” is displayed

And I’m redirected to “Login” page

And the following “text” and “input field” is displayed:


  | input field | text                        |

   |  Username  | Please enter your username |

   |  Password   | Please enter your password |

  And a checkbox “Remember me” is checked

  And a “Login” button is displayed

That kind of scenario clearly describes the process flow when a guest user tries to access a restricted page. The problem is that it specifically talks about UI, so it looks more like UI testing rather than a business rule.

There’s nothing that mandates that Gherkin must be written that way. It’s fine to have some UI testing defined in the step definition, but not this much.

The problem with a lot of UI testing (or any other developer-oriented tests), is that not everyone understands it. If we want to present it more senior stakeholders, they may not care about the UI, and prefer to just see the business process flow.

The alternative:

Turn the above Gherkin specification into a more business-oriented one like this:

Scenario: Ask for credentials when attempting to access a restricted page

  Given: I’m a guest

  When I access “Admin Dashboard”

  Then I should be asked to login

This new Gherkin scenario is clearer from a business perspective and is portable enough that if we later decided to move the admin dashboard to another URL, it will still be valid. This kind of portability was not present in the previous specification since we defined the specific URLs.

I hope that these examples show how Cucumber is sometimes misused, despite it being a great collaboration tool in BDD. Sometimes we just need to ask ourselves if we are really doing BDD with Cucumber or just using it for the sake of testing. Let’s remember this quote (which can also be found in the Cucumber official guide) from Andrew Premdas, one first adopter of Cucumber:

“Your Cucumber features should drive your implementation, not reflect it.”