Writing User Stories With Gherkin

The Origin of Gherkin

Originally intended for developers, Gherkin is a structured approach to writing behavioral tests, also called Behavior Driven Development (BDD). Instead of testing little bits of code, behavioral tests seek to follow true user workflow, such as signing in, or applying for a refund. This means a focus on how users interact with your system.

(Brought to you by the good people at cucumber)

But I’m a product manager. Why are we talking about Gherkin?

Turns out, what comes out of writing behavioral tests is identical to writing user stories: An overview of the goal the user wants to accomplish, the steps they’ll take, and how the product should respond. Sound familiar?

Gherkin is the perfect framework for writing user stories because it gives a consistent approach for reviewing all scenarios, defines the definition of Done, and provides crisp acceptance criteria.

As a PM, the benefits of using Gherkin are:

  • You’ll catch missing workflows before any work is started.
  • It’s a direct correlation to the user workflows that you and Design have developed.
  • Developers know when the story is Done because they have clear acceptance criteria. QA and PM too!
  • A consistent language across stories helps the team focus on delivering user value, unhindered by your writing style that day.

What does it look like?

What happened there?

Gherkin follows a very specific syntax:

Scenario -> Given -> When -> Then

  1. Scenarios: All the actions a user could take (including bad input)
  2. GIVEN: Sets the context. What page are we on and what state are we in? Is the user an admin? Signed-in? Has created a campaign?
  3. WHEN: What actions the user is performing. What event occurred?
  4. THEN: What should the system do in response? What is the expected outcome?

What did we NOT do?

We didn’t mention any technical details, such as database columns or CSS classes. The focus should be on the user, and their behaviors. Push yourself to keep the technical details out of here, unless you’re writing an API. Even then, there shouldn’t be a reference to HOW the code should be written.

Jumping in yourself

Writing in Gherkin is really that easy! Just follow these steps:



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store