What is BDD testing?
Behaviour-driven development (BDD) helps a team agree how software should behave using concrete examples. Gherkin records examples as Given, When, Then scenarios. A runner such as Cucumber matches each step to code and reports which scenarios passed, failed or stayed incomplete.
Describe one rule with concrete examples.
Our fictional delivery rule charges 500p below £50 and nothing from £50. A Scenario Outline expresses the same behaviour at 4999p, 5000p and 5001p. Cucumber expands each Examples row into its own scenario; the header names fill the angle-bracket placeholders. This keeps the exact threshold visible to developers and the person approving the rule.
Feature: Delivery charges
Delivery costs 500p below £50 and is free from £50.
Scenario Outline: The basket determines the delivery charge
Given a basket worth <basket> pence
When I calculate its delivery charge
Then the charge is <charge> pence
Examples:
| basket | charge |
| 4999 | 500 |
| 5000 | 0 |
| 5001 | 0 |Connect the Gherkin to assertions that run.
A feature file needs executable step definitions. Here, Given stores the basket value, When calls the selected function and Then compares the actual charge with the expected charge. Normal functions give each scenario access to its own Cucumber World. The world parameter selects the deliberately buggy function for the negative demonstration.
import assert from 'node:assert/strict';
import { Given, When, Then } from '@cucumber/cucumber';
import { deliveryPence } from '../src/delivery.mjs';
import { deliveryPence as buggyDeliveryPence } from '../src/delivery-buggy.mjs';
Given('a basket worth {int} pence', function (basketPence) {
this.basketPence = basketPence;
});
When('I calculate its delivery charge', function () {
const calculate = this.parameters.buggy ? buggyDeliveryPence : deliveryPence;
this.chargePence = calculate(this.basketPence);
});
Then('the charge is {int} pence', function (expectedPence) {
assert.equal(this.chargePence, expectedPence);
});The Cucumber Gherkin reference explains Scenario Outlines, and Cucumber.js step definitions document how steps connect to code.
Run both versions and inspect the actual failure.
The downloaded package pins Cucumber.js 13.3.0. Against the deliberate > boundary defect, the 5000p scenario fails: actual delivery is 500p when the requirement says 0p. The 4999p and 5001p scenarios pass. With the corrected >= function, all three scenarios pass. These were local executions of an owned educational fixture.
npm ci --ignore-scripts
npm run test:gherkin:bug
# The buggy command intentionally exits 1.
npm run test:gherkinBuggy: 3 scenarios (2 passed, 1 failed)
9 steps (8 passed, 1 failed)
AssertionError: 500 !== 0
Fixed: 3 scenarios (3 passed)
9 steps (9 passed)Keep incomplete scenarios separate from passes.
An undefined step needs an implementation. An ambiguous step needs its matching rules fixed. A pending, skipped or blocked scenario has not established the required behaviour. Inspect the scenario result and native report, rather than treating the existence of a feature file as coverage. The archive preserves JSON reports for both local runs.
Choose scenarios around a buying or access decision.
Use agreed examples for rules such as pricing, tenant boundaries or permissions. Include an exact boundary, a permitted action and an action that should be denied. Keep the scenario about behaviour that matters to a person; put selectors and implementation details in the step code. Generated properties can explore a wider input domain after the concrete examples are clear.
Run your supported scenarios within an approved plan.
Cue April can run supported installed Cucumber suites from your repository and retain scenario outcomes and native reports. Setup checks the step definitions, dependencies, environment, selected tags and qualified runner. Combine those results with API checks or browser testing for the same revision. Discuss the scope of an evaluation.
Primary documentation
Framework behaviour and configuration are documented by their maintainers.