A requirement such as “customers can transfer money” leaves important questions unanswered: between which accounts, with what balance, and what happens when funds are insufficient? Gherkin makes these questions discussable through structured, concrete examples. Its scenarios are readable by business stakeholders and can be connected to automated acceptance tests. section 2.2 section 2.3.5
A feature file groups a short feature description and its scenarios. Each scenario follows a natural sequence: Given establishes preconditions, When identifies the action, and Then states the expected outcome. And and But extend the preceding kind of step to keep the wording readable. These keywords provide structure without replacing the conversation needed to agree on the behavior. section 2.3.5 section 7.0
Feature: Transferring money between accounts
In order to manage my money more efficiently
As a bank client
I want to transfer funds between my accounts whenever I need to
Scenario: Transferring money to a savings account
Given Tess has a current account with $1000
And a savings account with $2000.00
When she transfers $500 from current to savings
Then she should have $500 in her current account
And she should have $2500 in her savings account
Scenario: Transferring with insufficient funds
Given Tess has a current account with $1000
And a savings account with $2000.00
When she transfers $1500 from current to savings
Then she should receive an 'insufficient funds' error
Then she should have $1000 in her current account
And she should have $2000 in her Savings account
The transfer feature shows two outcomes for the same starting balances: a successful transfer and an insufficient-funds error. The latter also checks that neither balance changes. section 2.3.5
Choose a form that makes the business rule easy to see:
- Use separate, focused steps when combining conditions or outcomes would obscure what changed; this also makes failures easier to locate and steps easier to reuse. section 7.2.4
- Use a Scenario Outline and an Examples table when the same behavior applies to several sets of values; placeholders take their values from each row. section 2.3.5
- Use a table within a step when account balances or other test data are clearer as rows and columns. section 2.3.5
Scenario Outline: Earning interest Given Tess has a <account-type> account with $<initial-balance> And the interest rate for <account-type> accounts is <interest> When the monthly interest is calculated Then she should have earned $<earnings> And she should have $<new-balance> in her <account-type> account Examples: | initial-balance | account-type | interest | earnings | new-balance | | 10000 | Current | 1.0 | 8.33 | 10008.33 | | 10000 | Savings | 3.0 | 25 | 10025 | | 10000 | SuperSaver | 5.0 | 41.67 | 10041.67 |
The interest example runs the same scenario once per account type, substituting each row’s balances, rate, and expected earnings into the placeholders. section 2.3.5
Gherkin files are not executable merely because they have Given, When, and Then steps: they must be integrated with a BDD tool such as Cucumber or SpecFlow. Keep scenarios focused on business behavior rather than treating them as test scripts. When connected to the running application and executed with builds, they can serve as acceptance tests and living documentation; unclear scenarios instead make failures harder to diagnose and tests more costly to maintain. section 7.2 section 7.6.1
