Tutorial: Learn Behavior-Driven Development from Scratch (2026)
I have seen countless projects where developers built features that perfectly matched the technical specification but completely missed what the business actually needed. Behavior-Driven Development closes this gap by making requirements executable. It shifts the conversation from what the system should do to what behavior the user expects.
BDD uses Gherkin — a natural language syntax — to describe features and scenarios. Tools like Cucumber, SpecFlow, and Behave turn these descriptions into automated tests. In this tutorial, you will learn the BDD workflow, write feature files, implement step definitions, and integrate BDD into your development process.
The BDD Workflow and Three Amigos
BDD starts with a conversation among the Three Amigos: product owner, developer, and tester. They discuss a feature and agree on concrete examples of desired behavior. These examples become Gherkin scenarios that everyone understands the same way.
The workflow is: Discovery (discuss and agree on examples), Formulation (write Gherkin scenarios), and Automation (implement step definitions). This cycle ensures that every feature is tested before it is coded. The scenarios serve as both documentation and automated tests throughout the feature's lifecycle.
Feature: Shopping Cart
As a customer
I want to add items to my shopping cart
So that I can purchase multiple products
Scenario: Add item to empty cart
Given the cart is empty
When I add a product with price $10.00
Then the cart total should be $10.00Writing Effective Gherkin Scenarios
Gherkin scenarios follow the Given-When-Then structure. Given sets up the context, When describes the action, and Then verifies the outcome. Use And and But to chain multiple conditions. Every scenario should be independent — no scenario depends on another scenario's state.
Good scenarios are declarative, not imperative. Instead of describing UI actions, describe business intent. Write "The user logs in with valid credentials" rather than "Click the login button and enter credentials." The implementation details belong in step definitions, not in the feature file. This keeps scenarios readable by non-technical stakeholders.
Scenario: Checkout with loyalty points
Given the user is logged in
And the cart contains 3 items
And the user has 500 loyalty points
When the user proceeds to checkout
And applies loyalty points
Then the total should be reduced by $5.00
And the loyalty points balance should be 0Scenario Outlines and Examples Tables
Scenario Outlines run the same scenario with multiple data sets. Use placeholders in angle brackets and provide values in an Examples table. This eliminates duplication and makes data-driven testing explicit in the feature file itself.
The Examples table is a powerful communication tool — business stakeholders can review and extend the table without touching test code. Each row becomes a separate test case in the report. I use Scenario Outlines extensively for boundary testing and edge case validation.
Scenario Outline: Shipping cost calculation
Given the cart total is
And the shipping method is ""
When the shipping cost is calculated
Then the shipping cost should be
Examples:
| cartTotal | method | expectedCost |
| 50.00 | standard | 5.99 |
| 100.00 | standard | 0.00 |
| 50.00 | express | 12.99 | Step Definitions for Cucumber (Java)
Step definitions connect Gherkin steps to code. In Cucumber JVM, use @Given, @When, @Then annotations with a regex or Cucumber Expression. The method parameters are extracted from the expression. Step definitions should delegate to page objects or service layers.
I organize step definitions into classes by domain — OrderSteps, PaymentSteps, etc. Cucumber supports dependency injection (guice, pico, spring) for sharing state between step classes. The Scenario object provides methods for attaching files and reporting, which I use for screenshots and logs.
@Given("the cart contains {int} items")
public void theCartContainsItems(int count) {
for (int i = 0; i < count; i++) {
cart.addItem(new Item("Product " + i, 10.00));
}
}
@When("the user proceeds to checkout")
public void theUserProceedsToCheckout() {
checkoutPage = cartPage.clickCheckout();
}
@Then("the total should be {double}")
public void theTotalShouldBe(double expectedTotal) {
assertEquals(expectedTotal, checkoutPage.getTotal(), 0.01);
}BDD with SpecFlow (.NET) and Behave (Python)
SpecFlow brings BDD to the .NET ecosystem. Feature files use the same Gherkin syntax. Step definitions are methods with [Given], [When], [Then] attributes. SpecFlow integrates with NUnit, xUnit, and MSTest. The SpecFlow+ LivingDoc generates rich HTML documentation from feature files.
Behave is the Python BDD framework. Steps are Python functions with decorators. Step parameters use {placeholders} with type converters. Behave's environment.py provides hooks for setup and teardown. Choose the framework that matches your tech stack — the BDD principles are identical across all implementations.
# Behave (Python)
@given('the cart is empty')
def step_impl(context):
context.cart = ShoppingCart()
@when('I add a product with price ${price}')
def step_impl(context, price):
context.cart.add_item(Product("Book", float(price)))
@then('the cart total should be ${total}')
def step_impl(context, total):
assert context.cart.total == float(total)BDD in CI and Organizational Adoption
BDD tests run as part of the CI pipeline just like any other automated test. Feature files are stored in version control alongside the code. Cucumber reports show which scenarios passed and failed, with step-level detail. Teams review failing scenarios during standup to decide whether it is a bug or a specification change.
Adopting BDD requires a cultural shift. Start with one team, one feature, and prove the value. The product owner must actively participate in writing and reviewing scenarios. Over time, the feature files become a living documentation set that always reflects the current system behavior.
mvn test -Dcucumber.features=src/test/resources/features
# Reports generated at target/cucumber-reports/index.html
# CI pipeline step
- name: Run BDD Tests
run: mvn test -Pcucumber
- name: Publish Cucumber Report
uses: actions/upload-artifact@v4
with:
name: cucumber-report
path: target/cucumber-reportsFrequently Asked Questions
What is the difference between BDD and TDD?
TDD writes unit tests before production code at the class/method level. BDD writes behavior scenarios before any code, involving business stakeholders. They complement each other — BDD for acceptance criteria, TDD for implementation correctness.
Who writes the feature files in BDD?
The Three Amigos — product owner, developer, tester — collaborate on feature files. The product owner defines the business rules, the tester adds edge cases, and the developer ensures technical feasibility. No one person owns the feature files.
Can BDD work with APIs and backend services?
Absolutely. BDD is not limited to UI testing. Scenarios can describe API behavior, database operations, and batch processing. The step definitions call REST endpoints, execute database queries, or trigger background jobs.
How do I avoid duplication in step definitions?
Reuse steps across scenarios by writing small, focused step definitions that compose into higher-level steps. Cucumber's world object (or dependency injection) shares context. Avoid long step definition classes by grouping related steps.
Originally published on Ayodhyyya. Last updated June 1, 2026.