4 December, 2020
On November 3, alongside some of my colleagues from the Quality Assurance team, we organised a webinar during which we’ve focused on the role of QA from the very beginning of the project. By the way, if you want to recap what we talked about – here’s the link to the whole recording (the webinar was in Polish). During the presentation, we’ve discussed topics related to the testing process, mobile applications, security testing, test automation and business analysis. At some point, when we talked about the creation of project documentation, the use of the Gherkin language while writing User Stories was mentioned. This topic caused a discussion among the audience. We did not have enough time to fully cover that subject. That’s why I decided to write this article and focus on the use of Gherkin language when writing User Stories.
Let’s rewind to that discussion over documentation. As we know, nobody likes writing it, right? 🙂 But obviously, you need to create that to build the system properly. The basic element that can be considered documentation is User Story. In The Software House, to standardize the whole description process, we use an internal template, the so-called description of Kuśmierz-Polak (the title comes from the names of the creators of this template). If you want to learn more about that, I recommend reading the article on writing good User Stories. One of the most important elements of this template is the description of Normal flow and possibly Alternative flow. To describe the course of processes that are to occur after implementing this functionality, we use the Given – When – Then syntax, which comes from the Gherkin language.
Where did this language come from in a technical world like IT? Given – When – Then syntax owes its origins to a certain software development approach, namely Behavior Driven Development (BDD) which is “a synthesis and refinement of practices stemming from Test Driven Development (TDD) and Acceptance Test Driven Development (ATDD)”.
As the creator of this approach, Dan North, writes, 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.”
As he worked on his new approach, Dan North confronted his ideas with some of his colleagues. At some point, they discovered that the new form of test writing was similar to the language used to gather requirements. Their goal was to create a vocabulary that would be understandable to all stakeholders.
Inspired by an article on Domain-Driven Design, they took a closer look at the User Story format and they noticed that it’s all 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 a template to capture a story’s acceptance criteria”. And this is how the Given-When-Then syntax was created.
Let’s take a look at what it consists of. I will use documentation from cucumber.io here.
The primary keywords are:
- Feature – the purpose of this keyword is to provide a high-level description of a software feature, and to group related scenarios.
- Rule (as of Gherkin 6) – the purpose of this keyword is to represent one business rule that should be implemented. It provides additional information for a feature. A Rule is 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. It consists of a list of steps.
- Given – steps are used to describe the initial context of the system – the scene of the scenario. It is typically something that happened in the past.
- 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 – steps are used to describe an expected outcome, or result.
- And, But for steps (or *) – used to write description in more fluid structure
- Background – it is common Given steps for more than one Feature
- Scenario Outline (or Scenario Template) – The Scenario Outline keyword can be used to run the same Scenario multiple times, with different combinations of values.
The theory is one thing, but obviously, you have to put it 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, in this case, it was about the city 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 modal is closed
And in selected items, the city is changed
It is not an extensive scenario because it focuses on only one element, and a broader description of this functionality can be found 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 the example from ProductVision.
Feature: Select profile
Background: Given I am logged in
Scenario: First profile select
Given I go to the application after logging
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 dropdown list
Then I see the dashboard for this.
As we can see, more than one scenario is described in the second example. In that case, when there are common elements like here – you need to be logged in, 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 our webinar mentioned at the beginning of this article. As I mentioned before, a discussion ensued when speaking about the use of this language. I would like to present my point of view on Gherkin.
Gherkin and Business Analysis
Working as a Business Analyst, but also as a QA, we very often move on the border between Business and technical teams. Very often I have encountered the situation that the person delegated to run the project on the client’s side does not always have the technical knowledge and uses “colloquial speech” when describing their needs. In such a situation, presenting the benefits of implementing a given functionality or discussing the paths that the end-user will follow, using the Given-When-Then structure is more understandable and legible for our business. In many publications, the authors also pay close attention to this. Confirmations can be found at Dana North, Michał Bartyzel or on the ProductVision website.
Personally, I also use Gherkin in analyzing tasks and checking whether various paths have been discussed or whether we know the final conditions after performing a given action. Creating subsequent use case scenarios using the Gherkin language helps to analyze tasks in greater detail as well as to present these tasks to the Business. Why? It is not always the case that a person from the client’s side has sufficient technical knowledge to be able to discuss the code with developers. It happens that the person delegated to run our project will be a person without technical knowledge, e.g. from the customer service department.
In this case, presenting tasks from the point of view of a technological solution does not work. Then images speak and here you can use mockups, designs or a piece of paper and a pencil but also the Gherkin language works great. Thanks to this, we have a clear description of what next steps will be performed by our user to complete the task set for them. It has already happened several times in my history that the greater value for the client was to read the next steps they would be performing in their system and visualize it, rather than a deep discussion with developers what would happen below the actions performed.
The Gherkin language is not only used to collect and describe requirements to help everyone understand what will happen in a given functionality. Very often, subsequent scenarios are written with the thought of automating the tests of the paths just described. What are the benefits and what are the difficulties?
These and some other questions will be covered by my colleague in the upcoming article…
 https://www.michalbartyzel.pl/po-co-mi-gherkin/ (Polish)