Mastering Cucumber: A Step-by-Step Guide to Setting up Gherkin E2E tests

Most test suites describe what the code does. Gherkin BDD describes what the user expects. Changing who reads your tests and who writes them also changes how fast the team agrees on what is finished. If you are weighing whether to put Gherkin BDD into your team’s workflow, the article below shows how Gherkin and BDD fit together, with examples, tools, and best practices for setting up a BDD testing framework.

What is Gherkin in BDD?

Gherkin BDD combines two things. Behavior-Driven Development (BDD) is a collaboration practice for defining software behavior in plain language. Gherkin is the structured syntax used to write those behaviors as executable test scenarios. Together, they let QA, developers, and business stakeholders read the same test and agree on what it means.

Gherkin BDD is the language layer that turns conversations about behavior into something a test runner can execute. BDD was introduced by Dan North in 2003 as a response to teams struggling with Test-Driven Development. According to Wikipedia, BDD is an agile software development method centered around collaboration between business and IT professionals who have a stake in finding a solution for a complex problem. Gherkin translates that collaboration in your test suite.

A scenario in the Gherkin language BDD teams write looks like this:

That single block captures a requirement, runs as a test case, and serves as living documentation. When the test runs, it executes real code through step definitions mapped to each line. When a stakeholder reads it, they see a plain English description of the feature.

For a detailed syntax overview, see our full guide on what is Gherkin.

BDD vs Gherkin vs Cucumber: What’s the Difference?

These three terms get mixed up constantly. They are related, but they do different jobs. When teams compare BDD vs Gherkin, the confusion usually happens because they choose between them, while the two complement each other.

You practice BDD as a team, you write the behavior in Gherkin, and you execute it with Cucumber (or another runner like SpecFlow, Behat, or Behave). A team can technically do BDD without Gherkin by using conversations and examples in any format. A team can also write Gherkin without using Cucumber by choosing a different runner. In real-world projects, the three usually appear together.

Why teams adopt BDD and Gherkin in 2026

Capgemini’s World Quality Report highlighted BDD and TDD competencies as in-demand skills for quality engineers operating in agile teams. The most recent edition shifted emphasis toward generative AI proficiency, but the core need for behavior-level testing has not gone away. Teams face four problems that BDD and Gherkin address directly.

1. The communication problem: QA writes tests. Product writes requirements. Developers write code. Three artifacts describing the same feature drift apart with every sprint. BDD testing Gherkin scenarios use the specification of desired behavior as a shared language for the project team. When the requirement, the test case, and the documentation live in the same Gherkin file, the drift stops.
2. The maintenance problem: Gherkin scenarios survive UI redesigns because they describe behavior rather than implementation. The step “When I click the login button” still works after a redesign as long as a login button still exists somewhere. The step definition underneath changes. The scenario does not.
3. The onboarding problem: A new QA hire reading a Selenium test in pure Java needs to know the language, the framework, the page objects, and the application. A new hire reading a BDD/Gherkin scenario only needs to know what the application does. They can contribute to scenario review on day one, even before writing a single step definition.
4. The AI integration problem: In 2026, AI tools generate test scenarios from requirements, user stories, and Figma mockups. AI integration accelerates test generation when combined with modern Gherkin BDD tools. The BDD Gherkin format works well as input for LLMs, both for generating new scenarios and for parsing existing ones into executable code. Teams without a BDD layer do this translation by hand.

BDD advantages and disadvantages

Here are some advantages of using behavior-driven development (BDD) tests:

1. Improved communication: BDD tests are written in a natural language syntax called Gherkin, which makes them easy for non-technical stakeholders to understand. This can improve communication between developers and non-technical team members and ensure that everyone is on the same page about the desired behavior of the application.
2. Increased collaboration: BDD tests encourage collaboration between developers, testers, and business analysts, as everyone can contribute to the development of the tests. This can lead to a more holistic approach to testing and a better understanding of the business requirements.
3. More focused testing: BDD tests are designed to focus on the behavior of the application, rather than the implementation details. This can help ensure that the application is tested from the perspective of the end user and that the most important behaviors are covered.

