Cucumber Testing Guide: BDD, Gherkin & Selenium

Cucumber testing gives development and QA teams a way to describe how software should behave in language that both technical and non-technical stakeholders can understand.

Instead of expressing every test only as code, teams describe expected behavior through scenarios written in Gherkin. Those scenarios are then connected to executable code through step definitions.

That distinction matters. Cucumber is not a browser automation tool by itself. It does not open browsers, locate elements, or interact with a mobile application on its own. It works alongside automation frameworks such as Selenium for web testing and Appium for mobile testing.

This guide explains what Cucumber testing is, how Behavior-Driven Development (BDD) and Gherkin fit into it, how to create your first test, how Cucumber integrates with Selenium, and where it makes sense to use the approach.

What Is Cucumber Testing?

Cucumber testing is an approach to defining and automating software behavior using readable scenarios that can serve as both specifications and executable tests.

Cucumber is a tool that supports Behavior-Driven Development. It reads scenarios written in Gherkin and connects each scenario step to code called a step definition. When the test runs, Cucumber finds the corresponding step definition and executes it.

A basic scenario might look like this:

The feature file explains the expected behavior without specifying how the browser finds the username field or which Selenium method clicks the login button. Those implementation details stay in the automation code.

This separation is one reason the Cucumber testing framework is useful for teams that want product requirements and automated tests to stay closely connected.

Cucumber can therefore serve three related purposes:

1. Specification: It describes what the system is expected to do.
2. Automation: Step definitions connect those expectations to executable code.
3. Documentation: Feature files provide a readable record of currently implemented behavior.

Teams sometimes refer to Cucumber as a Cucumber testing tool or a Cucumber testing framework. More precisely, it is a BDD tool that typically works as one part of a broader automation stack.

Understanding BDD (Behavior-Driven Development)

Behavior-Driven Development is a collaborative software development approach centered on describing expected system behavior through concrete examples.

BDD is broader than writing automated tests.

Before automation begins, developers, testers, product owners, business analysts, and other stakeholders can discuss questions such as:

• What behavior are we trying to deliver?
• Under what conditions should it occur?
• What should the user or another system observe afterward?
• Which edge cases need to be considered?
• What would indicate that the behavior is incorrect?

Those conversations can then become examples that describe expected behavior.

A common format is:

Given a starting condition
When an action or event occurs
Then an observable result should follow

For example:

The value of BDD comes from agreeing on behavior before implementation details start dominating the conversation.

1. BDD is not just test automation

A team can use Cucumber without practicing BDD effectively.

For example, testers could write hundreds of Gherkin scenarios after development is already complete, without involving developers or product teams. The scenarios may still execute, but much of the collaborative value of BDD is lost.

A better workflow is:

Discuss behavior → define examples → implement → automate → validate

The feature file then becomes a result of the shared understanding rather than simply another format for writing test cases.

Also Read : Guide to Conducting Test Automation Using Appium & Cucumber

Gherkin Syntax Explained

Gherkin is the structured language Cucumber uses to describe executable specifications.

Although Gherkin is designed to be readable, it follows defined syntax. Its primary keywords include Feature, Rule, Scenario or Example, Given, When, Then, And, But, Background, Scenario Outline, and Examples. Gherkin also supports tags, data tables, comments, and Doc Strings.

Here are the most important elements.

1. Feature

Feature describes a capability or area of behavior being specified.

A feature file normally groups related scenarios around that capability.

2. Scenario

A Scenario describes one concrete example of expected behavior.

Cucumber also supports Example as a synonym for Scenario.

3. Given

Given establishes the starting context or precondition.

It should describe the state required before the important action occurs.

4. When

When represents an event or action.

A scenario should generally focus on the behavior triggered by this event.

5. Then

Then describes an expected, observable result.

In the underlying step definition, this is normally where an assertion verifies that the actual behavior matches the expected behavior.

6. And and But

And and But make scenarios easier to read when several conditions, actions, or outcomes are needed.

7. Background

Background can define common setup steps that apply to scenarios within the same feature.

Use Background carefully. If it becomes long, readers have to keep jumping between the background and individual scenarios to understand what is happening.

8. Scenario Outline and Examples

A Scenario Outline lets the same behavior run with multiple sets of values.

This is useful when the behavior is identical but the input data changes.

9. Tags

Tags can organize scenarios into logical test groups.

Teams may use tags such as:

This makes it possible to select relevant groups during local development or CI execution.

Also Read: A Complete Guide to Continuous Testing

Cucumber vs. Traditional Testing Frameworks

Cucumber should not automatically replace traditional testing frameworks. In many projects, the two work together.

