Do you use Cucumber to support behavior-driven development? Check out these best practices for improving productivity and clarity.

What Will I Learn?

Today, we're going to present six simple and straightforward best practices to help you utilize Gherkin effectively. Before we do so, we'll review key concepts and explain why teams find Cucumber beneficial. 

Behavior-Driven Development

Cucumber's claim to fame is that it supports Behavior-Driven Development, or BDD. BDD is a collaborative process used by software teams  to mitigate the gaps between business and technical perspectives related to software requirements.

Following the Agile approach, the customer tells the business analyst/project owner about the needed feature. The business analyst then schedules a meeting with the developers and testers to discuss the feature to avoid misunderstandings. This meeting is called the Three Amigos Session.

How it Works

The business analyst/project owner defines the scope of the project and creates user stories for the feature;

The tester provides considerations related to edge test scenarios; and

The developer predicts possible technical challenges.

At the end of the meeting, the three collaboratively define the acceptance criteria examples (called scenarios), which are written using 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 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. Any given scenario should have only one GIVEN, one WHEN, and one THEN.

2. A maximum of two AND steps are allowed.

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

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

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

6. Do not use technical terms in the Gherkin steps. Always try to keep absolute values in a configuration file.

For example, DO NOT WRITE:

Given the user is in the login page

When the user fills “user123” in the username field

And fills “Password123” in the password field

And clicks on button “OK”

Then the main page is displayed 

Instead, DO WRITE:

Given “administrator-user” goes to login screen

When the user logs in

Then the main page is displayed


If you follow these six best practices, you'll be well on your way to enabling better collaboration and clarity for everyone involved in the new feature design, which in turn will result in time savings for your team and a better experience for your end users.



Giridhar Rajkumar, Cucumber with Java - Test Automation University

Gherkin Reference


Leonardo Jorente

Leonardo Jorente is a QA Test Engineer at Avenue Code. He brings eight years of experience in the field and is passionate about learning and sharing knowledge. In his free time, he enjoys nature walks, drawing, and spending time with family and friends.

Value Your Time: 11 Tips for More Efficient Meetings


Tips for Organizing Documentation in Agile Projects


Synergistic Digital Transformation: Potentiating Results with Systems Thinking


How A/B Testing Can Transform Your Business