Gherkin Testing: A Detailed Guide on Writing Gherkin Tests

Gherkin vs Cucumber vs BDD: Understanding the Ecosystem

First, a note on the name. A gherkin is a small pickled cucumber, and that is not a coincidence: the language is called Gherkin because it feeds Cucumber, and the compiled test cases it produces are genuinely called Pickles. The naming is a running joke that the maintainers have committed to entirely. If you arrived here looking for the vegetable, this is the wrong page, though you now know the food came first.

The joke aside, these three words get used interchangeably and they are not interchangeable at all. They sit at different levels, and mixing them up is the most common source of confusion for teams adopting BDD.

• BDD (Behavior-Driven Development) is the methodology. It is a way of working in which product, developers, and testers agree on how the software should behave, in shared language, before it is built. You can practise BDD with no tooling at all, on a whiteboard.
• Gherkin is the language. It is a plain-text DSL (domain-specific language) with a small vocabulary (Given, When, Then, And, But) used to write those agreed behaviors down in .feature files. It executes nothing by itself. It is a specification format.
• Cucumber is the tool. It reads your .feature files, matches each Gherkin step to a step definition you wrote in code, and runs it. It is the runner that turns the specification into an executable test.

The one-line version: BDD is why, Gherkin is what you write, and Cucumber is what runs it.

The last row is worth dwelling on, because it is where the confusion usually pays off. Cucumber is not the only runner that understands Gherkin. SpecFlow does it for .NET, Behave does it for Python, and Cucumber itself has JVM and JavaScript implementations. Gherkin is a language with several interpreters, which is exactly why treating "Gherkin" and "Cucumber" as synonyms causes problems: your .feature files are portable across ecosystems in a way your step definitions are not.

This also answers a question teams ask early: adopting Gherkin does not commit you to Cucumber, and adopting Cucumber does not mean you are doing BDD. Plenty of teams write Gherkin, run it with Cucumber, and never have the conversation that BDD is actually about, which is how you end up with the syntax and none of the benefit.

What Is Gherkin?

Gherkin is a plain-text language used to describe software behaviors in a way that’s both human-readable and structured enough for automated testing tools. It’s most commonly associated with frameworks like Cucumber for Behavior-Driven Development.

The main idea is to bridge communication between technical and non-technical team members. Instead of writing complex test scripts, you write simple scenarios that outline what the system should do in specific situations. Java teams practice JBehave testing using the same Given-When-Then structure, with step definitions written directly in Java.

Syntax and Structure of Gherkin

A Gherkin file (usually ending in .feature) is organized into features, scenarios, and steps.

• Feature: Describes the functionality under test.
• Scenario: Represents a concrete example or test case for that feature.
• Steps: Written in plain language with specific keywords that define behavior.

Example:

Feature: User login
  Scenario: Successful login with valid credentials
    Given the user is on the login page
    When the user enters valid credentials
    Then the user should be redirected to the dashboard

Keywords

Gherkin uses specific keywords to define the role of each line. These keywords can be localized into different languages.

• Feature: High-level description of what is being tested.
• Scenario: A single example or test case.
• Given: Sets up initial context or preconditions.
• When: Describes an action or event.
• Then: States the expected outcome or result.
• And / But: Used for step continuation to improve readability.
• Background: Defines steps common to all scenarios in a feature.
• Scenario Outline: Used for parameterized scenarios with different data sets.
• Examples: Provides the data for a scenario outline.

Scenario Outline and Examples

For repetitive scenarios with different inputs, you use Scenario Outline and Examples.

Scenario Outline: Login attempts
  Given that the user is on the login page
  When the user enters "<username>" and "<password>"
  Then the system displays "<message>"

  Examples:
    | username | password | message            |
    | alice    | pass123  | Welcome, alice!    |
    | bob      | wrong    | Invalid credentials|

Comments

Use # at the start of a line for comments. They are ignored during execution.

# This is a comment about the scenario

Formatting and Indentation

Indentation is optional but recommended for readability. Consistent spacing makes large feature files easier to scan.

A common approach is to indent steps under their corresponding Scenario or Background so the structure is clear at a glance. For example, keeping all Given, When, and Then statements aligned under a scenario title helps distinguish them from higher-level keywords like Feature or Scenario Outline.

Core Gherkin Keywords and Their Applications

In Gherkin, the language used to write BDD scenarios, keywords structure the specification so that it is easy to read, consistent, and executable by automation testing tools like Cucumber.

Here are the core Gherkin keywords and how they are applied:

Feature

• Purpose: Introduces the high-level functionality being described.
• Usage: Placed at the top of a .feature file to summarize the intent or scope.

