User stories and Gherkin


User stories and Gherkin

Agility is a toolbox of practices dedicated to individuals, working software, customer collaboration and response to change. Yes, those are the values of the Agile manifesto.

No its not a method; its an approach. It isnt only used in development, like Scrum; it can also be used for business management and for running analyses.

In his blog, Jurgen Appelo attempted to create a list of those Agile practices, some of which can be controversial. We might not agree with all of them but he does deserve credit for creating the listnonetheless.

Among those practices, two can be successfully combined to handle business requirements in an Agile organisation: User stories and Behaviour Driven Development.

User Stories

A user story is a short sentence describing a business requirement from the product owners perspective. Its an easy and fully understandable way to share information from the business to the development team.

Mike Cohn, one of the first signatory of the Agile Manifesto, suggested that the user story be written in the following format:

   As a <type of user>, I want <some goal> so that <some reason>

The type of user (or role) and the goal are mandatory. The reason field is optional if the reason is indeed obvious.

To create a useful user story, one of the best practices is to ensure that it will consider the INVEST principles. A user story should:

  • be Independent
  • be Negotiable
  • be Valuable
  • be Estimable
  • be Small
  • have Tests

Creating tests is mandatory. Acceptance tests must be described to consider a user story has been properly created.

We can create useful and readable acceptance tests with the Gherkin syntax used in BDD.

Behaviour-driven development

BDD is software development technique devised by Dan North. We are only interested in the way requirements are written for BDD. Its called the Gherkin syntax.

Gherkin is a business readable, domain specific language created especially for behavior descriptions. It gives you the ability to remove logic details from behavior tests. (https://github.com/cucumber/cucumber/wiki/Gherkin)

To write a requirement with the Gherkin syntax, we should use the following pattern:

  • Given a context
  • And additional information of context (optional)
  • When a specific action is performed
  • Then an expected result
  • And additional information or expected result (optional)

Use this pattern to describe main behaviours of a user story.

Here is an example:

As a manager, I want to display all guarantee contracts for clients Im allowed to manage.

In this case acceptance tests will describe what happens when the case succeeds and what happens when it fails.

A guarantee contract exists when:

  • Given a manager
  • And he has at least one guarantee contract among selected clients
  • When loading the Guarantee page
  • Then the guarantee list displays all retrieved guarantee contracts 
  • And the sum of the Amount column is displayed under it

A guarantee contract doesn't exist when:

  • Given a manager
  • And he doesn't have any guarantee contract among selected clients
  • When loading the Guarantee page
  • Then the guaranty list is empty
  • And the message "No data available for this query" is displayed


Using user stories and  acceptance tests written with the Gherkin syntax leads to team discussions and  prevents product owners or business analysts from producing heavy and hard to read (not to mention hard to maintain) requirement documents.

Since one of the most important points of agile practices is communication, easing this dialogue between stakeholders will save a lot of time and will increase the added value of implemented features.

Further reading:


Latest news