{"author":"Oleg Pidsadnyi","author_email":"oleg.pidsadnyi@gmail.com","bugtrack_url":null,"classifiers":["Development Status :: 6 - Mature","Intended Audience :: Developers","License :: OSI Approved :: MIT License","Operating System :: MacOS :: MacOS X","Operating System :: Microsoft :: Windows","Operating System :: POSIX","Programming Language :: Python :: 3","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Programming Language :: Python :: 3.9","Topic :: Software Development :: Libraries","Topic :: Software Development :: Testing","Topic :: Utilities"],"description":"Pytest-BDD: the BDD framework for pytest\n========================================\n\n.. image:: https://img.shields.io/pypi/v/pytest-bdd.svg\n :target: https://pypi.python.org/pypi/pytest-bdd\n.. image:: https://codecov.io/gh/pytest-dev/pytest-bdd/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/pytest-dev/pytest-bdd\n.. image:: https://github.com/pytest-dev/pytest-bdd/actions/workflows/main.yml/badge.svg\n :target: https://github.com/pytest-dev/pytest-bdd/actions/workflows/main.yml\n.. image:: https://readthedocs.org/projects/pytest-bdd/badge/?version=stable\n :target: https://readthedocs.org/projects/pytest-bdd/\n :alt: Documentation Status\n\npytest-bdd implements a subset of the Gherkin language to enable automating project\nrequirements testing and to facilitate behavioral driven development.\n\nUnlike many other BDD tools, it does not require a separate runner and benefits from\nthe power and flexibility of pytest. It enables unifying unit and functional\ntests, reduces the burden of continuous integration server configuration and allows the reuse of\ntest setups.\n\nPytest fixtures written for unit tests can be reused for setup and actions\nmentioned in feature steps with dependency injection. This allows a true BDD\njust-enough specification of the requirements without maintaining any context object\ncontaining the side effects of Gherkin imperative declarations.\n\n.. _behave: https://pypi.python.org/pypi/behave\n.. _pytest-splinter: https://github.com/pytest-dev/pytest-splinter\n\nInstall pytest-bdd\n------------------\n\n::\n\n pip install pytest-bdd\n\n\nExample\n-------\n\nAn example test for a blog hosting software could look like this.\nNote that pytest-splinter_ is used to get the browser fixture.\n\n.. code-block:: gherkin\n\n # content of publish_article.feature\n\n Feature: Blog\n A site where you can publish your articles.\n\n Scenario: Publishing the article\n Given I'm an author user\n And I have an article\n\n When I go to the article page\n And I press the publish button\n\n Then I should not see the error message\n And the article should be published\n\nNote that only one feature is allowed per feature file.\n\n.. code-block:: python\n\n # content of test_publish_article.py\n\n from pytest_bdd import scenario, given, when, then\n\n @scenario('publish_article.feature', 'Publishing the article')\n def test_publish():\n pass\n\n\n @given(\"I'm an author user\")\n def author_user(auth, author):\n auth['user'] = author.user\n\n\n @given(\"I have an article\", target_fixture=\"article\")\n def article(author):\n return create_test_article(author=author)\n\n\n @when(\"I go to the article page\")\n def go_to_article(article, browser):\n browser.visit(urljoin(browser.url, '/manage/articles/{0}/'.format(article.id)))\n\n\n @when(\"I press the publish button\")\n def publish_article(browser):\n browser.find_by_css('button[name=publish]').first.click()\n\n\n @then(\"I should not see the error message\")\n def no_error_message(browser):\n with pytest.raises(ElementDoesNotExist):\n browser.find_by_css('.message.error').first\n\n\n @then(\"the article should be published\")\n def article_is_published(article):\n article.refresh() # Refresh the object in the SQLAlchemy session\n assert article.is_published\n\n\nScenario decorator\n------------------\n\nFunctions decorated with the `scenario` decorator behave like a normal test function,\nand they will be executed after all scenario steps.\n\n\n.. code-block:: python\n\n from pytest_bdd import scenario, given, when, then\n\n @scenario('publish_article.feature', 'Publishing the article')\n def test_publish(browser):\n assert article.title in browser.html\n\n\n.. NOTE:: It is however encouraged to try as much as possible to have your logic only inside the Given, When, Then steps.\n\n\nStep aliases\n------------\n\nSometimes, one has to declare the same fixtures or steps with\ndifferent names for better readability. In order to use the same step\nfunction with multiple step names simply decorate it multiple times:\n\n.. code-block:: python\n\n @given(\"I have an article\")\n @given(\"there's an article\")\n def article(author, target_fixture=\"article\"):\n return create_test_article(author=author)\n\nNote that the given step aliases are independent and will be executed\nwhen mentioned.\n\nFor example if you associate your resource to some owner or not. Admin\nuser can’t be an author of the article, but articles should have a\ndefault author.\n\n.. code-block:: gherkin\n\n Feature: Resource owner\n Scenario: I'm the author\n Given I'm an author\n And I have an article\n\n\n Scenario: I'm the admin\n Given I'm the admin\n And there's an article\n\n\nUsing Asterisks in Place of Keywords\n------------------------------------\n\nTo avoid redundancy or unnecessary repetition of keywords\nsuch as \"And\" or \"But\" in Gherkin scenarios,\nyou can use an asterisk (*) as a shorthand.\nThe asterisk acts as a wildcard, allowing for the same functionality\nwithout repeating the keyword explicitly.\nIt improves readability by making the steps easier to follow,\nespecially when the specific keyword does not add value to the scenario's clarity.\n\nThe asterisk will work the same as other step keywords - Given, When, Then - it follows.\n\nFor example:\n\n.. code-block:: gherkin\n\n Feature: Resource owner\n Scenario: I'm the author\n Given I'm an author\n * I have an article\n * I have a pen\n\n\n.. code-block:: python\n\n from pytest_bdd import given\n\n @given(\"I'm an author\")\n def _():\n pass\n\n @given(\"I have an article\")\n def _():\n pass\n\n @given(\"I have a pen\")\n def _():\n pass\n\n\nIn the scenario above, the asterisk (*) replaces the And or Given keywords.\nThis allows for cleaner scenarios while still linking related steps together in the context of the scenario.\n\nThis approach is particularly useful when you have a series of steps\nthat do not require explicitly stating whether they are part of the \"Given\", \"When\", or \"Then\" context\nbut are part of the logical flow of the scenario.\n\n\nStep arguments\n--------------\n\nOften it's possible to reuse steps giving them a parameter(s).\nThis allows to have single implementation and multiple use, so less code.\nAlso opens the possibility to use same step twice in single scenario and with different arguments!\nAnd even more, there are several types of step parameter parsers at your disposal\n(idea taken from behave_ implementation):\n\n.. _pypi_parse: http://pypi.python.org/pypi/parse\n.. _pypi_parse_type: http://pypi.python.org/pypi/parse_type\n\n**string** (the default)\n This is the default and can be considered as a `null` or `exact` parser. It parses no parameters\n and matches the step name by equality of strings.\n**parse** (based on: pypi_parse_)\n Provides a simple parser that replaces regular expressions for\n step parameters with a readable syntax like ``{param:Type}``.\n The syntax is inspired by the Python builtin ``string.format()``\n function.\n Step parameters must use the named fields syntax of pypi_parse_\n in step definitions. The named fields are extracted,\n optionally type converted and then used as step function arguments.\n Supports type conversions by using type converters passed via `extra_types`\n**cfparse** (extends: pypi_parse_, based on: pypi_parse_type_)\n Provides an extended parser with \"Cardinality Field\" (CF) support.\n Automatically creates missing type converters for related cardinality\n as long as a type converter for cardinality=1 is provided.\n Supports parse expressions like:\n * ``{values:Type+}`` (cardinality=1..N, many)\n * ``{values:Type*}`` (cardinality=0..N, many0)\n * ``{value:Type?}`` (cardinality=0..1, optional)\n Supports type conversions (as above).\n**re**\n This uses full regular expressions to parse the clause text. You will\n need to use named groups \"(?P...)\" to define the variables pulled\n from the text and passed to your ``step()`` function.\n Type conversion can only be done via `converters` step decorator argument (see example below).\n\nThe default parser is `string`, so just plain one-to-one match to the keyword definition.\nParsers except `string`, as well as their optional arguments are specified like:\n\nfor `cfparse` parser\n\n.. code-block:: python\n\n from pytest_bdd import parsers\n\n @given(\n parsers.cfparse(\"there are {start:Number} cucumbers\", extra_types={\"Number\": int}),\n target_fixture=\"cucumbers\",\n )\n def given_cucumbers(start):\n return {\"start\": start, \"eat\": 0}\n\nfor `re` parser\n\n.. code-block:: python\n\n from pytest_bdd import parsers\n\n @given(\n parsers.re(r\"there are (?P\\d+) cucumbers\"),\n converters={\"start\": int},\n target_fixture=\"cucumbers\",\n )\n def given_cucumbers(start):\n return {\"start\": start, \"eat\": 0}\n\n\nExample:\n\n.. code-block:: gherkin\n\n Feature: Step arguments\n Scenario: Arguments for given, when, then\n Given there are 5 cucumbers\n\n When I eat 3 cucumbers\n And I eat 2 cucumbers\n\n Then I should have 0 cucumbers\n\n\nThe code will look like:\n\n.. code-block:: python\n\n from pytest_bdd import scenarios, given, when, then, parsers\n\n\n scenarios(\"arguments.feature\")\n\n\n @given(parsers.parse(\"there are {start:d} cucumbers\"), target_fixture=\"cucumbers\")\n def given_cucumbers(start):\n return {\"start\": start, \"eat\": 0}\n\n\n @when(parsers.parse(\"I eat {eat:d} cucumbers\"))\n def eat_cucumbers(cucumbers, eat):\n cucumbers[\"eat\"] += eat\n\n\n @then(parsers.parse(\"I should have {left:d} cucumbers\"))\n def should_have_left_cucumbers(cucumbers, left):\n assert cucumbers[\"start\"] - cucumbers[\"eat\"] == left\n\nExample code also shows possibility to pass argument converters which may be useful if you need to postprocess step\narguments after the parser.\n\nYou can implement your own step parser. It's interface is quite simple. The code can look like:\n\n.. code-block:: python\n\n import re\n from pytest_bdd import given, parsers\n\n\n class MyParser(parsers.StepParser):\n \"\"\"Custom parser.\"\"\"\n\n def __init__(self, name, **kwargs):\n \"\"\"Compile regex.\"\"\"\n super().__init__(name)\n self.regex = re.compile(re.sub(\"%(.+)%\", \"(?P<\\1>.+)\", self.name), **kwargs)\n\n def parse_arguments(self, name):\n \"\"\"Get step arguments.\n\n :return: `dict` of step arguments\n \"\"\"\n return self.regex.match(name).groupdict()\n\n def is_matching(self, name):\n \"\"\"Match given name with the step name.\"\"\"\n return bool(self.regex.match(name))\n\n\n @given(parsers.parse(\"there are %start% cucumbers\"), target_fixture=\"cucumbers\")\n def given_cucumbers(start):\n return {\"start\": start, \"eat\": 0}\n\n\nOverride fixtures via given steps\n---------------------------------\n\nDependency injection is not a panacea if you have complex structure of your test setup data. Sometimes there's a need\nsuch a given step which would imperatively change the fixture only for certain test (scenario), while for other tests\nit will stay untouched. To allow this, special parameter `target_fixture` exists in the `given` decorator:\n\n.. code-block:: python\n\n from pytest_bdd import given\n\n @pytest.fixture\n def foo():\n return \"foo\"\n\n\n @given(\"I have injecting given\", target_fixture=\"foo\")\n def injecting_given():\n return \"injected foo\"\n\n\n @then('foo should be \"injected foo\"')\n def foo_is_foo(foo):\n assert foo == 'injected foo'\n\n\n.. code-block:: gherkin\n\n Feature: Target fixture\n Scenario: Test given fixture injection\n Given I have injecting given\n Then foo should be \"injected foo\"\n\n\nIn this example, the existing fixture `foo` will be overridden by given step `I have injecting given` only for the scenario it's\nused in.\n\nSometimes it is also useful to let `when` and `then` steps provide a fixture as well.\nA common use case is when we have to assert the outcome of an HTTP request:\n\n.. code-block:: python\n\n # content of test_blog.py\n\n from pytest_bdd import scenarios, given, when, then\n\n from my_app.models import Article\n\n scenarios(\"blog.feature\")\n\n\n @given(\"there is an article\", target_fixture=\"article\")\n def there_is_an_article():\n return Article()\n\n\n @when(\"I request the deletion of the article\", target_fixture=\"request_result\")\n def there_should_be_a_new_article(article, http_client):\n return http_client.delete(f\"/articles/{article.uid}\")\n\n\n @then(\"the request should be successful\")\n def article_is_published(request_result):\n assert request_result.status_code == 200\n\n\n.. code-block:: gherkin\n\n # content of blog.feature\n\n Feature: Blog\n Scenario: Deleting the article\n Given there is an article\n\n When I request the deletion of the article\n\n Then the request should be successful\n\n\nScenarios shortcut\n------------------\n\nIf you have a relatively large set of feature files, it's boring to manually bind scenarios to the tests using the scenario decorator. Of course with the manual approach you get all the power to be able to additionally parametrize the test, give the test function a nice name, document it, etc, but in the majority of the cases you don't need that.\nInstead, you want to bind all the scenarios found in the ``features`` folder(s) recursively automatically, by using the ``scenarios`` helper.\n\n.. code-block:: python\n\n from pytest_bdd import scenarios\n\n # assume 'features' subfolder is in this file's directory\n scenarios('features')\n\nThat's all you need to do to bind all scenarios found in the ``features`` folder!\nNote that you can pass multiple paths, and those paths can be either feature files or feature folders.\n\n\n.. code-block:: python\n\n from pytest_bdd import scenarios\n\n # pass multiple paths/files\n scenarios('features', 'other_features/some.feature', 'some_other_features')\n\nBut what if you need to manually bind a certain scenario, leaving others to be automatically bound?\nJust write your scenario in a \"normal\" way, but ensure you do it **before** the call of ``scenarios`` helper.\n\n\n.. code-block:: python\n\n from pytest_bdd import scenario, scenarios\n\n @scenario('features/some.feature', 'Test something')\n def test_something():\n pass\n\n # assume 'features' subfolder is in this file's directory\n scenarios('features')\n\nIn the example above, the ``test_something`` scenario binding will be kept manual, other scenarios found in the ``features`` folder will be bound automatically.\n\n\nScenario outlines\n-----------------\n\nScenarios can be parametrized to cover multiple cases. These are called `Scenario Outlines `_ in Gherkin, and the variable templates are written using angular brackets (e.g. ````).\n\nExample:\n\n.. code-block:: gherkin\n\n # content of scenario_outlines.feature\n\n Feature: Scenario outlines\n Scenario Outline: Outlined given, when, then\n Given there are cucumbers\n When I eat cucumbers\n Then I should have cucumbers\n\n Examples:\n | start | eat | left |\n | 12 | 5 | 7 |\n\n.. code-block:: python\n\n from pytest_bdd import scenarios, given, when, then, parsers\n\n\n scenarios(\"scenario_outlines.feature\")\n\n\n @given(parsers.parse(\"there are {start:d} cucumbers\"), target_fixture=\"cucumbers\")\n def given_cucumbers(start):\n return {\"start\": start, \"eat\": 0}\n\n\n @when(parsers.parse(\"I eat {eat:d} cucumbers\"))\n def eat_cucumbers(cucumbers, eat):\n cucumbers[\"eat\"] += eat\n\n\n @then(parsers.parse(\"I should have {left:d} cucumbers\"))\n def should_have_left_cucumbers(cucumbers, left):\n assert cucumbers[\"start\"] - cucumbers[\"eat\"] == left\n\n\nExample parameters from example tables can not only be used in steps, but also embedded directly within docstrings and datatables, allowing for dynamic substitution.\nThis provides added flexibility for scenarios that require complex setups or validations.\n\nExample:\n\n.. code-block:: gherkin\n\n # content of docstring_and_datatable_with_params.feature\n\n Feature: Docstring and Datatable with example parameters\n Scenario Outline: Using parameters in docstrings and datatables\n Given the following configuration:\n \"\"\"\n username: \n password: \n \"\"\"\n When the user logs in\n Then the response should contain:\n | field | value |\n | username | |\n | logged_in | true |\n\n Examples:\n | username | password |\n | user1 | pass123 |\n | user2 | 123secure |\n\n.. code-block:: python\n\n from pytest_bdd import scenarios, given, when, then\n import json\n\n # Load scenarios from the feature file\n scenarios(\"docstring_and_datatable_with_params.feature\")\n\n\n @given(\"the following configuration:\")\n def given_user_config(docstring):\n print(docstring)\n\n\n @when(\"the user logs in\")\n def user_logs_in(logged_in):\n logged_in = True\n\n\n @then(\"the response should contain:\")\n def response_should_contain(datatable):\n assert datatable[1][1] in [\"user1\", \"user2\"]\n\n\nScenario Outlines with Multiple Example Tables\n----------------------------------------------\n\nIn `pytest-bdd`, you can use multiple example tables in a scenario outline to test\ndifferent sets of input data under various conditions.\nYou can define separate `Examples` blocks, each with its own table of data,\nand optionally tag them to differentiate between positive, negative, or any other conditions.\n\nExample:\n\n.. code-block:: gherkin\n\n # content of scenario_outline.feature\n\n Feature: Scenario outlines with multiple examples tables\n Scenario Outline: Outlined with multiple example tables\n Given there are cucumbers\n When I eat cucumbers\n Then I should have cucumbers\n\n @positive\n Examples: Positive results\n | start | eat | left |\n | 12 | 5 | 7 |\n | 5 | 4 | 1 |\n\n @negative\n Examples: Impossible negative results\n | start | eat | left |\n | 3 | 9 | -6 |\n | 1 | 4 | -3 |\n\n.. code-block:: python\n\n from pytest_bdd import scenarios, given, when, then, parsers\n\n\n scenarios(\"scenario_outline.feature\")\n\n\n @given(parsers.parse(\"there are {start:d} cucumbers\"), target_fixture=\"cucumbers\")\n def given_cucumbers(start):\n return {\"start\": start, \"eat\": 0}\n\n\n @when(parsers.parse(\"I eat {eat:d} cucumbers\"))\n def eat_cucumbers(cucumbers, eat):\n cucumbers[\"eat\"] += eat\n\n\n @then(parsers.parse(\"I should have {left:d} cucumbers\"))\n def should_have_left_cucumbers(cucumbers, left):\n assert cucumbers[\"start\"] - cucumbers[\"eat\"] == left\n\n\nWhen you filter scenarios by a tag, only the examples associated with that tag will be executed.\nThis allows you to run a specific subset of your test cases based on the tag.\nFor example, in the following scenario outline, if you filter by the @positive tag,\nonly the examples under the \"Positive results\" table will be executed, and the \"Negative results\" table will be ignored.\n\n.. code-block:: bash\n\n pytest -k \"positive\"\n\n\nHandling Empty Example Cells\n----------------------------\n\nBy default, empty cells in the example tables are interpreted as empty strings (\"\").\nHowever, there may be cases where it is more appropriate to handle them as ``None``.\nIn such scenarios, you can use a converter with the ``parsers.re`` parser to define a custom behavior for empty values.\n\nFor example, the following code demonstrates how to use a custom converter to return ``None`` when an empty cell is encountered:\n\n.. code-block:: gherkin\n\n # content of empty_example_cells.feature\n\n Feature: Handling empty example cells\n Scenario Outline: Using converters for empty cells\n Given I am starting lunch\n Then there are cucumbers\n\n Examples:\n | start |\n | |\n\n.. code-block:: python\n\n from pytest_bdd import then, parsers\n\n\n # Define a converter that returns None for empty strings\n def empty_to_none(value):\n return None if value.strip() == \"\" else value\n\n\n @given(\"I am starting lunch\")\n def _():\n pass\n\n\n @then(\n parsers.re(\"there are (?P.*?) cucumbers\"),\n converters={\"start\": empty_to_none}\n )\n def _(start):\n # Example assertion to demonstrate the conversion\n assert start is None\n\n\nHere, the `start` cell in the example table is empty.\nWhen the ``parsers.re`` parser is combined with the ``empty_to_none`` converter,\nthe empty cell will be converted to ``None`` and can be handled accordingly in the step definition.\n\n\nRules\n-----\n\nIn Gherkin, `Rules` allow you to group related scenarios or examples under a shared context.\nThis is useful when you want to define different conditions or behaviours\nfor multiple examples that follow a similar structure.\nYou can use either ``Scenario`` or ``Example`` to define individual cases, as they are aliases and function identically.\n\nAdditionally, **tags** applied to a rule will be automatically applied to all the **examples or scenarios**\nunder that rule, making it easier to organize and filter tests during execution.\n\nExample:\n\n.. code-block:: gherkin\n\n Feature: Rules and examples\n\n @feature_tag\n Rule: A rule for valid cases\n\n @rule_tag\n Example: Valid case 1\n Given I have a valid input\n When I process the input\n Then the result should be successful\n\n Rule: A rule for invalid cases\n\n Example: Invalid case\n Given I have an invalid input\n When I process the input\n Then the result should be an error\n\n\nDatatables\n----------\n\nThe ``datatable`` argument allows you to utilise data tables defined in your Gherkin scenarios\ndirectly within your test functions. This is particularly useful for scenarios that require tabular data as input,\nenabling you to manage and manipulate this data conveniently.\n\nWhen you use the ``datatable`` argument in a step definition, it will return the table as a list of lists,\nwhere each inner list represents a row from the table.\n\nFor example, the Gherkin table:\n\n.. code-block:: gherkin\n\n | name | email |\n | John | john@example.com |\n\nWill be returned by the ``datatable`` argument as:\n\n.. code-block:: python\n\n [\n [\"name\", \"email\"],\n [\"John\", \"john@example.com\"]\n ]\n\n.. NOTE:: When using the datatable argument, it is essential to ensure that the step to which it is applied\n actually has an associated data table. If the step does not have an associated data table,\n attempting to use the datatable argument will raise an error.\n Make sure that your Gherkin steps correctly reference the data table when defined.\n\nFull example:\n\n.. code-block:: gherkin\n\n Feature: Manage user accounts\n\n Scenario: Creating a new user with roles and permissions\n Given the following user details:\n | name | email | age |\n | John | john@example.com | 30 |\n | Alice | alice@example.com | 25 |\n\n When each user is assigned the following roles:\n | Admin | Full access to the system |\n | Contributor | Can add content |\n\n And the page is saved\n\n Then the user should have the following permissions:\n | permission | allowed |\n | view dashboard | true |\n | edit content | true |\n | delete content | false |\n\n.. code-block:: python\n\n from pytest_bdd import given, when, then\n\n\n @given(\"the following user details:\", target_fixture=\"users\")\n def _(datatable):\n users = []\n for row in datatable[1:]:\n users.append(row)\n\n print(users)\n return users\n\n\n @when(\"each user is assigned the following roles:\")\n def _(datatable, users):\n roles = datatable\n for user in users:\n for role_row in datatable:\n assign_role(user, role_row)\n\n\n @when(\"the page is saved\")\n def _():\n save_page()\n\n\n @then(\"the user should have the following permissions:\")\n def _(datatable, users):\n expected_permissions = []\n for row in datatable[1:]:\n expected_permissions.append(row)\n\n assert users_have_correct_permissions(users, expected_permissions)\n\n\nDocstrings\n----------\n\nThe `docstring` argument allows you to access the Gherkin docstring defined in your steps as a multiline string.\nThe content of the docstring is passed as a single string, with each line separated by `\\\\n`.\nLeading indentation are stripped.\n\nFor example, the Gherkin docstring:\n\n\n.. code-block:: gherkin\n\n \"\"\"\n This is a sample docstring.\n It spans multiple lines.\n \"\"\"\n\n\nWill be returned as:\n\n.. code-block:: python\n\n \"This is a sample docstring.\\nIt spans multiple lines.\"\n\n\nFull example:\n\n.. code-block:: gherkin\n\n Feature: Docstring\n\n Scenario: Step with docstrings\n Given some steps will have docstrings\n\n Then a step has a docstring\n \"\"\"\n This is a docstring\n on two lines\n \"\"\"\n\n And a step provides a docstring with lower indentation\n \"\"\"\n This is a docstring\n \"\"\"\n\n And this step has no docstring\n\n And this step has a greater indentation\n \"\"\"\n This is a docstring\n \"\"\"\n\n And this step has no docstring\n\n.. code-block:: python\n\n from pytest_bdd import given, then\n\n\n @given(\"some steps will have docstrings\")\n def _():\n pass\n\n @then(\"a step has a docstring\")\n def _(docstring):\n assert docstring == \"This is a docstring\\non two lines\"\n\n @then(\"a step provides a docstring with lower indentation\")\n def _(docstring):\n assert docstring == \"This is a docstring\"\n\n @then(\"this step has a greater indentation\")\n def _(docstring):\n assert docstring == \"This is a docstring\"\n\n @then(\"this step has no docstring\")\n def _():\n pass\n\n\n.. note:: The ``docstring`` argument can only be used for steps that have an associated docstring.\n Otherwise, an error will be thrown.\n\nOrganizing your scenarios\n-------------------------\n\nThe more features and scenarios you have, the more important the question of their organization becomes.\nThe things you can do (and that is also a recommended way):\n\n* organize your feature files in the folders by semantic groups:\n\n::\n\n features\n │\n ├──frontend\n │ │\n │ └──auth\n │ │\n │ └──login.feature\n └──backend\n │\n └──auth\n │\n └──login.feature\n\nThis looks fine, but how do you run tests only for a certain feature?\nAs pytest-bdd uses pytest, and bdd scenarios are actually normal tests. But test files\nare separate from the feature files, the mapping is up to developers, so the test files structure can look\ncompletely different:\n\n::\n\n tests\n │\n └──functional\n │\n └──test_auth.py\n │\n └ \"\"\"Authentication tests.\"\"\"\n from pytest_bdd import scenario\n\n @scenario('frontend/auth/login.feature')\n def test_logging_in_frontend():\n pass\n\n @scenario('backend/auth/login.feature')\n def test_logging_in_backend():\n pass\n\n\nFor picking up tests to run we can use the\n`tests selection `_ technique. The problem is that\nyou have to know how your tests are organized, knowing only the feature files organization is not enough.\nCucumber uses `tags `_ as a way of categorizing your features\nand scenarios, which pytest-bdd supports. For example, we could have:\n\n.. code-block:: gherkin\n\n @login @backend\n Feature: Login\n\n @successful\n Scenario: Successful login\n\n\npytest-bdd uses `pytest markers `_ as a `storage` of the tags for the given\nscenario test, so we can use standard test selection:\n\n.. code-block:: bash\n\n pytest -m \"backend and login and successful\"\n\nThe feature and scenario markers are not different from standard pytest markers, and the ``@`` symbol is stripped out automatically to allow test selector expressions. If you want to have bdd-related tags to be distinguishable from the other test markers, use a prefix like ``bdd``.\nNote that if you use pytest with the ``--strict-markers`` option, all Gherkin tags mentioned in the feature files should be also in the ``markers`` setting of the ``pytest.ini`` config. Also for tags please use names which are python-compatible variable names, i.e. start with a non-number, only underscores or alphanumeric characters, etc. That way you can safely use tags for tests filtering.\n\nYou can customize how tags are converted to pytest marks by implementing the\n``pytest_bdd_apply_tag`` hook and returning ``True`` from it:\n\n.. code-block:: python\n\n def pytest_bdd_apply_tag(tag, function):\n if tag == 'todo':\n marker = pytest.mark.skip(reason=\"Not implemented yet\")\n marker(function)\n return True\n else:\n # Fall back to the default behavior of pytest-bdd\n return None\n\nTest setup\n----------\n\nTest setup is implemented within the Given section. Even though these steps\nare executed imperatively to apply possible side-effects, pytest-bdd is trying\nto benefit of the PyTest fixtures which is based on the dependency injection\nand makes the setup more declarative style.\n\n.. code-block:: python\n\n @given(\"I have a beautiful article\", target_fixture=\"article\")\n def article():\n return Article(is_beautiful=True)\n\nThe target PyTest fixture \"article\" gets the return value and any other step can depend on it.\n\n.. code-block:: gherkin\n\n Feature: The power of PyTest\n Scenario: Symbolic name across steps\n Given I have a beautiful article\n When I publish this article\n\nThe When step is referencing the ``article`` to publish it.\n\n.. code-block:: python\n\n @when(\"I publish this article\")\n def publish_article(article):\n article.publish()\n\n\nMany other BDD toolkits operate on a global context and put the side effects there.\nThis makes it very difficult to implement the steps, because the dependencies\nappear only as the side-effects during run-time and not declared in the code.\nThe \"publish article\" step has to trust that the article is already in the context,\nhas to know the name of the attribute it is stored there, the type etc.\n\nIn pytest-bdd you just declare an argument of the step function that it depends on\nand the PyTest will make sure to provide it.\n\nStill side effects can be applied in the imperative style by design of the BDD.\n\n.. code-block:: gherkin\n\n Feature: News website\n Scenario: Publishing an article\n Given I have a beautiful article\n And my article is published\n\nFunctional tests can reuse your fixture libraries created for the unit-tests and upgrade\nthem by applying the side effects.\n\n.. code-block:: python\n\n @pytest.fixture\n def article():\n return Article(is_beautiful=True)\n\n\n @given(\"I have a beautiful article\")\n def i_have_a_beautiful_article(article):\n pass\n\n\n @given(\"my article is published\")\n def published_article(article):\n article.publish()\n return article\n\n\nThis way side-effects were applied to our article and PyTest makes sure that all\nsteps that require the \"article\" fixture will receive the same object. The value\nof the \"published_article\" and the \"article\" fixtures is the same object.\n\nFixtures are evaluated **only once** within the PyTest scope and their values are cached.\n\n\nBackgrounds\n-----------\n\nIt's often the case that to cover certain feature, you'll need multiple scenarios. And it's logical that the\nsetup for those scenarios will have some common parts (if not equal). For this, there are `backgrounds`.\npytest-bdd implements `Gherkin backgrounds `_ for\nfeatures.\n\n.. code-block:: gherkin\n\n Feature: Multiple site support\n\n Background:\n Given a global administrator named \"Greg\"\n And a blog named \"Greg's anti-tax rants\"\n And a customer named \"Wilson\"\n And a blog named \"Expensive Therapy\" owned by \"Wilson\"\n\n Scenario: Wilson posts to his own blog\n Given I am logged in as Wilson\n When I try to post to \"Expensive Therapy\"\n Then I should see \"Your article was published.\"\n\n Scenario: Greg posts to a client's blog\n Given I am logged in as Greg\n When I try to post to \"Expensive Therapy\"\n Then I should see \"Your article was published.\"\n\nIn this example, all steps from the background will be executed before all the scenario's own given\nsteps, adding a possibility to prepare some common setup for multiple scenarios in a single feature.\nAbout best practices for Background, please read Gherkin's\n`Tips for using Background `_.\n\n.. NOTE:: Only \"Given\" steps should be used in \"Background\" section.\n Steps \"When\" and \"Then\" are prohibited, because their purposes are\n related to actions and consuming outcomes; that is in conflict with the\n aim of \"Background\" - to prepare the system for tests or \"put the system\n in a known state\" as \"Given\" does it.\n\n\nReusing fixtures\n----------------\n\nSometimes scenarios define new names for an existing fixture that can be\ninherited (reused). For example, if we have the pytest fixture:\n\n\n.. code-block:: python\n\n @pytest.fixture\n def article():\n \"\"\"Test article.\"\"\"\n return Article()\n\n\nThen this fixture can be reused with other names using given():\n\n\n.. code-block:: python\n\n @given('I have a beautiful article')\n def i_have_an_article(article):\n \"\"\"I have an article.\"\"\"\n\n\nReusing steps\n-------------\n\nIt is possible to define some common steps in the parent ``conftest.py`` and\nsimply expect them in the child test file.\n\n.. code-block:: gherkin\n\n # content of common_steps.feature\n\n Scenario: All steps are declared in the conftest\n Given I have a bar\n Then bar should have value \"bar\"\n\n.. code-block:: python\n\n # content of conftest.py\n\n from pytest_bdd import given, then\n\n\n @given(\"I have a bar\", target_fixture=\"bar\")\n def bar():\n return \"bar\"\n\n\n @then('bar should have value \"bar\"')\n def bar_is_bar(bar):\n assert bar == \"bar\"\n\n.. code-block:: python\n\n # content of test_common.py\n\n @scenario(\"common_steps.feature\", \"All steps are declared in the conftest\")\n def test_conftest():\n pass\n\nThere are no definitions of steps in the test file. They were\ncollected from the parent conftest.py.\n\n\nDefault steps\n-------------\n\nHere is the list of steps that are implemented inside pytest-bdd:\n\ngiven\n * trace - enters the `pdb` debugger via `pytest.set_trace()`\nwhen\n * trace - enters the `pdb` debugger via `pytest.set_trace()`\nthen\n * trace - enters the `pdb` debugger via `pytest.set_trace()`\n\n\nFeature file paths\n------------------\n\nBy default, pytest-bdd will use the current module's path as the base path for finding feature files, but this behaviour can be changed in the pytest configuration file (i.e. `pytest.ini`, `tox.ini` or `setup.cfg`) by declaring the new base path in the `bdd_features_base_dir` key. The path is interpreted as relative to the `pytest root directory `__.\nYou can also override the features base path on a per-scenario basis, in order to override the path for specific tests.\n\npytest.ini:\n\n.. code-block:: ini\n\n [pytest]\n bdd_features_base_dir = features/\n\ntests/test_publish_article.py:\n\n.. code-block:: python\n\n from pytest_bdd import scenario\n\n\n @scenario(\"foo.feature\", \"Foo feature in features/foo.feature\")\n def test_foo():\n pass\n\n\n @scenario(\n \"foo.feature\",\n \"Foo feature in tests/local-features/foo.feature\",\n features_base_dir=\"./local-features/\",\n )\n def test_foo_local():\n pass\n\n\nThe `features_base_dir` parameter can also be passed to the `@scenario` decorator.\n\n\nAvoid retyping the feature file name\n------------------------------------\n\nIf you want to avoid retyping the feature file name when defining your scenarios in a test file, use ``functools.partial``.\nThis will make your life much easier when defining multiple scenarios in a test file. For example:\n\n.. code-block:: python\n\n # content of test_publish_article.py\n\n from functools import partial\n\n import pytest_bdd\n\n\n scenario = partial(pytest_bdd.scenario, \"/path/to/publish_article.feature\")\n\n\n @scenario(\"Publishing the article\")\n def test_publish():\n pass\n\n\n @scenario(\"Publishing the article as unprivileged user\")\n def test_publish_unprivileged():\n pass\n\n\nYou can learn more about `functools.partial `_\nin the Python docs.\n\n\nProgrammatic step generation\n----------------------------\nSometimes you have step definitions that would be much easier to automate rather than writing them manually over and over again.\nThis is common, for example, when using libraries like `pytest-factoryboy `_ that automatically creates fixtures.\nWriting step definitions for every model can become a tedious task.\n\nFor this reason, pytest-bdd provides a way to generate step definitions automatically.\n\nThe trick is to pass the ``stacklevel`` parameter to the ``given``, ``when``, ``then``, ``step`` decorators. This will instruct them to inject the step fixtures in the appropriate module, rather than just injecting them in the caller frame.\n\nLet's look at a concrete example; let's say you have a class ``Wallet`` that has some amount of each currency:\n\n.. code-block:: python\n\n # contents of wallet.py\n\n import dataclass\n\n @dataclass\n class Wallet:\n verified: bool\n\n amount_eur: int\n amount_usd: int\n amount_gbp: int\n amount_jpy: int\n\n\nYou can use pytest-factoryboy to automatically create model fixtures for this class:\n\n.. code-block:: python\n\n # contents of wallet_factory.py\n\n from wallet import Wallet\n\n import factory\n from pytest_factoryboy import register\n\n class WalletFactory(factory.Factory):\n class Meta:\n model = Wallet\n\n amount_eur = 0\n amount_usd = 0\n amount_gbp = 0\n amount_jpy = 0\n\n register(Wallet) # creates the \"wallet\" fixture\n register(Wallet, \"second_wallet\") # creates the \"second_wallet\" fixture\n\n\nNow we can define a function ``generate_wallet_steps(...)`` that creates the steps for any wallet fixture (in our case, it will be ``wallet`` and ``second_wallet``):\n\n.. code-block:: python\n\n # contents of wallet_steps.py\n\n import re\n from dataclasses import fields\n\n import factory\n import pytest\n from pytest_bdd import given, when, then, scenarios, parsers\n\n\n def generate_wallet_steps(model_name=\"wallet\", stacklevel=1):\n stacklevel += 1\n\n human_name = model_name.replace(\"_\", \" \") # \"second_wallet\" -> \"second wallet\"\n\n @given(f\"I have a {human_name}\", target_fixture=model_name, stacklevel=stacklevel)\n def _(request):\n return request.getfixturevalue(model_name)\n\n # Generate steps for currency fields:\n for field in fields(Wallet):\n match = re.fullmatch(r\"amount_(?P[a-z]{3})\", field.name)\n if not match:\n continue\n currency = match[\"currency\"]\n\n @given(\n parsers.parse(f\"I have {{value:d}} {currency.upper()} in my {human_name}\"),\n target_fixture=f\"{model_name}__amount_{currency}\",\n stacklevel=stacklevel,\n )\n def _(value: int) -> int:\n return value\n\n @then(\n parsers.parse(f\"I should have {{value:d}} {currency.upper()} in my {human_name}\"),\n stacklevel=stacklevel,\n )\n def _(value: int, _currency=currency, _model_name=model_name) -> None:\n wallet = request.getfixturevalue(_model_name)\n assert getattr(wallet, f\"amount_{_currency}\") == value\n\n # Inject the steps into the current module\n generate_wallet_steps(\"wallet\")\n generate_wallet_steps(\"second_wallet\")\n\n\nThis last file, ``wallet_steps.py``, now contains all the step definitions for our \"wallet\" and \"second_wallet\" fixtures.\n\nWe can now define a scenario like this:\n\n.. code-block:: gherkin\n\n # contents of wallet.feature\n Feature: A feature\n\n Scenario: Wallet EUR amount stays constant\n Given I have 10 EUR in my wallet\n And I have a wallet\n Then I should have 10 EUR in my wallet\n\n Scenario: Second wallet JPY amount stays constant\n Given I have 100 JPY in my second wallet\n And I have a second wallet\n Then I should have 100 JPY in my second wallet\n\n\nand finally a test file that puts it all together and run the scenarios:\n\n.. code-block:: python\n\n # contents of test_wallet.py\n\n from pytest_factoryboy import scenarios\n\n from wallet_factory import * # import the registered fixtures \"wallet\" and \"second_wallet\"\n from wallet_steps import * # import all the step definitions into this test file\n\n scenarios(\"wallet.feature\")\n\n\nHooks\n-----\n\npytest-bdd exposes several `pytest hooks `_\nwhich might be helpful building useful reporting, visualization, etc. on top of it:\n\n* `pytest_bdd_before_scenario(request, feature, scenario)` - Called before scenario is executed\n\n* `pytest_bdd_after_scenario(request, feature, scenario)` - Called after scenario is executed\n (even if one of steps has failed)\n\n* `pytest_bdd_before_step(request, feature, scenario, step, step_func)` - Called before step function\n is executed and its arguments evaluated\n\n* `pytest_bdd_before_step_call(request, feature, scenario, step, step_func, step_func_args)` - Called before step\n function is executed with evaluated arguments\n\n* `pytest_bdd_after_step(request, feature, scenario, step, step_func, step_func_args)` - Called after step function\n is successfully executed\n\n* `pytest_bdd_step_error(request, feature, scenario, step, step_func, step_func_args, exception)` - Called when step\n function failed to execute\n\n* `pytest_bdd_step_func_lookup_error(request, feature, scenario, step, exception)` - Called when step lookup failed\n\n\nBrowser testing\n---------------\n\nTools recommended to use for browser testing:\n\n* pytest-splinter_ - pytest `splinter `_ integration for the real browser testing\n\n\nReporting\n---------\n\nIt's important to have nice reporting out of your bdd tests. Cucumber introduced some kind of standard for\n`json format `_\nwhich can be used for, for example, by `this `_ Jenkins\nplugin.\n\nTo have an output in json format:\n\n::\n\n pytest --cucumberjson=\n\nThis will output an expanded (meaning scenario outlines will be expanded to several scenarios) Cucumber format.\n\nTo enable gherkin-formatted output on terminal, use `--gherkin-terminal-reporter` in conjunction with the `-v` or `-vv` options:\n\n::\n\n pytest -v --gherkin-terminal-reporter\n\n\nTest code generation helpers\n----------------------------\n\nFor newcomers it's sometimes hard to write all needed test code without being frustrated.\nTo simplify their life, a simple code generator was implemented. It allows to create fully functional\n(but of course empty) tests and step definitions for a given feature file.\nIt's done as a separate console script provided by pytest-bdd package:\n\n::\n\n pytest-bdd generate .. \n\nIt will print the generated code to the standard output so you can easily redirect it to the file:\n\n::\n\n pytest-bdd generate features/some.feature > tests/functional/test_some.py\n\n\nAdvanced code generation\n------------------------\n\nFor more experienced users, there's a smart code generation/suggestion feature. It will only generate the\ntest code which is not yet there, checking existing tests and step definitions the same way it's done during the\ntest execution. The code suggestion tool is called via passing additional pytest arguments:\n\n::\n\n pytest --generate-missing --feature features tests/functional\n\nThe output will be like:\n\n::\n\n ============================= test session starts ==============================\n platform linux2 -- Python 2.7.6 -- py-1.4.24 -- pytest-2.6.2\n plugins: xdist, pep8, cov, cache, bdd, bdd, bdd\n collected 2 items\n\n Scenario is not bound to any test: \"Code is generated for scenarios which are not bound to any tests\" in feature \"Missing code generation\" in /tmp/pytest-552/testdir/test_generate_missing0/tests/generation.feature\n --------------------------------------------------------------------------------\n\n Step is not defined: \"I have a custom bar\" in scenario: \"Code is generated for scenario steps which are not yet defined(implemented)\" in feature \"Missing code generation\" in /tmp/pytest-552/testdir/test_generate_missing0/tests/generation.feature\n --------------------------------------------------------------------------------\n Please place the code above to the test file(s):\n\n @scenario('tests/generation.feature', 'Code is generated for scenarios which are not bound to any tests')\n def test_Code_is_generated_for_scenarios_which_are_not_bound_to_any_tests():\n \"\"\"Code is generated for scenarios which are not bound to any tests.\"\"\"\n\n\n @given(\"I have a custom bar\")\n def I_have_a_custom_bar():\n \"\"\"I have a custom bar.\"\"\"\n\nAs as side effect, the tool will validate the files for format errors, also some of the logic bugs, for example the\nordering of the types of the steps.\n\n\n.. _Migration from 5.x.x:\n\nMigration of your tests from versions 5.x.x\n-------------------------------------------\n\nThe primary focus of the pytest-bdd is the compatibility with the latest gherkin developments\ne.g. multiple scenario outline example tables with tags support etc.\n\nIn order to provide the best compatibility, it is best to support the features described in the official\ngherkin reference. This means deprecation of some non-standard features that were implemented in pytest-bdd.\n\n\nRemoval of the feature examples\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nThe example tables on the feature level are no longer supported. If you had examples on the feature level, you should copy them to each individual scenario.\n\n\nRemoval of the vertical examples\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nVertical example tables are no longer supported since the official gherkin doesn't support them.\nThe example tables should have horizontal orientation.\n\n\nStep arguments are no longer fixtures\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nStep parsed arguments conflicted with the fixtures. Now they no longer define fixture.\nIf the fixture has to be defined by the step, the target_fixture param should be used.\n\n\nVariable templates in steps are only parsed for Scenario Outlines\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nIn previous versions of pytest, steps containing ```` would be parsed both by ``Scenario`` and ``Scenario Outline``.\nNow they are only parsed within a ``Scenario Outline``.\n\n\n.. _Migration from 4.x.x:\n\nMigration of your tests from versions 4.x.x\n-------------------------------------------\n\nReplace usage of inside step definitions with parsed {parameter}\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nTemplated steps (e.g. ``@given(\"there are cucumbers\")``) should now the use step argument parsers in order to match the scenario outlines and get the values from the example tables. The values from the example tables are no longer passed as fixtures, although if you define your step to use a parser, the parameters will be still provided as fixtures.\n\n.. code-block:: python\n\n # Old step definition:\n @given(\"there are cucumbers\")\n def given_cucumbers(start):\n pass\n\n\n # New step definition:\n @given(parsers.parse(\"there are {start} cucumbers\"))\n def given_cucumbers(start):\n pass\n\n\nScenario `example_converters` are removed in favor of the converters provided on the step level:\n\n.. code-block:: python\n\n # Old code:\n @given(\"there are cucumbers\")\n def given_cucumbers(start):\n return {\"start\": start}\n\n @scenario(\"outline.feature\", \"Outlined\", example_converters={\"start\": float})\n def test_outline():\n pass\n\n\n # New code:\n @given(parsers.parse(\"there are {start} cucumbers\"), converters={\"start\": float})\n def given_cucumbers(start):\n return {\"start\": start}\n\n @scenario(\"outline.feature\", \"Outlined\")\n def test_outline():\n pass\n\n\nRefuse combining scenario outline and pytest parametrization\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nThe significant downside of combining scenario outline and pytest parametrization approach was an inability to see the\ntest table from the feature file.\n\n\n.. _Migration from 3.x.x:\n\nMigration of your tests from versions 3.x.x\n-------------------------------------------\n\n\nGiven steps are no longer fixtures. In case it is needed to make given step setup a fixture,\nthe target_fixture parameter should be used.\n\n\n.. code-block:: python\n\n @given(\"there's an article\", target_fixture=\"article\")\n def there_is_an_article():\n return Article()\n\n\nGiven steps no longer have the `fixture` parameter. In fact the step may depend on multiple fixtures.\nJust normal step declaration with the dependency injection should be used.\n\n.. code-block:: python\n\n @given(\"there's an article\")\n def there_is_an_article(article):\n pass\n\n\nStrict gherkin option is removed, so the ``strict_gherkin`` parameter can be removed from the scenario decorators\nas well as ``bdd_strict_gherkin`` from the ini files.\n\nStep validation handlers for the hook ``pytest_bdd_step_validation_error`` should be removed.\n\nLicense\n-------\n\nThis software is licensed under the `MIT License `_.\n\n© 2013 Oleg Pidsadnyi, Anatoly Bubenkov and others\n\n","description_content_type":"text/x-rst","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":"https://pytest-bdd.readthedocs.io/","keywords":null,"license":"MIT","license_expression":null,"license_files":null,"maintainer":"Alessio Bogon","maintainer_email":"778703+youtux@users.noreply.github.com","name":"pytest-bdd","package_url":"https://pypi.org/project/pytest-bdd/","platform":null,"project_url":"https://pypi.org/project/pytest-bdd/","project_urls":{"Documentation":"https://pytest-bdd.readthedocs.io/","Homepage":"https://pytest-bdd.readthedocs.io/","Repository":"https://github.com/pytest-dev/pytest-bdd"},"provides_extra":null,"release_url":"https://pypi.org/project/pytest-bdd/8.1.0/","requires_dist":["Mako","gherkin-official<30.0.0,>=29.0.0","packaging","parse","parse-type","pytest>=7.0.0","typing-extensions"],"requires_python":">=3.9","summary":"BDD for pytest","version":"8.1.0","yanked":false,"yanked_reason":null}

Dependency	Optional
gherkin-official	false
Mako	false
packaging	false
parse	false
parse-type	false
pytest	false
typing-extensions	false

Package search

pytest-bdd

project_urls

Dependencies

All package metadata

Releases