Why Develop Using Gherkin?

I was having a conversation with David Lazar in the services wing of UST Global (my current company). During the conversation, we started talking about using SpecFlow and I detailed how I used Gherkin with SpecFlow to create a “paint by numbers” kit to drive offshore development.

As I sat and thought about it, I was reminded of a question someone once asked me about breaking down requirements which led to the question “why gherkin?” At the time, I am sure I came up with a clever tactical answer to the question, but now that I think about it more, the question is both tactical and strategic in nature.

To understand this, let’s look at specifics on how I break down requirements with me teams, when I am given some leeway on how the requirements get broken down.

Setting Up the Problem

I am going to start with the assumption that the requirements documents suck. I know this is not always the case, but I find it more likely than not that the requirements are insufficient to get the job done. This has led many company managers to the belief that there is something inherently wrong with offshoring, but the real problem is not so much where the work is being done, but the definition. Let me rathole for a second to explain this.

Company A sends work offshore and it comes back with less than stellar results. When the same work is sent inside the building, the results are much better. So, there is an assumption that it works onshore but not offshore.

But I will contend it IS NOT working onshore either. Things are still getting broken, but the feedback loop is generally much shorter as the business owner can walk over to the development pit and say “what were you thinking?” All of these trips are forgotten when comparing offshore to onshore. In addition, the employees have greater domain knowledge than the offshore team, which reduces the problem domain.

Let’s take this a step farther and compare onshore contracting to offshore. We now have less domain knowledge than employees, unless we are paying top dollar. We still have a short feedback loop, however, so this seems superior.

ASIDE: I have built and led teams in various countries and each has its challenges, As India oft ends up the whipping boy, let’s look at India. In Indian culture, there is a push to get to a higher level title. For this reason, you rarely see very senior resources. The bulk of any team will be somewhere between Freshers (fresh out of college, less than 1 year experience) to Senior Developer (approximately 5 years, maybe 7), with much of the team in the 1-3 years experience range. This is part of why the rates are so low, but it is a trade off. With lower levels of experience, you need more firm requirements.

The point here is the problem is not necessary offshore, it is just exacerbated. Let’s look at an example:

Requirement: At Elite Last Minute travel, a successful flight out is described as:

  1. Client is picked up at home in a limo
  2. Client is delivered to airport and given all pertinent documents by the travel consultant
  3. Client’s luggage is checked into his flight
  4. Client is escorted to the plane
  5. Client is flown to destination
  6. Client is met at destination by a limo
  7. Client is driven to hotel and checked in

Pretty straightforward, right? But what if the client wants to see the Lincoln Memorial (Washington DC) and is flown to Miami, Florida and checked into a hotel there. By the requirements, this would constitute a successful flight out.

This example is a bit on the absurd side, as it seems any idiot should know that the destination is part of the equation for success. But consider this: Once we gain tribal knowledge in a domain, we start to assume it is self-evident, as well. Unfortunately, it is not. Add culture changes into the mix and you might find the assumption leads to disaster.

Breaking down Requirements – Defining Done

The first step we have to go through is breaking down requirements to make sure done is properly defined. Let’s start with a simple requirement:

3.1 Multiplication
All multiplication in the system must return the correct answer

In an Agile environment, this is generally started by stating each requirement in terms of the user:

As an math idiot, I would like to have multiplication done for me, so I can look like a genius

Neither of these defines done, however, without the assumption the coder fully understands multiplication. To fully define done, we need to look at what some of the rules of multiplication are, Let’s say we start with the following:

  1. Multiplying two numbers is equivalent of the sum of the first number added to itself the number of times represented by the second number (okay, my ENglish sucks here, as this is on the fly)
    Example: 5 * 5 = 5 + 5 + 5 + 5 + 5 (there are five 5s in the additional side of the equation)
    Example 2: 2 *2 = 2 + 2 (there are two 2s in the additional side of the equation)
    Example: 5 * 2 = 5 + 5 (there are two 5s in the addition side of the equation)
    Example: 2 * 5 = 2 + 2 + 2 + 2 + 2 (there are five 2s in the addition side of the
  2. Multiplying any number times 0 results in zero (makes sense as the addition side would have zero {number value}s)
  3. Multiplying any number times 1 results in the number (also makes sense, as there is only one of the number in the “loop”)
  4. Multiplying any number other than 1 or 0 times the maximum value of an integer results in an error

This is not the complete rule set, but we can now break the problem down by these rules. I find the easiest way is to set up an Excel spreadsheet with inputs and outputs. For the above, I would use something like this:

Input A Input B Output
5 5 25
2 2 4
5 2 10
2 5 10
5 1 5
2 1 2
1 5 5
1 2 2
5 0 0
2 0 0
0 5 0
0 2 0
0 MAX 0
MAX 0 0

Done is now much better defined. If we take our previous example, we can break down the additional clarification too). NOTE: The actual inputs and outputs are more complex and then get separated out based on the unit being tested.

Input (Desired Attraction) Output (Destination City)
Lincoln Memorial Washington DC
Disney World Orlando
Grand Canyon Flagstaff

If you have not caught this, we are creating acceptance criteria. It is one way of “defining done”.

But What About Gherkin

Gherkin is a language that helps us use the acceptance above. If each line represents a single criteria in the acceptance matrix (the tables above), we might end up with something like:

Given that I chose the Grand Canyon as my desired location
When I fly to a destination
Then I will arrive in Flagstaff

So why is this important? For the same reason that user stories are important. It is a form of ubiquitous language that can be shared between business and IT to ensure everyone is on the same page. Provided we either make each of the lines into users stories and Gherkin statements (or code the acceptance table into Gherkin), we now have a definition of done.

Gherkin adds another value to me, when I am using Spec Flow. I can use the Gherkin statements to produce test stubs that I can send offshore. I call this a paint by numbers kit, as I can open them up in the morning and make sure the right colors were painted in the right spots (ie, they filled the assumptions in the given method, the action in the when method and the test result in the then method(s)).


This is just a brief intro into quality, as subject I am going to explore in detail as the year goes on. And while this may not express it clearly, as it started with an ADD (or ADHD) moment, the important takeaways are these:

  • Business and IT need to be in alignment with language. Here I am using user stories and Gherkin as the ubiquitous (shared) language, but you can have others. Domain Driven Design, which I will focus on later this year, also deals with the ubiquitous language concept, although it is more concerned with modeling the domain than defining done.
  • Most offshoring problems are a combination of expectations (a different understanding of what junior and senior developer means) and incomplete requirements. Fortunately, when we are in the same office, we can walk over and talk and give immediate feedback (not true in offshore engagements)
  • User stories and Gherkin can be used to bridge the gap from improperly defined requirements to a proper understanding of what done looks like (not true in ALL cases, but it is a good start)

Peace and Grace,

Twitter: @gbworld