On November 3, me and my colleagues from the Quality Assurance team organized a webinar focused the role of QA from the very beginning of the project (in Polish).
As we discussed the testing process, mobile applications, security testing, test automation, and business analysis, someone mentioned using Gherkin for writing User Stories. The audience woke up in an instant. We did not have enough time to cover that subject then, so let's dig into it now.
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.
Dan North
BDD approach creator
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 acces 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.
Authors
Mikołaj Kukurba
QA/BA with over 3 years of experience. At The Software House, Mikołaj works with great enthusiasm, meticulousness and devotion. At work, he uses tools to visualize the client's needs, such as draw.io or Pencil. In his free time, he loves riding on two wheels in a difficult terrain and visiting playgrounds with his children.