What Is Cucumber? BDD Testing Explained

Cucumber is an open-source tool for behavior-driven development (BDD). It runs executable specifications written in plain language, so the same document describes a feature, gets read by non-technical stakeholders, and runs as an automated test. Cucumber is widely used to align business and engineering on what an application should do.

Definition: What Is Cucumber?#

Cucumber lets you write tests in Gherkin, a structured plain-language syntax built around Given, When, and Then steps. Each Gherkin step is connected to code through a step definition, so a sentence a product manager can read also drives a real test.

A key point that trips people up: Cucumber is not a browser automation tool. It does not click buttons or load pages on its own. It is the BDD layer that organizes specifications and runs them; the actual browser work is done by a driver like Playwright or Selenium that you call from your step definitions.

Key Characteristics#

• Plain-language specs: Tests read as Given/When/Then sentences, not code
• Living documentation: One file is both the spec and the test
• Language support: Works with JavaScript, Java, Ruby, and more
• Driver-agnostic: Pairs with Playwright, Selenium, or any automation library
• Collaboration-first: Built so non-developers can read and shape behavior

How Cucumber Works#

Cucumber splits a test into two layers: the feature file and the step definitions.

1. Feature Files (Gherkin)#

A .feature file describes behavior in business language:

Feature: Login
  Scenario: Successful login
    Given I am on the login page
    When I sign in with valid credentials
    Then I see my dashboard

Feature: Login
  Scenario: Successful login
    Given I am on the login page
    When I sign in with valid credentials
    Then I see my dashboard

2. Step Definitions#

Each step maps to a function that does the work and asserts the outcome:

import { Given, When, Then, expect } from "@cucumber/cucumber";

Given("I am on the login page", async function () {
  await this.page.goto("/login");
});

When("I sign in with valid credentials", async function () {
  await this.page.getByTestId("email").fill(process.env.TEST_EMAIL ?? "");
  await this.page.getByTestId("password").fill(process.env.TEST_PASSWORD ?? "");
  await this.page.getByTestId("submit").click();
});

Then("I see my dashboard", async function () {
  await expect(this.page).toHaveURL("/dashboard");
});

import { Given, When, Then, expect } from "@cucumber/cucumber";

Given("I am on the login page", async function () {
  await this.page.goto("/login");
});

When("I sign in with valid credentials", async function () {
  await this.page.getByTestId("email").fill(process.env.TEST_EMAIL ?? "");
  await this.page.getByTestId("password").fill(process.env.TEST_PASSWORD ?? "");
  await this.page.getByTestId("submit").click();
});

Then("I see my dashboard", async function () {
  await expect(this.page).toHaveURL("/dashboard");
});

The browser actions above come from a driver (Playwright here), not from Cucumber itself.

When to Use Cucumber#

Cucumber earns its keep when the spec needs an audience beyond developers:

1. Cross-Functional Collaboration#

Product, QA (quality assurance), and engineering agree on behavior in language everyone reads. The Gherkin file becomes the shared contract.

2. Acceptance Testing#

Validating that a feature meets agreed requirements. The scenarios map directly to acceptance criteria.

3. Living Documentation#

Teams that want specs to stay current use Cucumber so the documentation is the test; if behavior changes, the failing scenario forces an update.

Limitations to Know#

BDD has a cost, and Cucumber is not the right fit for every team:

• Two layers to maintain: Every Gherkin step needs a step definition, which is extra indirection
• Overhead without an audience: If only developers read the tests, the plain-language layer adds work without payoff
• Discipline required: Vague or duplicated steps make the suite hard to maintain
• Not faster: Cucumber sits on top of your driver, so it does not speed up the underlying tests

If a developer-only team wants direct browser tests, a framework like Cypress or Playwright without the BDD layer is often simpler.

Cucumber vs Writing Tests Directly#

Getting Started with Cucumber#

Installation#

npm install --save-dev @cucumber/cucumber

npm install --save-dev @cucumber/cucumber

Run Your Scenarios#

npx cucumber-js

npx cucumber-js

Cucumber finds your .feature files, matches each step to a definition, and reports which scenarios pass.

Best Practices#

1. Write steps from the user's point of view. "When I sign in" reads better and lasts longer than "When I click the button with id submit".
2. Reuse steps. Keep a small, shared vocabulary of steps so scenarios stay readable and definitions do not duplicate.
3. Keep scenarios independent. Each scenario should set up its own state rather than depending on a previous one.
4. Use stable selectors in step definitions. Drive the browser with data-testid style selectors so tests survive styling and copy changes.

Conclusion#

Cucumber turns plain-language specifications into automated tests, which makes it a strong fit for teams that need product, QA, and engineering reading the same document. The trade-off is a second layer to maintain and no speed gain, so developer-only teams often skip the BDD layer.

BDD suites still have to be written and maintained as the UI changes, and the underlying browser tests break when selectors drift. ObserveOne's Autopilot generates Playwright tests from a URL and self-heals selectors when the app shifts, so your coverage survives redesigns instead of breaking on every refactor.