As we know, nobody enjoys writing it, right? 🙂 But software gets too complex to work flawlessly without documentation. A User Story is one of the foundational documents the team needs to document.

To standardize the whole description process at The Software House, we use an internal Kuśmierz-Polak template (named after its creators). 

One of the most important elements of this template is the description of Normal flow and possibly Alternative flow. We use the Given – When – Then syntax from the Gherkin language to describe how a functionality works for a user.

The origins of Gherkin

Given–When–Then syntax came to life because of the Behavior Driven Development (BDD) approach, which is “a synthesis and refinement of practices stemming from Test Driven Development (TDD) and Acceptance Test Driven Development (ATDD)”. 

Dan North, it’s author, said BDD was created in response to constantly repeated questions.

“I kept coming across the same confusion and misunderstandings. Programmers wanted to know where to start, what to test and what not to test, how much to test in one go, what to call their tests, and how to understand why a test fails.”

Their goal was to create a vocabulary that would be understandable to all stakeholders. He and his colleagues discovered that their new form of test writing was similar to the language used to gather requirements.

Inspired by an article on Domain-Driven Design, they inspected the User Story format and found out that it’s about “discovering what every agile tester already knows: a story’s behaviour is simply its acceptance criteria – if the system fulfills all the acceptance criteria, it’s behaving correctly; if it doesn’t, it isn’t”.

That’s how they created this Gherkin testing template to capture a story’s acceptance criteria by using the Given-When-Then syntax.

Learn Gherkin syntax

Let’s take a look at what it consists of. I will use documentation from cucumber.io here. The primary keywords are:

• Feature – provides a high-level description of a software feature and groups related scenarios
• Rule (as of Gherkin 6) – represents one business rule that should be implemented. It’s als used to group together several scenarios that belong to this business rule
• Example (or Scenario) – this is a concrete example that illustrates a business rule, consisting of a list of steps
• Given – sets the scene of the scenario, typically describing what happened with the system in steps
• When – steps are used to describe an event or an action. This can be a person interacting with the system, or it can be an event triggered by another system.
• Then – describes an expected outcome in steps
• And, But for steps (or *) – used to write a description in a more fluid structure
• Background – groups Given descriptions to add context to a scenario.
• Scenario Outline (or Scenario Template) – used to run the same Scenario multiple times with different combinations of values.

To put theory into practice, let me use two examples here. One of these comes from our project and was related to granting users access to change data.

Given the user is on the list

And user clicks on the checkbox in the selected item

And user clicks on three dots icon

And user chooses Change city

And user sets up a new city name

When the user clicks on Update selected items

Then the modal is closed

And in selected items, the city is changed

It is not an extensive scenario because it focuses on only one element. You can find a broader description of this functionality in our User Story description template. In this case, we only wanted to describe the so-called green user path. However, if we were going to describe many scenarios for one functionality, then it would have to be approached like this example from ProductVision.

Feature: Select profile

Background: Given I am logged in

Scenario: First profile select

Given I go to the application after logging in

When I am asked which profile I would like to choose from my list

And I select a profile from the list

Then I see the dashboard for this profile

Scenario: Next profile select

Given I am on the dashboard

And I have selected profile

When I select from the drop-down list

Then I see the dashboard for this

This second example describes more than one scenario. When there are common elements like here,, then we can pull this element above all scenarios and put it in the Background.

We already know where the Gherkin pattern and language came from. But let’s go back to the question of how one can use Gherkin in business analysis that came up during the webinar.

Gherkin and Business Analysis

Sometimes, the project manager from the client’s side uses “colloquial speech” to describe project needs, because that person doesn’t have sufficient technical knowledge. Creating subsequent use case scenarios with the Gherkin language helps to present tasks to stakeholders in a way they understand.

Using the Given-When-Then structure in such cases can clear out the benefits of implementing functionality that’s the matter of discussion. Dana North, Michał Bartyzel, and the ProductVision team agrees. Instead of debating over how our technology should work for an event, it makes much more sense to put the spotlight on what the user does.

Personally, I also use Gherkin in analyzing tasks and checking whether various paths have been discussed or whether we know the outcome of a user action.

From my experience, clients see greater value in User Stories than in discussion with developers about the software’s functionality, which might be confusing and filled with details that dissapear minute by minute.

The Gherkin language is not only used to collect and describe requirements to represent what happens when we invoke a function of our app. Very often, QA specialists develop subsequent scenarios during their User Story work to have input for automated user path tests. How does that look like?

Our Team Leader Tomas Górski dives into that in a guide called Beyond Behavior-Driven Development – BDD Gherkin tutorial for automated testing, which I think you’d enjoy reading next.