BDD and Gherkin

Why it matters

Many costly defects in business features are not coding slips but misunderstandings: the developer read "200.00 or more" as "more than 200.00", or nobody decided what an expired code should do. BDD goes after that cost at its source. A conversation about concrete examples before any code is written exposes different readings and missing rules while they are cheap to fix, which makes it one of the earliest forms of static testing a team has.

For a tester, BDD moves the work forward: instead of finding gaps after the build, you help shape the examples that define the feature, and the same scenarios later serve as acceptance tests and regression tests. Reports speak the language of the business, so a failed scenario says which rule broke. The approach has a cost, though: a layer of step definitions to maintain. Teams that adopt the tool without the conversation pay that cost and get little back.

BDD starts with a conversation: the three amigos

Cucumber, one of the best-known BDD tools, describes day-to-day BDD as three practices repeated for every small change. Discovery: the team talks through concrete examples of the new behaviour and agrees on the details. Formulation: the agreed examples are written down as Gherkin scenarios, and the people who agreed them check that the wording still says what they meant. Automation: the scenarios are connected to code so that they run against the system, ideally before the feature is built, to guide development. In short: what the system could do, what it should do, and what it actually does.

Discovery usually happens in a short meeting per story during backlog refinement, before development starts. Many teams call it the "three amigos", because it brings together three perspectives: the business (a product owner or business analyst, who owns the problem and the rules), development (who knows how it could be built and what is technically hard) and testing (who asks what could go wrong and which examples would show it). It is the three perspectives that matter, not the head count: a designer or a second developer may join.

A popular way to run the meeting is example mapping, described in Cucumber’s BDD documentation. Coloured cards build a map on the table: a yellow card for the story, a blue card for each rule, green cards under a rule for the examples that illustrate it, and red cards for questions nobody in the room can answer. The map shows readiness at a glance: many red cards mean the story is not ready to build, and many blue cards usually mean it is too big and should be split. Here is the map for story SHOP-31, "Apply a discount code at checkout".

• Story (yellow): SHOP-31, apply a discount code at checkout.
• Rule 1 (blue): SAVE10 takes 10% off a subtotal of 200.00 SAR or more. Examples (green): 250.00 pays 225.00; 200.00 pays 180.00; 199.99 is refused and pays 199.99.
• Rule 2 (blue): an expired code is refused. Example (green): the code ended on 31 March 2027 and is applied on 1 April 2027, so the message is "This code has expired".
• Rule 3 (blue): one code per order. Example (green): SAVE10 is applied, then WELCOME5 is entered; the result waits on a red card.
• Questions (red): is the minimum checked before or after the delivery fee? Does a second code replace the first or get refused? What happens when the customer removes items and the subtotal falls below 200.00 after the code was applied?

Try it: User Story → Test Scenarios Try it: Boundary Value Generator Try it: Decision Table Generator

Gherkin syntax: the parts of a feature file

Gherkin is the plain-language format that BDD tools read. Scenarios live in text files with the .feature extension, and every line that is not blank starts with a keyword, except free-text descriptions. You already know the step keywords Given, When, Then, And and But, and the Scenario Outline with its Examples table, from the lesson on acceptance criteria. A complete feature file adds structure around them.

After the product owner answered the first red card (the minimum applies to the subtotal, before the delivery fee), the team formulated rules 1 and 2 of SHOP-31 as the file below. Each blue card became a Rule and each green card a Scenario. The Gherkin reference recommends three to five steps per scenario; with more, the example stops reading as a specification.