Here are some disadvantages of using BDD tests:

1. Requires a learning curve: BDD tests use a new syntax (Gherkin) that may require a learning curve for those unfamiliar with it. This can be a barrier to adoption, especially for teams with limited time or resources.
2. Can be time-consuming: Writing BDD tests requires more upfront planning and collaboration than traditional testing approaches. This can be time-consuming and may not be practical for all projects.
3. May not be suitable for all projects: BDD tests are best suited for projects with well-defined business requirements and a clear understanding of the desired behavior of the application. If these conditions are not met, BDD tests may not be the most effective testing approach.
4. Step definitions often become complex and hard to manage: Without a reusable step library, the same action is written in many different ways, creating a major extra cost when the test suite grows.

Cucumber BDD Gherkin Setup for E2E or Unit Testing

In this tutorial, we will go over how to set up a cucumber testing framework for end-to-end (E2E) or unit testing. This is a practical guide to the official Cucumber BDD Gherkin documentation. Here is a quick overview of the steps:

1. 1. 1. Install Cucumber
      2. Create a project directory
      3. Initialize the project
      4. Write your feature files
      5. Write your step definitions
      6. Run your tests

By following these steps, you will have a basic cucumber testing framework set up for E2E or unit testing. You can then continue to add more feature files and step definitions as needed to test different aspects of your application.

1. Install Cucumber: To use Cucumber, you will need to install it first. You can do this using a package manager like npm (for JavaScript) or gem (for Ruby).

   # npm 
   npm install cucumber 
   
   # gem 
   gem install cucumber

2. Create a project directory: Create a new directory for your project and navigate to it in your terminal.
3. Initialize the project: Initialize the project by running the following command:

   cucumber --init
   

   This will create the following directory structure:

   .
   ├── features
   │   ├── step_definitions
   │   └── support
   └── cucumber.yml
   

   The features directory is where you will store your cucumber feature files. The step_definitions directory is where you will store the implementation for your step definitions. The support directory is where you can store any additional support code for your tests. The cucumber.yml file is used to configure cucumber.

4. Write your feature files: Feature files are written in Gherkin, a natural language syntax for describing software behavior. Each feature file should describe a single feature or behavior of your application. Here is one of the simplest Gherkin BDD examples, a feature file for a login feature:

   Feature: Login
     As a user
     I want to be able to log in to the application
     So that I can access my account information
   
     Scenario: Successful login
       Given I am on the login page
       When I enter my username and password
       And I click the login button
       Then I should be taken to the dashboard page
   

5. Write your step definitions: Step definitions are the implementation for the steps in your feature files. They are written in a programming language like JavaScript or Ruby. Here is an example step definition file for the login feature:

   Given("I am on the login page", () => {
     // Navigate to the login page
   });
   
   When("I enter my username and password", () => {
     // Enter the username and password
   });
   
   When("I click the login button", () => {
     // Click the login button
   });
   
   Then("I should be taken to the dashboard page", () => {
     // Verify that the user is taken to the dashboard page
   });
   

6. Run your tests: To run your tests, use the following command:

   cucumber
   

   This will run all the feature files in the features directory. You can also specify a specific feature file or directory to run by passing it as an argument:

   cucumber features/login.feature
   

That’s it. You now have a basic cucumber testing framework set up for E2E or unit testing. You can continue to add more feature files and step definitions as needed to test different aspects of your application. For directory structure beyond this, reporting setup, CI integration, and much more, see our Cucumber testing tutorial.

BDD Usage Tips and Tricks

By following these tips, you can avoid problems with BDD testing Gherkin-based scenarios and ensure your tests effectively validate the behavior of your application. For deeper guidance on the test case side, see our guide on writing BDD test cases with examples and templates.

