Writing Gherkins in a better way: Best Practices

Are you using Cucumber to support behavior driven development then one should definitely know a few best practices in writing gherkins script for improving productivity and clarity. Before that, let's have quick review on gherkin and cucumber.

Gherkin

Gherkin is a natural language that helps Cucumber to interpret and execute automated scripts. The syntax is used as living documentation for the project since the tests must always be updated. Because Gherkin is a natural language, it's easier for non-technical team members to understand the feature creation and testing process (especially when best practices are utilized). Gherkin is the language parser inside Cucumber.

Cucumber

Cucumber is a testing tool that supports the BDD approach using Gherkin. Cucumber is used to develop automation of the acceptance tests created.

Best Practices for Gherkin

Now that we've defined our key terms, let's cover the six best practices to write clear and effective scenarios using Gherkin. Some of these principles are self-explanatory, while others require

more detailed elaboration.

1. Tags are powerful

Tags are related words for each scenario. Each tag is prefixed with an “@” symbol and is listed before the scenario title that they apply to. We use them for reporting statistics (% of tests with a specific tag which pass/fail), and for filtering (for refining test runs). These help to reflect the current quality of the system to a stakeholder. An example is as follows:

Feature: User access @ID-00001 @REQ-004 @login Scenario: The user logs in and sees the Home page Given …

2. Any given scenario should have only one GIVEN, one WHEN, and one THEN.

3. A maximum of two AND steps are allowed.

4. Meaningful Titles

The title of a scenario should describe the purpose of the requirement and the outcome of the test in one concise line, making it easy to find a scenario in the test suite when needed just by scanning the titles.

5. If a scenario requires more than five steps, try to split it into two different scenarios.

6. Reference the end user rather than using first person (I/we) in your tests.

For example, DO NOT WRITE:

Given I´m logged in

When I create a new item...

Instead, DO WRITE:

Given the administrator is logged in

When the user creates a new item ...

7. Describe the specific flow and not every click.

For example, DO NOT WRITE:

Given the administrator opens the login page

And inserts user/password

And clicks the confirmation button

When the user opens the quick menu

And selects the option create a new item

And fills all the fields

And clicks the confirmation button

Then a successful message appears

Instead, DO WRITE:

Given the administrator is logged in

When the user creates a new item

Then a successful message appears

8. Use a reasonable number of scenario outlines

Using too many scenario outlines leads to many scenarios runs because adding a scenario is a matter of adding a new row to the Examples table. A large number of similar tests make the test run longer and clutter up the test results. Use a reasonable number of data sets and choose them carefully to verify various conditions.

9. Reuse step definitions, when possible

Scenarios can include steps that sound very similar or even the same, for instance, test scenarios for an online shop can contain a step like “Given the user is logged in …”. You benefit from reusing step definitions in the following ways:

• This makes it easy to maintain your tests when the tested app changes.

• This will simplify test automation.

10. Don’t write procedure-driven scenarios

Don’t write a scenario the same way you create UI test script. Don’t link to button names or text box captions where possible. This often hides the core idea, and if the UI changes, your tests become misleading, and you need to update them.

11. Use Backgrounds Wisely

f 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.

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

Practice makes perfect

The rules shared above should be the guiding principles for good Gherkin. So give it a try, and have fun writing good Gherkin.