BDD Best Practices
Rules for BDD suites that stay readable for stakeholders and maintainable for developers.
How to Use This List
- Apply when writing or reviewing feature files and step definitions
- If most items are unchecked, consider staying with pytest
- Review scenario inventory quarterly for stale features
A - Scenario Quality
- Scenarios describe behavior, not implementation. "Invoice is created" not "POST /api/v2/invoices returns 201."
- 5-7 steps maximum per scenario. Longer scenarios split into multiple cases.
- Declarative Given steps. "Given a premium customer" not "Given I insert row into customers table."
- One outcome per scenario. Multiple Then assertions ok if verifying one behavior.
B - Step Definitions
- Steps are thin glue. Business logic lives in application modules.
- Reuse common steps. Auth, API client, and assertion steps shared across features.
- Typed parsers for parameters.
{amount:f}not string parsing in step body. - Fresh context per scenario. No state leaks between runs.
C - Organization
- Feature files grouped by capability.
features/billing/,features/auth/. - Tags for smoke, slow, and wip. CI runs smoke on PR; full suite on main.
- Scenario Outline for data variations only. Not for unrelated test cases.
- Background for shared setup. Avoid repeating Given in every scenario.
D - Process
- Scenarios written before implementation. Outside-in BDD, not retrofitted tests.
- Stakeholders review feature files. Living documentation stays current.
- Unit tests complement BDD. Edge cases and error paths in pytest.
- Delete scenarios for removed features. Stale scenarios erode trust.
E - CI & Maintenance
- BDD runs in CI. Smoke on PR; full acceptance on main or nightly.
- In-process testing preferred. TestClient over hitting staging APIs in CI.
- Flaky scenarios fixed or quarantined.
@wipexcluded until stable. - Reports published as artifacts. HTML/Cucumber reports for stakeholder visibility.
FAQs
How is BDD different from integration tests?
BDD scenarios are stakeholder-readable acceptance specs. Integration tests are developer-focused.
How many feature files?
One per capability area. 5-15 scenarios per file.
Should developers write Gherkin?
Dev + product together. Developers own step definitions.
How do I prevent step explosion?
Parameterize steps. Review step inventory monthly; merge duplicates.
English only?
Gherkin keywords are English. Step text can use domain language agreed by the team.
How do I handle API versioning in steps?
Hide version in step definitions. Scenarios stay version-agnostic.
Can BDD test non-functional requirements?
Limited. Performance and security better suited to dedicated tools. BDD for functional behavior.
How do I onboard new scenarios?
Copy nearest feature file. Follow naming and step reuse conventions.
What about mobile app BDD?
Use domain-language steps. UI details hidden in step definition layer (Appium, etc.).
When to retire BDD?
If stakeholders stop reading scenarios and maintenance cost exceeds value, consolidate to pytest.
Related
- BDD Decision Checklist - adoption criteria
- Gherkin Syntax - writing scenarios
- Gherkin to CI Pipeline - automation
- Testing Best Practices - pytest complement
Stack versions: This page was written for Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.