1. Clearly define the behavior of the application: Before writing any BDD tests, it is important to have a clear understanding of the desired behavior of the application. This will help ensure that the tests are focused on the most important behaviors and will reduce the risk of writing tests that are not relevant to the business requirements.
2. Collaborate with all stakeholders: BDD tests are designed to be written by a cross-functional team, including developers, testers, and business analysts. Make sure to involve all relevant stakeholders in the test-writing process to ensure that the tests accurately reflect the business requirements.
3. Use a consistent syntax: BDD tests are written in a natural language syntax called Gherkin. Make sure to use a consistent syntax across all tests to ensure that they are easy to read and understand.
4. Keep the tests focused: BDD tests should focus on a single behavior or feature of the application. Avoid writing tests that cover multiple behaviors or features, as this can make them more difficult to understand and maintain.
5. Use clear and descriptive names: Use clear and descriptive names for your feature files, scenarios, and step definitions to make them easy to understand and maintain.
6. Regularly review and update your tests: As the application evolves, it is important to regularly review and update your BDD tests to ensure that they are still relevant and accurately reflect the desired behavior of the application.

Good BDD example

Some of the key characteristics of the good examples include:

1. Focus on a single behavior or feature: Each scenario focuses on a single behavior or feature of the application, which makes the test easier to understand and maintain.
2. Clear steps and verification points: The scenarios include clear steps and verification points to ensure that the behavior of the application is being tested effectively.
3. Use of descriptive and clear names: The feature files, scenarios, and step definitions have descriptive and clear names, which makes the test easy to understand and maintain.

Let’s look at one of the cleanest BDD Gherkin examples, a well-formed test case. The next test covers three different behaviors of the shopping cart feature: adding an item to the cart, removing an item from the cart, and emptying the cart. It also includes multiple steps and verification points for each behavior, which makes the test more comprehensive.

Feature: Shopping cart
  As a shopper
  I want to be able to add and remove items from my shopping cart
  So that I can manage the items I want to purchase

Scenario: Add an item to the shopping cart
  Given I am on the product page for a shirt
  When I click the "add to cart" button
  And I select the size and quantity of the shirt
  And I click the "add to cart" button again
  Then I should see a notification that says "Shirt added to cart"
  And the shopping cart icon should show the correct number of items

Scenario: Remove an item from the shopping cart
  Given I am on the shopping cart page
  And there is at least one item in the cart
  When I click the "remove" button for an item
  Then I should see a notification that says "Item removed from cart"
  And the shopping cart icon should show the updated number of items
  And the item should no longer be listed in the shopping cart

Scenario: Empty the shopping cart
  Given I am on the shopping cart page
  And there are multiple items in the cart
  When I click the "empty cart" button
  Then I should see a notification that says "Shopping cart emptied"
  And the shopping cart icon should show 0 items
  And the shopping cart should be empty

BDD problems and bad examples

In this exercise, you will see examples of bad BDD tests for a shopping cart feature. These examples illustrate common mistakes that can occur when writing BDD tests and can help you understand what to avoid when writing your own tests.

Some of the problems with the bad examples include:

1. Lack of focus: The scenarios are too general and do not focus on a single behavior or feature of the application.
2. Lack of steps and verification points: The scenarios do not include enough steps and verification points to test the behavior of the application.
3. Combining multiple behaviors into a single scenario: This can make the test more difficult to understand and maintain.

By comparing the bad examples to good examples of BDD tests, you can see the importance of writing clear, focused, and comprehensive tests that accurately reflect the desired behavior of the application.

The next test is bad because it combines multiple behaviors into a single scenario (“Add and remove items from the shopping cart”). This makes it difficult to understand what is being tested and makes the test more prone to errors. Additionally, the test does not include any verification points to ensure that the shopping cart is being updated correctly.

Feature: Shopping cart
  As a shopper
  I want to be able to use my shopping cart

Scenario: Add and remove items from the shopping cart
  Given I am on the shopping cart page
  When I click the "add to cart" button for an item
  And I click the "remove" button for the same item
  Then I should see a notification that says "Item added to cart"
  And I should see a notification that says "Item removed from cart"

Scenario: Checkout
  Given I am on the shopping cart page
  When I click the "checkout" button
  Then I should be taken to the checkout page

