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. @wip excluded until stable.
• Reports published as artifacts. HTML/Cucumber reports for stakeholder visibility.

FAQs

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+.