Cucumber is frequently used with frameworks rather than instead of them.

For example:

Gherkin → Cucumber → Step definitions → Selenium → Browser

JUnit, TestNG, or another runner may also be part of the execution stack.

This makes Cucumber especially useful at the level where teams want to describe business or user behavior. A small calculation inside a Java method, by contrast, is usually clearer as a normal unit test.

Also Read : Manual Testing vs Automation Testing Guide

Setting Up Cucumber for Your Project (Step-by-Step)

The following example uses Java, Maven, Cucumber, and Selenium.

Step 1: Install the prerequisites

You will need:

• Java
• Maven
• An IDE such as IntelliJ IDEA, Eclipse, or VS Code
• A browser for local Selenium execution

Cucumber provides official JVM packages through Maven Central. When using multiple Cucumber dependencies, keep their versions aligned.

Step 2: Create a Maven project

Create a standard Maven project and organize the test code roughly like this:

Feature files belong under src/test/resources/features, while step definitions can remain under src/test/java.

Step 3: Add the required dependencies

A Java project needs Cucumber plus the libraries used for test execution and browser automation.

For example:

The versions above reflect current releases at the time of writing. Teams should verify and pin appropriate versions for their own project before implementation.

Step 4: Create a feature file

Create:

Then add your scenario:

Step 5: Add step definitions

Cucumber now needs Java methods that correspond to those Gherkin steps.

Each annotation connects a Gherkin step to executable Java code.

Step 6: Configure the Cucumber runner

With JUnit Platform, the runner can identify the feature files and step definition package.

You can then execute the suite through Maven or your IDE.

Writing Your First Cucumber Test (With Real Code)

Now let's turn the earlier login scenario into an actual Selenium test.

1. Feature file

2. Step definition

This Cucumber testing example shows how the layers work together.

The Gherkin scenario describes the expected behavior:

The Java methods define how that behavior is executed.

Selenium controls the browser.

The assertion verifies the result.

In a production project, it is usually better to move browser interactions into page objects or other reusable automation components instead of keeping every locator directly inside the step definition.

For example:

The feature remains readable, while technical implementation stays in the automation layer.

Integrating Cucumber with Selenium (and Other Frameworks)

Cucumber and Selenium solve different problems.

Cucumber answers: What behavior should we verify?

Selenium answers: How do we interact with the browser to verify it?

A typical architecture looks like this:

Keeping these responsibilities separate makes the framework easier to maintain.

1. Cucumber with Selenium

This combination is commonly used for browser-based acceptance and functional tests.

The step definition can create either a local WebDriver:

or a remote one:

The second approach is useful when tests run on remote browsers or devices.

2. Cucumber with Appium

The same BDD structure can also be used for mobile testing.

Instead of Selenium browser commands, step definitions can invoke Appium:

Feature files can therefore remain focused on user behavior while Appium handles device interaction.

3. Cucumber with API automation

Cucumber is not limited to UI testing.

A step such as:

can map to an HTTP client or API testing library instead of Selenium.

This is useful when the behavior being specified belongs at the service level.

4. Cucumber with Playwright

The same concept applies to other web automation frameworks. Step definitions can call Playwright APIs instead of Selenium APIs.

The important point is that Cucumber defines the behavior layer. The automation framework performs the underlying interactions.

Types of Cucumber Tests

Cucumber supports several kinds of automated testing when tests can be described meaningfully through behavior.

1. Acceptance testing

Acceptance tests verify that a feature behaves according to agreed requirements.

Example:

This is one of the strongest uses of BDD because the scenario can directly represent expected product behavior.

2. Functional testing

Cucumber can verify application functions such as:

• User authentication
• Search
• Checkout
• Account management
• Form submission
• Content access
• Navigation

The automation behind those scenarios may use Selenium, Appium, API libraries, or another framework.

3. Regression testing

Previously validated scenarios can be rerun after changes to confirm that important behavior still works.

Tags can help organize a dedicated regression suite:

4. Smoke testing

A small number of critical Cucumber scenarios can serve as a smoke suite.

For example:

This gives teams a quick check of essential journeys after a build or deployment.

5. End-to-end testing

In End-to-end testing cucumber is well suited to describing complete user journeys involving several components.

For example:

The underlying automation may interact with the UI, APIs, test data, and other systems.

6. API testing

BDD scenarios can describe API behavior without exposing request implementation details in the feature file.

7. Integration testing

In Integration Testing Cucumber can also describe behavior that depends on several connected services, provided the behavior is meaningful at the acceptance or system level.

When to Use Cucumber - and When Not To

