cucumber-testing

Overview

Per cucumber-install:

"Cucumber is available for most mainstream programming languages."

Cucumber implementations split into tiers (cucumber-install):

• Official: Hosted under the main Cucumber organization (JavaScript, Java, Ruby, Android, Kotlin, Scala, C++)
• Semi-official: Developed elsewhere but use Cucumber components (PHP's Behat, Python's Behave, .NET's Reqnroll)

This skill covers the three most-used official implementations: Cucumber-JVM (Java + Kotlin), Cucumber-JS (Node), and Cucumber-Ruby. For Python, see behave-testing. For .NET, see reqnroll-testing.

When to use

• The team uses BDD with Gherkin features.
• Cross-stakeholder collaboration is the value (Gherkin scenarios read by non-engineers).
• Acceptance criteria authored as Gherkin scenarios per gherkin-from-stories.

If only engineers will read the tests, BDD's collaboration value is wasted - plain xUnit-style tests are simpler. Not sure which runner fits the repo, or whether BDD is worth adopting at all? See references/runner-selection.md - the runner decision table, per-runner first-run commands, the SpecFlow end-of-life note, and the "when BDD is not worth it" test.

Step 1 - Install (Cucumber-JVM)

Maven:

<dependency>
  <groupId>io.cucumber</groupId>
  <artifactId>cucumber-java</artifactId>
  <version>7.20.0</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>io.cucumber</groupId>
  <artifactId>cucumber-junit-platform-engine</artifactId>
  <version>7.20.0</version>
  <scope>test</scope>
</dependency>

For Kotlin: replace cucumber-java with cucumber-kotlin.

Step 2 - Install (Cucumber-JS)

npm install --save-dev @cucumber/cucumber

Step 3 - Install (Cucumber-Ruby)

gem install cucumber
# Or in Gemfile:
group :test do
  gem 'cucumber-ruby'
end

Step 4 - Author a Feature

# features/cart.feature
Feature: Apply promo code at checkout

  Background:
    Given a logged-in user with email confirmed
    And the cart contains 1 of "BOOK-001" at $24.99

  Scenario: Apply valid promo
    When I enter "WELCOME10" in the promo input
    And I click "Apply"
    Then the subtotal updates to $22.49
    And a confirmation toast appears

  Scenario Outline: Promo validation rejects bad codes
    When I enter "<code>" in the promo input
    And I click "Apply"
    Then an error appears: "<error>"

    Examples:
      | code         | error                    |
      | EXPIRED50    | This code has expired    |
      | NOTREAL      | Code not found           |
      | "" (empty)   | Please enter a code      |

Step 5 - Write step definitions

Bind each Gherkin line to a method with a {cucumber-expression} capture. Minimal JS example:

const { Given, When, Then } = require('@cucumber/cucumber');

Given('a logged-in user with email confirmed', function() {
  this.page = new CheckoutPage(createLoggedInUser());
});

When('I enter {string} in the promo input', function(code) {
  this.page.enterPromo(code);
});

Then('the subtotal updates to ${float}', function(expected) {
  assert.equal(this.page.getSubtotal(), expected);
});

Full Java (Cucumber-JVM) and JS step definitions, plus the JUnit XML reporting config, are in references/step-definitions-and-reporting.md.

Step 6 - Run

JVM (via Maven):

mvn test
# Or specific feature:
mvn test -Dcucumber.features=features/cart.feature

JS:

npx cucumber-js features/

Ruby:

cucumber features/

Step 7 - Reporting

Cucumber outputs multiple formats; JUnit XML is the CI-canonical one and feeds junit-xml-analysis (in the qa-test-reporting plugin). The JVM (cucumber.properties) and JS (CLI) reporting config is in references/step-definitions-and-reporting.md.

Step 8 - Tags + filtering

@regression @critical
Scenario: Apply valid promo
  ...

# Run only critical tests
npx cucumber-js features/ --tags '@critical'

# Skip @wip
npx cucumber-js features/ --tags 'not @wip'

Anti-patterns

Anti-pattern	Why it fails	Fix
Imperative steps ("I click button id=#submit")	Couples to implementation; scenarios become fragile.	Declarative steps ("I submit the form").
100 unique step definitions	Drift; inconsistency.	Step library curation (see bdd-step-library-curator).
BDD without business stakeholder involvement	Defeats the point; expensive xUnit tests.	If non-engineers don't read the features, switch to plain unit tests.
Mixing Cucumber + plain JUnit assertions	Two test runners; double maintenance.	Cucumber's runner only; plain JUnit for non-BDD tests in separate suite.
Skipping Background for shared setup	Repeated Given lines clutter scenarios.	Background block (Step 4 example).

Limitations

• Step ambiguity. Two step definitions matching the same Gherkin line cause runtime errors; the framework reports ambiguous steps but only at runtime.
• Per-language quirks. Cucumber-JVM's regex syntax differs from Cucumber-JS's; copy-paste between languages doesn't work.
• Performance. BDD adds runner overhead vs plain xUnit; acceptable for <500-test suites, slow beyond.
• Step-definition discoverability. Without IDE plugin, finding the implementation behind a Gherkin line is manual grep.

References

• ci - Cucumber installation: official + semi-official + unofficial implementation tiers; recommendation to match production language.
• behave-testing - Python sibling.
• reqnroll-testing - .NET sibling.
• bdd-step-library-curator - addresses step proliferation.
• gherkin-from-stories - upstream skill that generates Gherkin from stories, AC lists, manual steps, and raw specs.
• references/runner-selection.md - runner decision table + first-run commands.