Picking a BDD runner - decision table and first-run commands

Deep reference for cucumber-testing. Runner choice in BDD is almost entirely determined by your language and build system, because step definitions are written in that language. Read the repo, match a row, stop deliberating.

The .NET trap: do not start on SpecFlow

SpecFlow was the standard .NET BDD runner for a decade, so most tutorials still point at it. It is dead: Tricentis states "SpecFlow has been retired" (shiftsync.tricentis.com (opens in new window)), specflow.org redirects there, and it "reached its end-of-life on December 31, 2024" with the GitHub projects deleted as of 1 January (reqnroll.net (opens in new window)). The packages still install only because nuget.org will not delete existing ones (reqnroll.net (opens in new window)) - exactly how newcomers land on an unsupported dependency. Use Reqnroll, the maintained successor: "a reboot of the SpecFlow project" (reqnroll.net (opens in new window)); migrating is mostly package and namespace renames, not a rewrite (reqnroll.net (opens in new window)). See reqnroll-testing (and its references/specflow-legacy.md for not-yet-migrated projects).

First runnable path per runner

Run the block that matches your row. Success looks the same everywhere: the runner reports undefined steps and prints copy-pasteable step-definition snippets. That is the correct first result, not a failure.

# Node (Cucumber-JS), per cucumber.io/docs/installation/javascript
npm install --save-dev @cucumber/cucumber
mkdir -p features/step_definitions && npx cucumber-js

# Python (Behave), per behave.readthedocs.io/en/latest/install
pip install behave
mkdir -p features/steps && behave

# Java (Cucumber-JVM), the maintained Maven starter project
git clone https://github.com/cucumber/cucumber-jvm-starter-maven-java
cd cucumber-jvm-starter-maven-java && ./mvnw test

# Ruby (Cucumber-Ruby), per cucumber.io/docs/installation/ruby
gem install cucumber
cucumber --init && cucumber

# .NET (Reqnroll), per docs.reqnroll.net/latest/installation/setup-project.html
dotnet new install Reqnroll.Templates.DotNet
dotnet new reqnroll-project -t nunit -f net8.0 -o CheckoutSpecs
cd CheckoutSpecs && dotnet test

Command sources: npm install --save-dev @cucumber/cucumber (install/javascript (opens in new window)) with npx cucumber-js (cucumber-js CLI (opens in new window)); pip install behave (behave install (opens in new window)); ./mvnw test on the starter repo, which runs features through Cucumber's JUnit Platform Engine (jvm starter (opens in new window)); gem install cucumber and cucumber --init (install/ruby (opens in new window)); the Reqnroll template install and -t / -f flags per docs.reqnroll.net setup (opens in new window).

When BDD is not worth it

BDD's payoff is the shared understanding produced by the conversation. The Cucumber project is explicit that documentation and automated tests "are produced by a BDD team, you can think of them as nice side-effects. The real goal is valuable, working software, and the fastest way to get there is through conversations between the people who are involved in imagining and delivering that software." (cucumber.io/docs/bdd (opens in new window))

Read that as a cost test (practitioner judgment, not a documented rule): if no non-technical stakeholder ever reads, reviews or writes a feature file, the translation layer is pure overhead. Write the tests directly in JUnit, pytest, NUnit or Mocha instead. Usually skip BDD for: internal libraries, SDKs, CLIs and infrastructure with no business-facing behaviour; teams where only engineers have ever opened a feature file; retrofitting Gherkin onto an existing UI automation suite; and spike work whose specification is not stable enough to formulate.

The honest signal that BDD is working: someone who does not write code has edited a .feature file in the last month.

Cucumber step definitions and reporting

Full step-definition and JUnit XML reporting examples for cucumber-testing (opens in new window) (Steps 5 and 7). The Gherkin feature they bind to is in Step 4 of the SKILL.md.

Step definitions - JVM (Java)

import io.cucumber.java.en.*;

public class CheckoutSteps {

    private Cart cart;
    private CheckoutPage page;

    @Given("a logged-in user with email confirmed")
    public void a_logged_in_user() {
        TestUser user = TestUsers.loggedInWithEmailConfirmed();
        page = new CheckoutPage().loginAs(user);
    }

    @Given("the cart contains {int} of {string} at ${double}")
    public void the_cart_contains(int qty, String sku, double price) {
        cart = new Cart();
        cart.addItem(new Item(sku, qty, price));
        page.setCart(cart);
    }

    @When("I enter {string} in the promo input")
    public void i_enter(String code) {
        page.enterPromo(code);
    }

    @When("I click {string}")
    public void i_click(String label) {
        page.click(label);
    }

    @Then("the subtotal updates to ${double}")
    public void the_subtotal_updates(double expected) {
        assertEquals(expected, page.getSubtotal(), 0.01);
    }
}

Step definitions - JS

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

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

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);
});

Reporting

Cucumber outputs to multiple formats; JUnit XML is the CI-canonical one.

JVM (in cucumber.properties):

cucumber.plugin=pretty,html:target/cucumber-report.html,junit:target/cucumber-report.xml

JS (CLI):

npx cucumber-js features/ \
  --format html:reports/cucumber.html \
  --format junit:reports/cucumber.xml

The JUnit XML feeds junit-xml-analysis (in the qa-test-reporting plugin).