Gherkin for Product Owners, or how to communicate efficiently with engineers
Once upon a time I worked with a Product Owner that used to write her feature specifications in Gherkin language. Every engineer in the organisation was amazed with that, we perceived it as a super-power for communicating with us, Developer’s and QA’s, in our own language.
Gherkin is a well-known tool for engineers because most Behavioural Testing frameworks use its syntax, or at least a version of it; but surprisingly it didn’t become very popular as a standard for communication between Product and Tech people. Yet. Our intention here is to contribute to fill that gap.
We firmly believe that using Gherkin as a shared standard between product and engineering people can improve the efficiency of communication, removing ambiguity and shortening the feedback loop, clarifying the agreements, lowering the risk of having different interpretations. In short, Gherkin will help the team to speak the same language.
When User Stories Are Not Enough
“As a user I want to do something in order to achieve some result”, you know. User Stories are a great tool for capturing and communicating our system’s expected behaviours and while being so simple they have many advantages.
- Since we’re specifying the target user, we ensure our features are actually providing value to someone.
- They cover both expected interactions and results with just enough narrative.
- The context of the requirement is explicit through the result definition.
Unfortunately, the User Story approach also has its limitations. Its simplicity has two sides, while it removes noise from the message to be shared, it also removes important details. Nobody uses User Stories alone for specifying features, our Jira tickets are then bloated with additional constraints, acceptance criteria, notes, examples, interpretations and all sorts of things to clarify the exact meaning of our User Story.
For complex user flows involving many steps, we even split User Stories into smaller ones, but there’s no explicit connection between them unless we group them using Epics.
Summarising, User Stories have the following limitations.
- They are limited to describing the happy path.
- By itself, the approach lacks a way for grouping multiple Stories together.
- There is no room for adding details and examples.
Gherkin comes to the rescue when we have to deal with behaviours that cannot be summarised in a short sentence, when we need to provide all the details so what we get from our system is exactly what we expected. And it does it in a way that leaves little room for misunderstanding, by using examples.
What a Gherkin Feature Looks Like
Gherkin is a syntax for describing the system features using examples that describe the expected behaviour step-by-step. Let’s see an example of a very simple “Gherkin Feature”.
As you can see, the expected behaviour is thoroughly described with detailed instructions to reproduce it. Think of it as if you were giving instructions over the phone to someone interacting with your application. The expected results are then established so anybody can check if it is working the way it was supposed to.
Dissecting the Feature
A Gherkin feature has two main parts, the feature explanation and the scenario examples.
The Feature section describes the expected behaviour from a high-level perspective using an open syntax.
You can use a simple title.
A User Story approach.
Or your homemade convention.
The Scenario part (or Example, they are equivalent) is where the magic happens. You can add to each Feature as many Scenario blocks as you need to completely describe the expected outcome. They always start with a brief summary followed by an arbitrary number of steps that explain how the system should behave.
There are three types of “steps”: Given, When and Then. We can also use And and But as wildcards that mean “the same as above”.
Givenrepresents the context, the required state of our system for the interaction to work.Whenrepresents the interaction itself, what the user does to achieve a result.Thenrepresents the expected result, how the system will respond or how it will look after the interaction.
Putting it all together, this is how a full Gherkin feature could look like.
Writing Great Features
While being pretty straightforward, the Gherkin approach is not free of pitfalls, so there are a few tips for unleashing its full potential and avoiding some common mistakes that deserve being shared.
Yes, You Are Writing Code!
Believe it or not, Developers and QA Engineers can use your feature specifications into their code in order to automate the testing of the application. Sounds exciting? They do that by writing what they call “Step Definitions”, which are pieces of code that translate between the human-readable steps you have written and their mumbo-jumbo-on-a-black-screen.
This has some important implications.
- You are enabling them to practice the so called Behaviour-Driven Development (BDD), which is said to dramatically improve the quality of software: less bugs and happier users. So, by using Gherkin, you are not only improving communication but also promoting better engineering practices that could increase the reliability of your system. Big kudos for you!
- You and the techies will have to work together, they will ask for improvements in your features in order to allow reusability, consistency and correct mapping between the specs and the code. If you have some smart engineers onboard they will also evangelise you about the Ubiquitous Language. Keep your mind open and look at Gherkin features as a resource to be owned collaboratively among the team.
- Changing a single word in a step can potentially involve non-trivial development in order to adapt the system behaviour. So take it seriously, consider your feature specs as a source of truth that should be stable enough to match your team’s rate of change capability.
- As a conclusion, introducing this practice will affect the whole development process, not only the initial specification phase. At the end, you should expect higher predictability of your delivery stream.
But it is Business Language
The previous tip should not distort the nature of Gherkin features, remember that they should be writable and readable by Product people like you. It turns out that your engineering peers also use the same tools for writing more technical tests (for APIs and that sort of stuff), and that’s absolutely right as long as they do it in isolation to the Product-faced features; but never let that technical detail leak into your behaviour-driven feature specifications.
Your collection of features should not contain references to endpoints, database columns, microservices, repositories or other technical jargon; no matter if you are tech-savvy enough to understand that gibberish.
Given, when, then… when, then, when, given, then
The Given When Then structure of your scenarios should be set in stone. At some point you could be tempted to add an additional action after having checked the results so you can test another part of the flow… But that’s a terrible idea.
There are plenty of reasons for not doing this, some of them are technical and out-of-scope in this article, but the main one is to keep the legibility and clearness of your scenarios. Even in the simple example above, it is noticeable how the scenario definition has been affected, making it harder to figure out if we are describing the system status, performing an action or checking results. It also ruins the syntactical structure of the text: ”Then I can see the doctor listed when I click the doctor’s name”, if read naturally, means just the opposite to what the scenario is trying to describe.
Cheating with the Keywords
The specific purpose of Given, When and Then steps is an important convention that must be kept for the Gherkin approach to work properly, avoiding unnecessary confusion and implementation issues when used in automated test suites.
Remember that Given should describe the status of the system before the interaction, so it usually starts with I am, there is, I have, and similiar kinds of statements.
When steps represent user actions, avoid using them for verifying the state of the system before or after the interaction.
Then is only for checking the final outcome, once you add Then step no further actions are allowed.
Me, myself & I
While the Gherkin language itself does not limit who the subject of the steps should be, there is a good reason for using the first person whenever possible. If you are familiar with the User Story style, you are already aware of it.
Imagine the following scenario.
It doesn’t look bad, does it? Well, it may not be obvious, but this practice has many dangers.
- When testing it, either manually or automatically, we would be forced to switch roles in the middle of the test. It could be even impossible to be automatically tested for this reason.
- It makes too many assumptions, for instance: how did the doctor know about the newly booked visit? What is the patient doing while the doctor does their part?
- If abused, we could end up with a mess of different roles being affected, so the delivery of value to the end user would be unclear.
So try to stick to a single user behaviour (using the first person) along with generic statements that don’t require changing hats.
But who exactly am I?
When trying to align each Scenario with a single user, you’ll find out soon that segmenting your users is far from straightforward. It is rather a science itself. As a Product Owner you’ll be for sure better versed than me in this kind of stuff, but let me point out how writing Gherkin features will actually unveil already existing loopholes in your segmentation.
First, creating new user groups will no longer be for free. Changing Given I am a doctor to Given I am a neurologist will automatically spawn a torrent of questions from your team: What is the difference? How do we check the specialisation? Is this really needed? QA’s need to know how to impersonate that new user, Developer’s need to actually implement access control policies; so you will be forced to define what each new segment means. Precision, disambiguation, establishing the correct boundaries between users will become mandatory.
Finally, please, no cheating. Protect yourself and your team against the old trick for disguising technical tasks as User Stories: “As a developer I want the database to…”. That defeats completely the purpose of user-centric approaches which should clearly separate what creates value for end users from what is only technically supporting that value stream.
Look at it the other way round: if you are unable to express a task to be done as a Gherkin feature without violating the basic rules, congratulations! You have spotted a supporting technical task that doesn’t contribute directly to the value stream towards the user. Does this mean that the task should not be done? No way! Developing software involves a lot of work like this. However you’ll want to clearly differentiate both types of items and make informed decisions about what should be prioritised. Oh, and of course don’t even try to specify technical tasks using Gherkin, it will not work.
Controlled Granularity
Any Scenario can be defined with different degrees of granularity. Take the following example steps.
This could be summarised in a single step.
Which one is better? As a Software Engineer, I was looking forward to saying: it depends. You will have to choose the best option depending on the context, however you can follow a few rules.
- Prefer the shorter and simpler option that keeps enough meaning to explain the action.
- Never omit steps that are not completely obvious.
- Complementary steps can be strongly summarised, while the ones in the focus of the feature should be more verbose.
- Do not tie yourself to details that can change frequently, such as specific wordings.
- Always check with your team, they may need further details for clarifying tests and implementation.
Complexity Heuristics
One additional value you get for free when using Gherkin is the chance to use it as a measure of the complexity of your features.
Having a few scenarios attached to each feature in order to describe the possible flows and corner cases is completely right, but sometimes you will notice how you are forced to keep adding more and more scenarios in order to fully specify the expected behaviours. At other times you could spot how difficult it is to describe the behaviour without breaking any rules or conventions.
That is a clear symptom of a feature that has become too complex and could be simplified in order to keep the involved cognitive load in tolerable levels. Maybe there are too many exceptions and you can homogenise the use-cases, or maybe it could be divided into sequential sub-features, or it is just a matter of better defining your user profiles… By writing Gherkin features you will be able to early detect risky approaches that could end up into long development cycles, friction with other parts of the system and so on. And you will get all of these insights during the first design phase, when adding corrections is still cheap and safe.
Conclusion
Well crafted Gherkin features are an awesome way of specifying the behaviour of your system with a good balance between simplicity and depth. They allow you to provide much more details than a User Story and they are much more clear and expressive than an assorted bunch of descriptive sentences.
For the Product Owners & Managers it can be tricky at first getting used to the methodology, and the vast majority of resources available online are targeting Developers and Quality Assurance Engineers; however, after beating that initial barrier, the benefits in terms of communication with your team are huge.
If you are lucky, you will already have some engineers in your team using Gherkin for more technical purposes, take advantage of that and let them introduce you to the basics of the language. Ask them to rewrite your previous specifications as Gherkin features to get a better idea on how you could write them the next time.
After some practice, you will be happy to replace your previous feature descriptions with Gherkin features. Ask your team for feedback and use the tips above to detect common issues early.
This is all about improving the way you and your team communicate with each other, so remember to review the methodology periodically to check that everyone is comfortable and don’t hesitate to change whatever needs to be changed.
Disclaimer About Gherkin Syntax
This post doesn’t cover all the possibilities Gherkin offers, consider it as a mere introduction. If you want to dive deeper into the language visit the Syntax Reference by Cucumber to discover Scenario Outline, Background and several other handy features.
Also take into account that Gherkin is a live framework and it evolves over time. In late versions of the language Scenario is called Example, the concept of Rule was introduced to support Example Mapping, among other changes. I have stuck to the old-school –but still absolutely valid– syntax to keep this simple and because some implementations of Gherkin do not support the newest features, so some Engineers don’t know them and/or cannot translate them into working test suites.