Cucumber is useful, but it should not be added to every test suite automatically.

Use Cucumber when:

1. Business behavior needs to be understandable across roles

Cucumber works well when product managers, developers, testers, and other stakeholders need a shared description of expected behavior.

2. Requirements can be expressed through concrete examples

BDD becomes useful when rules can be clarified using scenarios rather than vague requirements.

3. Acceptance criteria need to stay connected to automation

Feature files can give teams a clear relationship between expected behavior and automated verification.

4. You are testing important user journeys

Login, payments, booking, search, registration, account workflows, and similar journeys can often be described clearly through Gherkin.

5. Living documentation provides real value

Maintained feature files can show what the application currently supports and what the automated suite verifies.

Avoid or reconsider Cucumber when:

1. You are writing low-level unit tests

A simple unit test is normally easier to understand directly in code.

Writing this:

usually adds little value compared with a straightforward unit test.

2. Nobody outside the automation team reads the feature files

If Gherkin is only a second syntax that testers have to maintain, the cost may outweigh the benefits.

3. Scenarios simply reproduce UI implementation details

Feature files full of steps such as "click this button," "enter text in this field," and "select this menu" become difficult to read and brittle.

4. The primary objective is load or performance testing

Cucumber can trigger other tools, but it is not a dedicated load or performance testing system.

5. The team has not agreed on how BDD will be used

Adding Gherkin without shared conventions can quickly produce duplicate steps, inconsistent terminology, and feature files that are harder to maintain than ordinary tests.

Best Practices for Writing Effective Cucumber Tests

Good Cucumber testing depends more on scenario design than on the number of scenarios written.

1. Write behavior, not browser instructions

Prefer:

instead of:

Implementation details belong in step definitions and automation code.

This keeps the feature file focused on what the system does rather than how the interface currently happens to work. Official Cucumber guidance similarly recommends describing intended behavior instead of implementation details.

2. Keep scenarios focused

Each scenario should demonstrate a clear behavior or rule.

If one scenario covers login, search, checkout, account editing, logout, and email verification, a failure becomes harder to interpret.

3. Keep scenarios reasonably short

A large number of steps often indicates that the scenario is describing procedure instead of behavior.

Cucumber's own Gherkin guidance recommends keeping examples concise, with roughly three to five steps often being enough to preserve their expressive value.

This is guidance rather than a hard limit. Some behaviors legitimately need more context.

4. Use consistent domain language

If the business calls someone a "subscriber," do not alternate randomly between:

unless those terms genuinely mean different things.

Consistent language makes scenarios easier to discuss and reuse.

5. Keep step definitions thin

A step definition should connect the Gherkin statement to reusable automation or application code.

Avoid placing hundreds of lines of browser logic inside each step definition.

Prefer:

over repeating locators, waits, and browser commands throughout the step classes.

6. Avoid duplicated step definitions

These steps communicate almost the same behavior:

Without conventions, the step library can grow unnecessarily.

Define a shared vocabulary and reuse it where the behavior is genuinely identical.

7. Keep scenarios independent

One scenario should not rely on another scenario running first.

Tests may run individually, in a different order, or in parallel. Shared scenario state can therefore lead to unpredictable failures.

8. Use Scenario Outlines for meaningful data variation

If the same behavior needs to be checked with several inputs, a Scenario Outline may be cleaner than copying the entire scenario repeatedly.

9. Use tags with a clear purpose

A useful tag strategy might include:

Avoid creating dozens of overlapping tags that nobody understands or maintains.

10. Use explicit waits in UI automation

For browser or mobile tests, asynchronous loading can cause flakiness.

Avoid arbitrary sleeps such as:

Instead, wait for the condition the test actually requires.

11. Separate test data from behavior

Large amounts of setup data can make feature files difficult to read.

Keep the scenario focused on the values that matter to the behavior being tested.

12. Review Gherkin like production code

Feature files deserve review for:

• Readability
• Duplication
• Ambiguous language
• Incorrect business rules
• Excessive implementation detail
• Missing edge cases

A scenario that executes successfully can still be a poor specification.

Common Challenges with Cucumber Testing (and Fixes)

Challenge 1: Feature files become too technical

A scenario starts looking like a Selenium script written in English.

Fix: Move selectors, clicks, page navigation, and other implementation details into step definitions, page objects, or helper classes.

Keep Gherkin at the behavior level.

Challenge 2: Duplicate steps accumulate

Large teams may create several phrases for the same behavior.

Fix: Establish shared terminology and search existing step definitions before adding new ones.

Parameterize steps where it improves clarity:

Challenge 3: Step definitions become difficult to maintain

