BDD & Gherkin Highlights Summary

Every highlight bullet from the 8 pages in this section, gathered on one page and grouped by the page it came from.

The BDD Living Documentation Model

A Gherkin scenario is a specification that fails loudly the moment it stops matching reality
Feature file, step definition, and application service are three separable layers - each with a different audience
Behavior-Driven Development is a coordination protocol between roles, not a testing framework choice
Living documentation only stays living as long as scenarios describe behavior, not implementation steps
BDD and unit testing answer different questions and are not substitutes for each other

BDD Decision Checklist

Only adopt BDD if non-technical stakeholders actively participate in scenario review
Skip BDD if scenarios duplicate pytest tests 1:1 - you'll maintain two suites for no gain
BDD pays off around 10+ acceptance scenarios; below that pytest with good names suffices
Red flag: only developers reading tests - use pytest with descriptive names instead
Red flag: flaky scenarios erode stakeholder trust and cause feature file abandonment
Red flag: step definitions becoming complex logic means you've over-engineered BDD

Gherkin Syntax

Feature files use Given-When-Then structure to describe software behavior in plain text
Background runs before every scenario to set up preconditions across all test cases
Scenario Outline with Examples parametrizes tests using data tables for multiple cases
Given preconditions, When actions, Then outcomes; And/But continue the previous step
Limit scenarios to 5-7 steps and extract repeated setup to Background for readability
Keep Scenario Outline examples focused on boundary cases to avoid maintenance burden

behave / pytest-bdd Setup

Choose pytest-bdd for pytest integration or behave for standalone Gherkin testing
Link Gherkin features to Python with scenarios() and @given/@when/@then decorators
Use parsers.parse to extract typed parameters from Gherkin step text
Isolate step state with pytest fixtures or behave context objects to prevent leaks
Set scenarios() path relative to steps file or feature collection fails silently
Match step text exactly to decorators, use parsers for flexible matching

Step Definitions

Parsers extract typed parameters like {name:d} {name:f} from Gherkin step text
Context objects hold per-scenario state shared across step definitions
Make step definitions thin glue to services, not reimplementing application logic
Make steps specific or use regex anchors to avoid ambiguous matches and errors
Shared mutable context leaks state between scenarios, use fixture scope=function
Longest matching step text applies when multiple steps could match a Gherkin line

Gherkin to Code

Start with a failing scenario to drive outside-in development of step definitions and application code
Implement step stubs first to verify scenario structure before writing application code
Extract business logic from step definitions into app modules immediately to avoid monoliths
Write scenarios for happy paths, unit tests for edge cases like boundaries and errors
Keep scenarios in domain language using business concepts instead of implementation details
Aim for 1-3 acceptance scenarios per user story to stay iterative rather than waterfall

Gherkin to CI Pipeline

Tag @smoke on scenarios for fast PR checks, full suite on main only
Unit tests run in one CI job, acceptance tests in separate jobs
Smoke BDD should complete in under 2 minutes or move scenarios elsewhere
Register pytest-bdd markers in pyproject.toml or warnings become errors
Use TestClient or test environment URLs instead of production APIs in BDD
Verify feature files collected with pytest --collect-only features/

BDD Best Practices

Describe scenario behavior, not API implementation details
Limit scenarios to maximum 5-7 steps before splitting
Reuse common steps across features for consistency
Use typed parameter parsers instead of string parsing
Write scenarios before implementation for outside-in BDD
Delete stale scenarios for removed features promptly

The BDD Living Documentation Model

A Gherkin scenario is a specification that fails loudly the moment it stops matching reality

Feature file, step definition, and application service are three separable layers - each with a different audience

Behavior-Driven Development is a coordination protocol between roles, not a testing framework choice

Living documentation only stays living as long as scenarios describe behavior, not implementation steps

BDD and unit testing answer different questions and are not substitutes for each other

BDD Decision Checklist

Only adopt BDD if non-technical stakeholders actively participate in scenario review

Skip BDD if scenarios duplicate pytest tests 1:1 - you'll maintain two suites for no gain

BDD pays off around 10+ acceptance scenarios; below that pytest with good names suffices

Red flag: only developers reading tests - use pytest with descriptive names instead

Red flag: flaky scenarios erode stakeholder trust and cause feature file abandonment

Red flag: step definitions becoming complex logic means you've over-engineered BDD

Gherkin Syntax

Feature files use Given-When-Then structure to describe software behavior in plain text

Background runs before every scenario to set up preconditions across all test cases

Scenario Outline with Examples parametrizes tests using data tables for multiple cases

Given preconditions, When actions, Then outcomes; And/But continue the previous step

Limit scenarios to 5-7 steps and extract repeated setup to Background for readability

Keep Scenario Outline examples focused on boundary cases to avoid maintenance burden

behave / pytest-bdd Setup

Choose pytest-bdd for pytest integration or behave for standalone Gherkin testing

Link Gherkin features to Python with scenarios() and @given/@when/@then decorators

Use parsers.parse to extract typed parameters from Gherkin step text

Isolate step state with pytest fixtures or behave context objects to prevent leaks

Set scenarios() path relative to steps file or feature collection fails silently

Match step text exactly to decorators, use parsers for flexible matching

Step Definitions

Parsers extract typed parameters like {name:d} {name:f} from Gherkin step text

Context objects hold per-scenario state shared across step definitions

Make step definitions thin glue to services, not reimplementing application logic

Make steps specific or use regex anchors to avoid ambiguous matches and errors

Shared mutable context leaks state between scenarios, use fixture scope=function

Longest matching step text applies when multiple steps could match a Gherkin line

Gherkin to Code

Start with a failing scenario to drive outside-in development of step definitions and application code

Implement step stubs first to verify scenario structure before writing application code

Extract business logic from step definitions into app modules immediately to avoid monoliths

Write scenarios for happy paths, unit tests for edge cases like boundaries and errors

Keep scenarios in domain language using business concepts instead of implementation details

Aim for 1-3 acceptance scenarios per user story to stay iterative rather than waterfall

Gherkin to CI Pipeline

Tag @smoke on scenarios for fast PR checks, full suite on main only

Unit tests run in one CI job, acceptance tests in separate jobs

Smoke BDD should complete in under 2 minutes or move scenarios elsewhere

Use TestClient or test environment URLs instead of production APIs in BDD

Verify feature files collected with pytest --collect-only features/

BDD Best Practices

Describe scenario behavior, not API implementation details

Limit scenarios to maximum 5-7 steps before splitting

Reuse common steps across features for consistency

Use typed parameter parsers instead of string parsing

Write scenarios before implementation for outside-in BDD

Delete stale scenarios for removed features promptly

BDD & Gherkin Highlights Summary

Buscar en la documentación

BDD & Gherkin Highlights Summary