Example:

Feature: User login
  Users should be able to log in with valid credentials

Scenario

• Purpose: Defines a single concrete example or test case of the feature.
• Usage: Follows the Feature section, describing a specific behavior through steps.

Example:

Scenario: Successful login with valid credentials

Given

• Purpose: Sets the initial context or preconditions before an action occurs.
• Usage: Often describes the starting state of the system or data.

Example:

Given the user is on the login page

When

• Purpose: Specifies the action or event performed by the user or system.
• Usage: Describes the trigger for the behavior being tested.

Example:

When the user enters valid credentials

Then

• Purpose: Outlines the expected outcome or result.
• Usage: Verifies that the system behaves as intended after the action.

Example:

Then the user should see the dashboard

And / But

• Purpose: Adds additional conditions or steps without repeating Given, When, or Then.
• Usage: Improves readability by chaining related steps.

Example:

And the welcome message is displayed
But the user does not see admin options

Background

• Purpose: Defines common preconditions for all scenarios in a feature.
• Usage: Reduces repetition by setting up shared Given steps.

Example:

Background:
Given the user is logged in

Scenario Outline

• Purpose: Allows parameterized scenarios for multiple data sets.
• Usage: Works with the Examples keyword to run the same scenario with varied inputs.

Example:

Scenario Outline: Login with multiple user roles
Given the user is on the login page
When the user logs in with <username> and <password>
Then the <role> dashboard is displayed

Examples:
| username | password | role   |
| alice    | pass123  | admin  |
| bob      | pass456  | member |

Examples

• Purpose: Supplies the data table for Scenario Outlines.
• Usage: Each row runs the scenario once with those values.

Advanced Gherkin Constructs

Beyond the core keywords, Gherkin has a few advanced constructs that help you make scenarios more expressive, reusable, and maintainable when working on larger test suites.

Here are the main ones and how they are used.

Tags

• Purpose: Categorize or group features and scenarios for filtering in test execution.
• Usage: Placed on the line above a Feature or Scenario. Can be used to run only certain tests (e.g., @smoke, @regression).

Example:

@smoke @login
Scenario: Successful login with valid credentials
Given the user is on the login page
When the user enters valid credentials
Then the user should see the dashboard

Doc Strings