Step classes sometimes grow into large collections of browser commands, assertions, test data, and setup logic.

Fix: Treat step definitions as an adapter between Gherkin and the automation architecture.

Move reusable logic into:

• Page objects
• API clients
• Service classes
• Test data builders
• Utility classes

Challenge 4: UI tests become flaky

Cucumber does not remove the usual causes of UI automation instability.

Tests can still fail because of:

• Unstable locators
• Timing problems
• Test data dependencies
• Network delays
• Environment problems
• Shared state

Fix: Improve the underlying Selenium or Appium implementation. Use stable selectors, condition-based waits, independent test data, and appropriate environment controls.

Challenge 5: The test suite becomes slow

End-to-end Cucumber tests can become expensive if every scenario opens a browser and executes a long workflow.

Fix: Keep Cucumber focused on behavior that benefits from BDD. Test lower-level logic through unit and integration tests.

For larger suites, use tagging, selective CI execution, and parallel execution where appropriate. Cucumber-JVM supports parallel execution through options including JUnit Platform and TestNG.

Challenge 6: Scenarios depend on each other

A checkout test might assume a previous scenario has already created a customer account.

This can make the suite fail when tests are reordered or executed in parallel.

Fix: Give every scenario the state it needs independently.

Challenge 7: Gherkin becomes documentation that nobody trusts

If feature files stop matching actual application behavior, they lose their value as specifications.

Fix: Keep important scenarios executable and run them regularly in CI. Changes to product behavior should include corresponding changes to the relevant features and automation.

Integrating Cucumber Tests with CI/CD (Jenkins, GitHub Actions)

Cucumber tests can run in CI/CD in essentially the same way they run locally.

A CI system executes the project's test command and uses the exit status to determine whether the test stage passed. Cucumber returns a non-zero exit status when scenarios fail, which allows CI systems to identify failures.

1. Running Cucumber with GitHub Actions

For a Java and Maven project, a simple workflow could look like this:

The same Maven command used locally is now executed whenever the configured CI event occurs.

GitHub's current Java and Maven guidance follows the same basic pattern: check out the project, configure Java, and run the Maven build or test command.

Teams can extend the workflow to:

• Run only selected tags
• Execute different browser configurations
• Upload test reports
• Run tests in parallel
• Trigger tests on pull requests
• Run larger regression suites on scheduled builds

2. Running Cucumber with Jenkins

A simple Jenkins pipeline can execute the Maven test suite:

From there, teams can configure reporting, environment variables, credentials, browser infrastructure, and other pipeline requirements according to their Jenkins environment.

3. Use different test groups at different pipeline stages

Running every end-to-end scenario on every commit may become expensive.

A practical structure might be:

Tags make it easier to choose the right tests for each stage.

How Cucumber Integrates with the HeadSpin Platform

Cucumber remains responsible for feature files, scenarios, and step definitions when used with HeadSpin. When those step definitions use Selenium or Appium, teams can configure the remote WebDriver or Appium URL to run the automation on HeadSpin instead of a local browser or device.

HeadSpin supports Selenium and Appium automation across real devices and browsers. During supported sessions, teams can also use HeadSpin's test and performance data to investigate how an automated journey behaved across the selected test environment.

This means teams can keep their existing Cucumber workflow while using HeadSpin as the execution and analysis environment for the Selenium or Appium layer.

Conclusion

Cucumber testing is most useful when automated testing is only part of the goal.

Its real value comes from creating a shared description of how software should behave and connecting that description to executable verification.

Gherkin makes those behaviors readable. Step definitions connect them to code. Selenium, Appium, API libraries, and other frameworks perform the underlying automation.

Used well, this structure can make acceptance criteria easier to discuss, automate, and maintain. Used without clear BDD practices, however, Cucumber can simply add another layer of syntax and maintenance.

The right question is therefore not whether every automation project should use Cucumber. It is whether describing important behavior as shared, executable examples will improve how your team builds and validates software.

FAQs

Q1. Can Cucumber be used without Selenium?

Ans: Yes. Cucumber and Selenium are independent.

Step definitions can call APIs, application code, Appium, Playwright, database utilities, service clients, or other libraries. Selenium is only required when Selenium-based browser automation forms part of the test.

Q2. Can Cucumber be used for API testing?

Ans: Yes. Gherkin scenarios can describe API behavior while step definitions send requests and validate responses through an API client or testing library.

Q3. How does Cucumber work with Selenium?

Ans: Cucumber executes a Gherkin scenario and calls its matching step definitions. Those step definitions can use Selenium WebDriver to open browsers, interact with elements, and inspect the application.

The basic flow is: