{"id":2719,"library":"pytest-bdd","title":"pytest-bdd","description":"Pytest-bdd is a pytest plugin that implements a subset of the Gherkin language to enable automating project requirements testing and facilitate Behavior-Driven Development (BDD). It integrates seamlessly with pytest, allowing reuse of fixtures and plugins, unifying unit and functional tests, and simplifying continuous integration server configuration. The library is actively maintained, with version 8.1.0 currently available, and often releases updates to ensure compatibility with the latest Gherkin specification.","status":"active","version":"8.1.0","language":"en","source_language":"en","source_url":"https://github.com/pytest-dev/pytest-bdd","tags":["bdd","testing","pytest","gherkin"],"install":[{"cmd":"pip install pytest-bdd","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"pytest-bdd is a plugin for the pytest testing framework.","package":"pytest","optional":false}],"imports":[{"symbol":"scenario","correct":"from pytest_bdd import scenario"},{"symbol":"given","correct":"from pytest_bdd import given"},{"symbol":"when","correct":"from pytest_bdd import when"},{"symbol":"then","correct":"from pytest_bdd import then"},{"note":"While parsers were previously accessible via `pytest_bdd.steps`, the direct import from `pytest_bdd` is the current and recommended path.","wrong":"from pytest_bdd.steps import parsers","symbol":"parsers","correct":"from pytest_bdd import parsers"}],"quickstart":{"code":"import pytest\nfrom pytest_bdd import scenario, given, when, then\n\n# --- content of features/example.feature ---\n# Feature: Basic feature\n#   Scenario: Run a simple scenario\n#     Given I have a value of 10\n#     When I add 5 to it\n#     Then the value should be 15\n\n# --- content of tests/test_example.py ---\n\n@scenario('../features/example.feature', 'Run a simple scenario')\ndef test_simple_scenario():\n    pass\n\n@pytest.fixture\ndef initial_value():\n    return {}\n\n@given('I have a value of 10')\ndef i_have_value_10(initial_value):\n    initial_value['value'] = 10\n\n@when('I add 5 to it')\ndef i_add_5(initial_value):\n    initial_value['value'] += 5\n\n@then('the value should be 15')\ndef the_value_should_be_15(initial_value):\n    assert initial_value['value'] == 15\n\n# To run this example:\n# 1. Create a directory structure: project_root/features/ and project_root/tests/\n# 2. Save the .feature content into features/example.feature\n# 3. Save the Python code into tests/test_example.py\n# 4. Run `pytest` from `project_root`","lang":"python","description":"This quickstart demonstrates a basic pytest-bdd setup. It involves creating a Gherkin `.feature` file to define a scenario and a corresponding Python test file (`test_example.py`) where the scenario is linked using `@scenario` and step definitions (`@given`, `@when`, `@then`) are implemented. Pytest fixtures are used for sharing state between steps."},"warnings":[{"fix":"Explicitly define fixtures or use the `target_fixture` parameter in step decorators if you need to expose a step's return value as a fixture. For example, `@given(parsers.parse('I have a {fruit}'), target_fixture='my_fruit')`.","message":"Step arguments are no longer fixtures since version 6.0.0 and 8.0.0. In previous versions, parsed step arguments automatically became pytest fixtures. This behavior was removed to align with official Gherkin specifications and avoid conflicts with actual fixtures.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Migrate feature-level and vertical examples into `Scenario Outline` blocks using `Examples` tables. Ensure all variable templates `<variable>` are used within `Scenario Outline` steps only.","message":"Feature-level and vertical example tables are no longer supported since version 6.0.0 and 8.0.0. Pytest-bdd now strictly adheres to Gherkin's specification, which only supports example tables within `Scenario Outline` sections.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Ensure that steps containing variable templates like `<variable>` are exclusively used within `Scenario Outline` scenarios. For regular `Scenario` steps that need parameters, use `pytest_bdd.parsers.parse` or other explicit parsers.","message":"The behavior of parsing variable templates (`<variable>`) in steps changed significantly in versions 6.0.0 and 8.0.0. Previously, these were parsed in both `Scenario` and `Scenario Outline`. Now, they are only parsed for `Scenario Outline` steps.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Configure the `bdd_features_base_dir` key in your `pytest.ini` (or `tox.ini`, `setup.cfg`) to specify the base directory for feature files, relative to the pytest root directory. Alternatively, provide `features_base_dir` directly to the `@scenario` decorator for per-scenario overrides.","message":"By default, `pytest-bdd` uses the current module's path to find feature files. This can lead to issues if feature files are organized in a different directory structure.","severity":"gotcha","affected_versions":"all"},{"fix":"Add all Gherkin tags to the `markers` section in `pytest.ini`. E.g., `[pytest]\nmarkers = my_tag: description of my_tag`. Ensure tags use alphanumeric characters and underscores, starting with a non-number.","message":"When using tags in `.feature` files, if `pytest` is run with the `--strict-markers` option, these tags must also be explicitly declared in the `markers` setting of your `pytest.ini` file. Tag names should also be Python-compatible variable names.","severity":"gotcha","affected_versions":"all (especially with pytest >= 5.0 and --strict-markers)"},{"fix":"Update `.feature` files to comply with the official Gherkin specification. Ensure multiline steps are enclosed in triple quotes, every feature file begins with `Feature:`, and tags like `@tag one` are changed to `@tag_one` or separate tags.","message":"Since version 8.0.0, `pytest-bdd` uses the official Gherkin parser. This introduced several strictness changes: multiline steps must use triple-quotes, all feature files must start with `Feature:`, and tags can no longer contain spaces.","severity":"breaking","affected_versions":">=8.0.0"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}