Gherkin best practices | 8 tips
Posted by Kenan Rhoton
What are the Gherkin best practices?
Over the years of working with Cucumber (and Gherkin), here at Redsauce we've come up with some guidelines that help us create better features.
We've listed the ones we find most useful and which we apply to any projects we undertake using Cucumber.
Gherkin Best Practices 1: Write declarative features
Scenarios should be written like a user would describe them.
Beware of scenarios that only describe clicking links and filling in form fields, or of steps that contain code or CSS selectors.
This is just another variant of programming, but certainly not a feature description.
Declarative features are vivid, concise and contain highly maintainable steps.
# Bad: this is just programming
Given the user is on "http://www.mypage.com/home"
When the user clicks on the first news item
Then the browser shows the news item view page
# Good: clear, readable and relatable
Given the user is on the Home page
When the user reads the news
Then the user can see the article
# Ugly: Despite being readable, it isn’t clear what we’re testing
Given the user wants to see news
Then the user sees news
Gherkin Best Practices 2: Insert a Narrative
Narratives describe in about one sentence what a feature does.
A typical example contains a role that needs the feature, the feature itself and the benefit the user obtains.
It’s important to envision why you are implementing the feature in the first place.
They also give a short overview of the feature so others get a rough understanding without needing to read the scenarios.
# Bad: What are we testing here?
Feature: Reservations
Scenario: User makes a normal reservation
# Good: Both motives and what is being tested appear clearly
Feature: Perform a reservation
As a registered user
To ensure the restaurant has a table available
The user makes a reservation
Scenario: The user successfully makes a reservation
# Ugly: This is too long, no one will ever read it
Feature: The user intends to make a reservation and does so
As a user that has an account on the site
Since they are having an event, be it a bachelor party or birthday or even just a romantic dinner for two, and they want to make sure that they will have a place available to them for this event
The user logs into the page and chooses a restaurant to his liking to make a reservation for said event
Gherkin Best Practices 3: Avoid conjunctive steps
When you encounter a Cucumber step that contains two actions conjuncted with an “and”, you should normally at least consider breaking it into two steps.
Sticking to one action per step makes your steps more modular and increases reusability.
This is not a general rule though.
There may be reasons for conjunctive steps.
However, most of the time it’s best to avoid them.
# Bad: This step contains two separate problems
Given the user is logged in with a product in their cart
# Good: Every step is a one statement about the state
Given the user is logged in
And the user has a product in their cart
# Ugly: These steps can be logically condensed
Given the user is on the site
And the user has an account
And the user logs into their account
And the user wants to buy a product
And the user adds it to their cart
Gherkin Best Practices 4: Use Backgrounds Wisely
If you use the same steps at the beginning of all scenarios of a feature, put them into the feature’s Background.
Background steps are run before each scenario.
But take care that you don’t put too many steps in there as your scenarios may become hard to understand.
# Bad: We are repeating ourselves!
As a cat lover
The user would like to enjoy pictures of cats
So they go to their gallery
Scenario: The user views pictures of cats
Given the user is logged in
When the user goes to the "Cats" gallery
Then the user can see pictures of cats
Scenario: The user likes a picture of a cat
Given the user is logged in
When the user goes to the "Cats" gallery
And the user likes a picture
Then the user can see that picture in their "Liked" gallery
# Good: We don’t repeat ourselves :)
As a cat lover
The user would like to enjoy pictures of cats
So they go to their gallery
Background:
Given the user is logged in
And the user goes to the "Cats" gallery
Scenario: The user views pictures of cats
Then the user can see pictures of cats
Scenario: The user likes a picture of a cat
When the user likes a picture
Then the user can see that picture in their "Liked" gallery
Gherkin Best Practices 5: Single-purpose scenarios
Scenarios should be written with a single use-case in mind.
This helps locate any potential errors and find exactly which cases fail.
It also helps to understand exactly what is being tested and why.
# Bad: the Scenario covers too many things
Scenario: Cart
Given the user is in the shopping page
When the user adds potatoes to the cart
Then the cart contains potatoes
When the user clears the cart
Then the cart is empty
When the user adds potatoes to the cart
And the user clicks on checkout
Then the user is asked for the payment method
# Good: one Scenario per use-case
Background:
Given the user is in the shopping page
And the user adds potatoes to the cart
Scenario: Potatoes added to cart
Then the cart contains potatoes
Scenario: Cart cleared
When the user clears the cart
Then the cart is empty
Scenario: Checkout
When the user clicks on checkout
Then the user is asked for the payment method
Gherkin Best Practices 6: Follow the State-Action-State pattern
Scenarios should declare a beginning state (Given), perform some actions (When) and make sure the expected final state is achieved (Then).
This will help ensure the scenarios are readable and useful.
# Bad: too confusing to read
Scenario: User successfully logs in
Given the user is in the login page
When the user authenticates correctly
Then the user should see the homepage
When the user clicks on his profile
Then the user should see his personal information
# Good: making the authentication step check its own success makes it more readable
Scenario: User successfully logs in
Given the user is in the login page
When the user authenticates correctly
And the user clicks on his profile
Then the user should see his personal information
Gherkin Best Practices 7: Don’t be too lengthy
A good rule of thumb is to attempt to keep Scenarios within 5 or less steps.
In some cases it may be necessary to go higher, but only very rarely should it even be considered to go above 7.
# Bad: way too long!
Scenario: User successfully registers a new account
Given the user is on the login page
When the user goes to the registration form
And the user fills in his name
And the user fills in his email address
And the user fills in a sufficient quality password
And the user selects a home country "Spain"
And the user submits the registration form
Then the user is successfully registered on the platform
# Good: conciseness is a virtue
Scenario: User successfully registers a new account
Given the user is on the login page
When the user correctly fills in the registration form
Then the user is successfully registered on the platform
Gherkin Best Practices 8: Steps
Finally, a couple considerations that should always be in mind when programming the steps themselves:
Make self-contained steps: Each step should validate the initial state before the action and the final state after it. This results in more meaningful messages, as otherwise a problem in a steps action could result in a following step failing instead.
Reuse functions: In Cucumber you can call steps within other steps. Don’t do this. Instead create a function that may be called from multiple steps. You should try to reuse functions as often as possible. This will improve the maintainability of your app: If you need to change a certain behavior, you just need to change a single function.