Scenario: Empty the shopping cart
  Given I am on the shopping cart page
  When I click the "empty cart" button
  Then I should see a notification that says "Shopping cart emptied"

The next test is bad because it does not clearly define the behavior of the shopping cart feature. The scenarios are too general and do not specify the steps or verification points necessary to test the feature. The test only covers a limited number of behaviors, which means that the shopping cart feature is not being tested comprehensively.

Feature: Shopping cart
  As a shopper
  I want to be able to use my shopping cart

Scenario: Add an item to the shopping cart
  Given I am on the product page
  When I click the "add to cart" button
  Then I should see a notification

Scenario: Remove an item from the shopping cart
  Given I am on the shopping cart page
  When I click the "remove" button for an item
  Then I should see a notification

Scenario: Checkout
  Given I am on the shopping cart page
  When I click the "checkout" button
  Then I should be taken to the checkout page

How AI is Changing Gherkin Scenario Writing in 2026

Manual scenario authoring is no longer the default. By 2026, most teams adopting Gherkin BDD generate their first draft of scenarios with an AI tool, then refine. Three shifts are worth tracking.

• Scenario generation from requirements. AI agents read Jira tickets and Confluence pages, then output structured Given/When/Then scenarios. They include edge cases a human reviewer often misses on a first pass. The bottleneck moves from writing scenarios to reviewing and curating them. This matters for the adoption argument. The 4-to-8-week ramp-up most teams budget for BDD assumes manual scenario authoring. With AI generation, the timeline reduces.
• Automatic conversion of existing tests to Gherkin. The biggest historical blocker to BDD adoption has been migrating hundreds or thousands of existing classical test cases into Gherkin format. AI conversion tools now handle this in bulk. Scenario titles become Scenario:. Preconditions become Given. Action steps become When and And. Expected results become Then. Testomat.io’s Transform Project to BDD agent is one example. The work that used to take a team a quarter now takes one engineer an afternoon to review.
• MCP-based authoring inside the IDE. The Model Context Protocol (MCP) lets AI tools like Cursor and Claude Code read your existing scenarios, search them, and generate new ones directly inside the developer’s editor. Testomat.io exposes an MCP server that lets external AI assistants query the test suite via Test Query Language, then generate new Gherkin scenarios from connected sources like Jira or Confluence without leaving the IDE. For developer-led BDD, this collapses the cycle of writing a ticket, writing a scenario, and writing step definitions into one continuous workflow.

For QA teams thinking about using BDD, the choice has become much simpler. The barriers that used to make BDD too difficult or expensive for most teams have stopped being a major obstacle. It is time to rethink and start writing BDD scenarios with Testomat.io.

Summary

Gherkin BDD is a powerful approach for improving communication and collaboration within a development team, since it allows non-technical stakeholders to contribute to the testing process. In this article, we covered the basics of BDD and provided examples of good and bad BDD tests. By following best practices and learning about advanced features and tools, you can continue to improve your skills in the BDD approach.

What to learn or to do next? That is your learning curve:

1. Learn about advanced Gherkin syntax: Gherkin is the natural language syntax used to write BDD tests. There are advanced features of Gherkin, such as scenario outlines and data tables, that can help you write more efficient and flexible tests.
2. Explore different BDD tools: There are several tools available for automating BDD tests, such as Cucumber, Behat, and SpecFlow. Explore different tools and choose the one that best fits your needs and workflow.
3. Understand the role of BDD in the development process: BDD is not just a testing approach, but a philosophy that can be applied throughout the development process. Understand how BDD fits into your development workflow and how it can be used to improve communication and collaboration within your team.
4. Learn about other testing approaches: In addition to BDD, there are other testing approaches that can be useful, such as test-driven development (TDD) and acceptance test-driven development (ATDD). Understanding the strengths and weaknesses of different testing approaches can help you choose the right approach for your project.
5. Keep up to date with industry trends: The field of software testing is constantly evolving. Stay up to date with industry trends and best practices by reading blogs and attending conferences and workshops. This will help you stay current and improve your skills as a senior-level engineer.