{"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":"python","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,"search_vec":"'8.1.0':61 'activ':57 'allow':37 'autom':21 'avail':63 'bdd':3,6,31,76 'behavior':28 'behavior-driven':27 'compat':70 'configur':53 'continu':50 'current':62 'develop':30 'driven':29 'enabl':20 'ensur':69 'facilit':26 'fixtur':40 'function':46 'gherkin':17,74,79 'implement':12 'integr':33,51 'languag':18 'latest':73 'librari':55 'maintain':58 'often':65 'plugin':10,42 'project':22 'pytest':2,5,9,36,78 'pytest-bdd':1,4 'releas':66 'requir':23 'reus':38 'seamless':34 'server':52 'simplifi':49 'specif':75 'subset':14 'test':24,47,77 'unifi':43 'unit':44 'updat':67 'version':60","created_at":"2026-04-11T01:39:56.135010+00:00","updated_at":"2026-04-16T19:56:58.530555+00:00","problems":[{"fix":"Define a Python function with the appropriate `pytest_bdd` decorator (`@given`, `@when`, or `@then`) matching the exact text of the Gherkin step.\n\n```python\nfrom pytest_bdd import given\n\n@given('I have a clean database')\ndef clean_database():\n    # Implement database setup here\n    pass\n```","cause":"A step defined in the Gherkin feature file does not have a corresponding Python step implementation function (decorated with @given, @when, or @then) that matches its text.","error":"pytest_bdd.exceptions.StepDefinitionNotFoundError: Step definition is not found for step 'I have a clean database'"},{"fix":"Correct the syntax in the `.feature` file to adhere to the Gherkin specification, ensuring correct keywords, indentation, or table formatting.\n\n```gherkin\nFeature: User login\n\n  Scenario: Successful login\n    Given I am on the login page\n    When I enter valid credentials\n    Then I should be logged in\n```","cause":"The Gherkin `.feature` file contains a syntax error or an incorrectly formatted line at the specified location, preventing the parser from understanding the file structure.","error":"gherkin.parser.ParserError: Parse error at /path/to/feature_file.feature:3: Expected one of: #EOF, #TableRow, #DocString, #Step, #Tag, #Comment, #Empty, #Background, #Scenario, #ScenarioOutline, #Rule. Got 'Invalid Line'"},{"fix":"Ensure the referenced fixture is correctly defined using `@pytest.fixture` and is available in a scope accessible to the test (e.g., in the test file itself or in a `conftest.py` file in a parent directory).\n\n```python\n# In conftest.py or your test file\nimport pytest\n\n@pytest.fixture\ndef my_fixture():\n    return \"some_value\"\n\n# In your steps file, use the fixture as an argument\nfrom pytest_bdd import given\n\n@given('I use a fixture')\ndef use_the_fixture(my_fixture):\n    print(f\"Using: {my_fixture}\")\n```","cause":"A pytest fixture referenced by a `pytest-bdd` step or scenario is either not defined, not imported, or not discoverable by pytest in the test file or a `conftest.py`.","error":"_pytest.fixtures.FixtureLookupError: Unknown fixture 'my_fixture' (scenario: 'My Scenario')"},{"fix":"Install the `pytest-bdd` package using pip: `pip install pytest-bdd`","cause":"The `pytest-bdd` library has not been installed in the current Python environment or the active environment is not the one where it was installed.","error":"ModuleNotFoundError: No module named 'pytest_bdd'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"8.1.0","cli_name":"pytest","cli_version":"pytest 9.0.3","type":"library","homepage":"https://pytest-bdd.readthedocs.io/","github":"https://github.com/pytest-dev/pytest-bdd","docs":"https://pytest-bdd.readthedocs.io/","changelog":null,"pypi":"https://pypi.org/project/pytest-bdd/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}