• Feature: one per file. Its name and the free-text description under it say what the feature is for; the description is not executed.
• Rule: groups the scenarios that illustrate one business rule, like a blue card with its green cards.
• Scenario, or its synonym Example: one concrete example of one behaviour.
• Background: Given steps shared by every scenario in the file or the rule. It runs before each scenario, after any Before hooks (Cucumber’s setup hooks, like beforeEach in other runners). Keep it short and use it only for context a reader needs to understand the scenarios.
• Data table: rows between | pipes under a step, passed to that step’s code as one argument. Doc string: multi-line text between two """ lines, for an email body or a JSON payload.
• Tags such as @smoke or @SHOP-31 label a feature, rule, scenario or examples table so that you can choose what to run. Tags are inherited: a tag on the feature applies to every scenario in it.
• Comments start with # at the beginning of a line. A # language: header on the first line switches the keywords to another spoken language.

# Story SHOP-31. Rules agreed in the example-mapping session.
@checkout
Feature: Discount codes at checkout
  A customer can enter one discount code per order.
  The discount is taken from the subtotal, before the delivery fee.

  Background:
    Given these discount codes exist:
      | code   | percent | min_subtotal | valid_until |
      | SAVE10 | 10      | 200.00       | 2027-03-31  |

  Rule: A code applies only from its minimum subtotal

    Scenario: A subtotal at the minimum gets the discount
      Given Huda has a cart with a subtotal of 200.00 SAR
      When she applies the code "SAVE10"
      Then the amount to pay before delivery is 180.00 SAR

    Scenario: A subtotal just under the minimum keeps its price
      Given Huda has a cart with a subtotal of 199.99 SAR
      When she applies the code "SAVE10"
      Then the code is refused with "Spend 200.00 SAR to use this code"
      And the amount to pay before delivery is 199.99 SAR

  Rule: An expired code is refused

    @smoke
    Scenario: A code used the day after its end date
      Given today is 1 April 2027
      And Huda has a cart with a subtotal of 250.00 SAR
      When she applies the code "SAVE10"
      Then the code is refused with "This code has expired"

Part 1:1@checkout
Part 2:2Feature: Discount codes at checkout
Part 3:3  A customer can enter one discount code per order.

Part 4:4  Background:
    Given these discount codes exist:
Part 5:5      | code   | percent | min_subtotal | valid_until |
      | SAVE10 | 10      | 200.00       | 2027-03-31  |

Part 6:6  Rule: A code applies only from its minimum subtotal

Part 7:7    Scenario: A subtotal at the minimum gets the discount
Part 8:8      Given Huda has a cart with a subtotal of 200.00 SAR
Part 9:9      When she applies the code "SAVE10"
Part 10:10      Then the amount to pay before delivery is 180.00 SAR

Try it: Acceptance Criteria Generator

Good and bad scenarios

The most common way BDD goes wrong is a feature file that is really a test script: every click, field and URL written out in Given/When/Then. This imperative style breaks with every redesign, and it buries the rule under user-interface detail. The declarative style says what happens in the language of the business and leaves the how to the automation code. Compare two versions of the same example.

Nothing in the first version says why 180.00 is the right answer: the subtotal of 200.00 SAR, the one fact the rule depends on, is hidden in the price of a book. Its last step checks a database table that no stakeholder can see, and its steps glue several actions together with "and", so they cannot be reused. The product owner can read and approve the second version, and it survives a redesign of the checkout page unchanged.

• One behaviour per scenario, with a title that states it: "A subtotal just under the minimum keeps its price", not "Discount test 2".
• Declarative steps in business words; the clicks belong in the step definitions and page objects.
• Only the data that changes the result. Every value in the scenario should matter to the rule, and nothing the rule depends on should be hidden.
• An outcome a user or stakeholder can observe in every Then, specific enough to fail: "Then I should see 180.00" does not say where.
• Independent, repeatable scenarios: each one sets up its own context and passes or fails alone, in any order and on any day. The rule 1 scenarios do not mention a date, so their automation must fix the shop’s clock, for example in a Before hook; otherwise they start failing the day SAVE10 expires.
• One phrase per idea across the project, such as "subtotal" everywhere rather than "cart total" in one file and "basket amount" in another, so that steps reuse the same definitions.

# Imperative: a test script dressed as a scenario
Scenario: Discount test 2
  Given I open "https://shop.example/login"
  And I type "huda@example.com" in "email" and click "Sign in"
  And I click "Add to cart" next to "Desert Stars"
  And I click "Checkout"
  When I type "SAVE10" in "code" and click "Apply"
  Then I should see "180.00"
  And the discounts table has a row for this order

# Declarative: one behaviour in the language of the business
Scenario: A subtotal at the minimum gets the discount
  Given Huda has a cart with a subtotal of 200.00 SAR
  When she applies the code "SAVE10"
  Then the amount to pay before delivery is 180.00 SAR

How scenarios connect to automation

A BDD runner such as Cucumber reads the feature files and, for every step, looks for a step definition: a function registered with a pattern that the step text must match. The pattern is usually a Cucumber Expression, in which parameters such as {int}, {float}, {word} and {string} capture values from the text and pass them to the function as arguments; regular expressions work as well. The keyword is not part of the match: a Given step and a Then step with the same text call the same definition, so the same text cannot mean two different things in two places.

Step definitions are glue code and should stay thin. They translate a business step into calls to the automation layer you met in the lessons on the page object model and test automation architecture: an API client prepares the data for a Given, a page object performs the When as a user would, and the Then reads the result and makes the assertion that compares the actual outcome with the expected one. Values that one step produces for a later step, such as the cart the Given created, are kept in a context object. In Cucumber for JavaScript this is the World, available as this inside a step function (so steps use function, not arrow functions, which have no this of their own) and created fresh for every scenario, which keeps scenarios independent; the API client and page objects are usually created there too, so every step can reach them.

Every step ends with a status: passed, failed, skipped (steps after a failed, pending or undefined step are not run), pending (a definition that is not finished yet), undefined (no definition matches; Cucumber prints a code snippet to start from) or ambiguous (more than one definition matches). The report lists scenarios and steps in the words of the feature file, so a failed Then step names the rule that broke. Tags select what runs, for example npx cucumber-js --tags "@smoke and not @wip" in a pipeline.

import { Given, When, Then } from "@cucumber/cucumber";
import assert from "node:assert/strict";

// Matches the Background step; the data table arrives as the last argument
Given("these discount codes exist:", async function (table) {
  for (const row of table.hashes()) await this.api.createCode(row);
});

// Matches: Given Huda has a cart with a subtotal of 200.00 SAR
Given("{word} has a cart with a subtotal of {float} SAR",
  async function (customer, subtotal) {
    this.cart = await this.api.createCart(customer, subtotal);
  });

// Matches: When she applies the code "SAVE10"
When("she applies the code {string}", async function (code) {
  await this.checkout.open(this.cart);
  await this.checkout.applyCode(code);
});

// Matches both: Then the amount to pay ... and: And the amount to pay ...
Then("the amount to pay before delivery is {float} SAR",
  async function (expected) {
    assert.equal(await this.checkout.amountBeforeDelivery(), expected);
  });

Then("the code is refused with {string}", async function (message) {
  assert.equal(await this.checkout.codeMessage(), message);
});

Try it: Regex Tester

Frequently asked questions

References

• Gherkin Reference — CucumberCucumberThe Gherkin syntax for executable specifications: Feature, Rule, Scenario, Given/When/Then steps, Background, Scenario Outline and Examples.
• Behaviour-Driven Development — CucumberCucumberBehaviour-Driven Development as three practices — discovery, formulation and automation — built on concrete examples that business and technical people agree on.
• ISTQB Certified Tester Foundation Level (CTFL) v4.0ISTQB · 2023The foundation syllabus of software testing: test levels and types, test design techniques, test management and tools.