• Purpose: Allow multi-line text to be passed as input to a step without breaking formatting.
• Usage: Enclosed in triple quotes """. Often used for JSON, XML, or plain text bodies.

Example:

When I send the following payload:
"""
{
  "username": "alice",
  "password": "pass123"
}
"""

Data Tables

• Purpose: Pass structured data to a step in a readable way.
• Usage: Each row represents related values, like a spreadsheet. Used for inputs, configuration, or expected results.

Example:

Given the following users exist:
| name  | role   | active |
| Alice | admin  | true   |
| Bob   | member | false  |

Rule

• Purpose: Group related scenarios within a feature and state a business rule they cover.
• Usage: Improves organization and clarifies intent in long feature files.

Example:

Rule: Only active members can log in
Scenario: Active user logs in successfully
Scenario: Inactive user is denied access

Background with Multiple Contexts

• Purpose: Combine Background with Rules to create more localized shared steps.
• Usage: Each Rule can have its own Background to avoid unrelated steps in other scenarios.

Parameterized Steps (Step Definitions)

• Purpose: Write flexible steps that accept variables.
• Usage: The Gherkin step contains placeholders like "([^"]*)" or <value>, depending on the BDD tool.

Example:

When the user logs in with username "alice" and password "pass123"

Conjunctions in Nonlinear Ways

• Purpose: Mix And and But in Given, When, and Then blocks to describe complex behavior.
• Usage: Allows chaining without repeating main keywords, but keep readability in mind.

Hooks Integration (Tool-Specific)

• Purpose: Although not Gherkin syntax itself, hooks in Cucumber tie into Gherkin scenarios to run setup or teardown code before/after scenarios, features, or tagged groups.
• Usage: Triggered via tags or lifecycle events.

How Gherkin Works Under the Hood: AST and Pickles

You can write Gherkin for years without knowing this, but it explains several behaviors that otherwise look arbitrary, particularly around Scenario Outlines. A .feature file is not handed to the test runner as text. It goes through a small compilation pipeline first.

Step 1: The parser builds an AST

The Gherkin parser reads your file and produces an Abstract Syntax Tree (AST), a structured object representing exactly what you wrote: the Feature, its Background, each Scenario, every step, its keyword, any data tables, and the line numbers they came from. This stage is purely structural. It captures your document faithfully, including the parts that are not directly executable, such as descriptions and comments.

This is also where syntax errors surface. A misindented Examples table or an unrecognised keyword fails here, before any test attempts to run, which is why those errors point at a line number rather than at your step definitions.

Step 2: The compiler produces Pickles

The AST is then compiled into Pickles, and yes, the name is another link in the Cucumber and Gherkin joke. A Pickle is one clean, executable test case: flattened, with the Background steps already merged in, and stripped of everything the runner does not need.

The detail that actually matters day to day is what happens to a Scenario Outline. In the AST it is a single scenario with an Examples table attached. In the compiler it is expanded, so a Scenario Outline with five rows becomes five separate Pickles, each with the placeholders already substituted.

That is why your test report shows five results rather than one, why a single failing row fails independently of the other four, and why the runner can execute those rows in parallel. By the time anything runs, the Outline no longer exists: there are only concrete test cases.

The separation also explains a piece of architecture. Because Pickles are a plain, language-neutral representation, any runner can consume them. That is precisely how one language serves Cucumber, SpecFlow, and Behave: the parser and compiler are shared, and only the step-definition binding differs per ecosystem.

Localization: Gherkin speaks over 70 languages

Because the parser works from a keyword table rather than hardcoded English, Gherkin has built-in localization (i18n) support for more than 70 languages. Add a language header at the top of the file and write the keywords in your own:

# language: fr
Fonctionnalité: Connexion utilisateur

  Scénario: Connexion réussie
    Soit un utilisateur enregistré
    Quand il saisit des identifiants valides
    Alors il accède à son tableau de bord

This is not a novelty. The entire premise of BDD is that the specification is readable by the business, and that premise collapses if the business language is not English and the specification is. The step definitions stay in code as usual; only the human-facing layer changes.

How to Perform Gherkin Testing With Selenium?

Let’s look at the simple Gherkin test written using Selenium and Cucumber that validates the login functionality of TestMu AI eCommerce Playground.

Here is the Gherkin feature file:

Feature: User Login

  Scenario: Login with valid credentials
    Given the user is on the login page
    When the user enters valid credentials
    And clicks on the login button
    Then the user should be logged in successfully

Below is the test script for the step definitions written using Selenium Cucumber:

package steps;

import io.cucumber.java.en.*;
import org.openqa.selenium.*;
import org.openqa.selenium.remote.RemoteWebDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import java.net.MalformedURLException;
import java.net.URL;
import java.time.Duration;

public class LoginSteps {
    WebDriver driver;

    @Given("the user is on the login page")
    public void the_user_is_on_the_login_page() throws MalformedURLException {
        ChromeOptions options = new ChromeOptions();
        driver = new RemoteWebDriver(new URL("http://localhost:4444/wd/hub"), options);
        driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(10));
        driver.get("https://ecommerce-playground.lambdatest.io/index.php?route=account/login");
    }

    @When("the user enters valid credentials")
    public void the_user_enters_valid_credentials() {
        driver.findElement(By.id("input-email")).sendKeys("testuser@example.com");
        driver.findElement(By.id("input-password")).sendKeys("Password123");
    }

    @When("clicks on the login button")
    public void clicks_on_the_login_button() {
        driver.findElement(By.cssSelector("input[value='Login']")).click();
    }

    @Then("the user should be logged in successfully")
    public void the_user_should_be_logged_in_successfully() {
        String heading = driver.findElement(By.cssSelector("h2")).getText();
        if (!heading.contains("My Account")) {
            throw new AssertionError("Login failed. Expected My Account page.");
        }
        driver.quit();
    }
}

Code Walkthrough:

• Setup RemoteWebDriver: Initializes a remote Chrome browser session by connecting to a Selenium Grid hub running locally at http://localhost:4444/wd/hub with basic ChromeOptions.
• Navigate and Wait: Opens the login page URL and sets an implicit wait of 10 seconds to allow elements time to appear before throwing exceptions.
• Perform Login Actions: Enters predefined valid email and password into the login form fields and clicks the login button to submit.
• Verify and Cleanup: Checks if the landing page contains the expected “My Account” heading to confirm successful login, then closes the browser session by quitting the driver.

Here is how each step in the Gherkin feature file is implemented in the Selenium script during Cucumber testing:

• Given the User is on the Login Page: It opens a remote browser session via Selenium Grid and navigates to the login page URL, setting up the test’s starting point.
• When the User Enters Valid Credentials: It simulates the user typing their email and password into the login form fields.
• When the User Enters Valid Credentials: It simulates the user typing their email and password into the login form fields.
• When the User Enters Valid Credentials: It simulates the user typing their email and password into the login form fields.
• When Clicks on the Login Button: The code performs the action of clicking the login button to submit the form.
• Then the User Should be Logged in Successfully: It verifies that the page shows the “My Account” heading, confirming the login succeeded, and then closes the browser.

For more information, check this guide on Selenium testing using Gherkin.

How to Perform Gherkin Testing With TestMu AI Online Selenium Grid?

Cloud testing platforms such as TestMu AI provides an online Selenium Grid that lets you run Gherkin-based BDD tests at scale across 3000+ real browsers and devices.

With TestMu AI, you can perform Selenium test automation using Cucumber, helping teams validate user stories in plain English while ensuring cross-browser compatibility. This reduces hassles of setting up test infrastructure and accelerates feedback in Agile workflows.

To perform Gherkin testing on TestMu AI, you only need to point your WebDriver to TestMu AI remote grid and configure the automation capabilities. You can generate capabilities from the TestMu AI Automation Capabilities Generator.

ChromeOptions browserOptions = new ChromeOptions();
browserOptions.setPlatformName("Windows 10");
browserOptions.setBrowserVersion("dev");
HashMap<String, Object> ltOptions = new HashMap<String, Object>();
ltOptions.put("username", "Your LambdaTest Username");
ltOptions.put("accessKey", "Your LambdaTest Access Key");
ltOptions.put("project", "Gherkin Testing With Selenium");
ltOptions.put("w3c", true);
ltOptions.put("plugin", "java-testNG");
browserOptions.setCapability("LT:Options", ltOptions);

Then, replace your LT_USERNAME and LT_ACCESS_KEY with actual values (or set them as environment variables).

Your .feature files and Gherkin scenarios remain unchanged, since TestMu AI only affects the execution environment, not the test logic.

To get started, refer to this guide on Selenium Cucumber testing on TestMu AI.

Advantages and Limitations of Gherkin Testing

Gherkin is often sold as an unqualified good, and teams that adopt it on that basis are the ones who abandon it eighteen months later. It has a real payoff and a real cost, and the cost is not obvious on day one.

Advantages

• It bridges the business and technical gap: This is the main event. A product owner can read, and more importantly correct, a Gherkin scenario without knowing any code. Ambiguity gets caught in the conversation rather than in a defect three sprints later.
• Tests double as living documentation: Ordinary documentation drifts because nothing forces it to stay true. A .feature file that has gone stale fails in CI, so the specification and the behavior are kept in sync by the build rather than by discipline.
• It forces clarity before code: Writing Given, When, Then requires knowing the precondition, the trigger, and the expected outcome. Teams routinely discover during that exercise that nobody had actually agreed what the feature does.
• Reusable steps compound: A well-written step such as "Given I am logged in as an admin" is reused across dozens of scenarios, so the marginal cost of the next scenario keeps falling.
• It is portable across ecosystems: The same .feature file runs under Cucumber, SpecFlow, or Behave, so the specification outlives a change of stack.

Limitations

• The maintenance overhead is real: Every scenario needs a step definition behind it, so you maintain two layers instead of one. A UI change can mean editing the feature file, the step definition, and the page object. Teams consistently underestimate this.
• Step definition duplication creeps in: "Given I am logged in", "Given the user is logged in", and "Given a logged-in user" are three steps doing one job, because nobody could find the existing one. Without deliberate curation a step library becomes a swamp, and this is the single most common way Gherkin suites rot.
• It is the wrong tool for unit testing: Writing Given, When, Then around a function that adds two numbers is pure ceremony. The plain-language layer exists so non-technical people can read it, and no product owner is reading your unit tests. Use unittest, JUnit, or pytest there.
• It is slower to write than plain code: An engineer testing something themselves is faster writing the test directly. The translation layer only pays for itself if somebody non-technical actually reads the output.
• The benefit evaporates without the collaboration: This is the fatal one. If developers write the feature files alone and no product person ever reads them, you have taken on all the maintenance cost of BDD and none of the alignment benefit. That is the most common way Gherkin fails, and it is a process failure rather than a tooling one.

The honest summary: Gherkin is worth it where a non-technical stakeholder genuinely engages with the scenarios, and where the behavior is complex enough that misunderstanding it is expensive. For everything below that line, particularly unit tests and developer-only suites, it is overhead wearing the costume of rigour.

Integrating Gherkin with CI/CD and Test Management Systems

A .feature file that only runs when someone remembers to run it is documentation, not a test. The living documentation claim only holds if the build enforces it, which means wiring Gherkin into your pipeline.

Running Gherkin in CI

Mechanically this is simple, because Cucumber and its siblings are command-line runners like any other. The pipeline checks out the code, installs dependencies, and runs the suite. Here is a GitHub Actions workflow:

name: BDD Tests

on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  cucumber:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '17'

      # run only the scenarios tagged @smoke on every PR
      - name: Run Gherkin scenarios
        run: mvn test -Dcucumber.filter.tags="@smoke"

      # keep the report even when the suite fails
      - name: Publish report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: cucumber-report
          path: target/cucumber-reports/

The same shape applies to Jenkins or GitLab CI: a stage that runs the runner and archives the report. Two details matter more than the platform. Use tags to split the suite, so @smoke runs on every pull request while the full regression runs nightly, because a BDD suite that adds fifteen minutes to every PR gets disabled. And publish the report with if: always(), since the report you most need is the one from the run that failed.

Syncing results to a Test Management System

CI proves the scenarios pass. A Test Management System (TMS) answers a different question: what is our coverage, which requirement does this scenario verify, and what is the trend across releases? Tools such as TestQuality and Testomat.io exist for this, and Gherkin suits them unusually well because a .feature file is already a structured, human-readable test case.

The integration works in both directions, which is the part worth understanding. The TMS imports your .feature files as test cases, so the scenarios developers maintain in Git are the same ones QA leads and stakeholders see. Your CI run then posts results back, so each execution updates the corresponding case automatically instead of someone marking it by hand.

That loop is what makes living documentation more than a slogan. The specification lives in version control where it is reviewed, the pipeline proves it is still true on every commit, and the TMS makes it visible to the people who cannot read a repository. Take away any one of the three and Gherkin reverts to being a verbose way to write tests.

Best Practices for Writing Effective Gherkin Scenarios

Common Challenges in Gherkin Testing and Solutions

Here are the common challenges teams face with Gherkin testing, along with practical solutions to address them.

• Overly Technical Language: Scenarios end up filled with implementation details (CSS selectors, database IDs, API endpoints) that non-technical stakeholders cannot follow.

  Solution: Use domain language that reflects business processes. Agree on a shared vocabulary with stakeholders and use it consistently across all scenarios.

• Scenarios Becoming Too Long or Complex: Some scenarios try to cover multiple paths, edge cases, and actions in one script, making them hard to maintain.

  Solution: Break them into smaller, focused scenarios. One scenario should test one behavior. Use Scenario Outline for variations instead of cramming everything into one.

• Background Sections Misused: Background steps become bloated with too much setup, leading to confusion about what’s actually relevant.

Solution: Keep backgrounds minimal and only for truly shared, stable setup steps. Any scenario-specific setup should remain in that scenario.

• Fragile Steps Tied to UI Details: Tests fail frequently because they reference specific UI elements that change often.

  Solution: Write steps at a higher level of abstraction, describing actions in business terms. Let automation code handle the translation to UI interactions.

• Duplicate or Inconsistent Steps: Different team members write similar steps in slightly different ways, creating redundancy.

  Solution: Maintain a shared step library and review new steps for reusability before adding them. This keeps the step set small and easier to maintain.

• Ambiguity in Expected Outcomes: “Then the user should see the order” is vague. Does it mean in a table, in a confirmation message, or both?

  Solution: Be precise about the observable result while keeping the business perspective. For example, “Then the order appears in the pending orders list.”

• Over-Reliance on Gherkin for All Testing: Teams try to capture every single Gherkin test case, including low-level checks, which bloats the suite.

  Solution: Use Gherkin for high-value, business-facing behaviors. Keep unit and integration tests in code where they belong.

• Flaky Tests from Environment or Data Issues: Scenarios fail intermittently because of unstable test environments or inconsistent data states.

  Solution: Ensure test data is reset between runs and use stable, dedicated environments for acceptance testing.

• Lack of Maintenance Over Time: As the application evolves, scenarios become outdated and no longer match the real business process.

  Solution: Schedule regular scenario reviews. Treat Gherkin scripts as living documentation, not write-once artifacts.

Conclusion

Gherkin provides a clear and structured way to describe software behavior in plain language while keeping scenarios directly tied to automated tests. By understanding its syntax, keywords, and advanced constructs, teams can write feature files that are both readable and executable. When combined with Selenium, Gherkin becomes a powerful bridge between business requirements and technical implementation, ensuring test coverage aligns with real-world use cases.

Following best practices helps maintain consistency and scalability, while awareness of common challenges prepares teams to resolve issues before they become blockers. In the end, effective use of Gherkin testing fosters better collaboration, improves test automation efficiency, and enhances overall software quality.

Citations

• Gherkin: https://cucumber.io/docs/gherkin/