Repository files navigation

pytest-bdd implements a subset of the Gherkin language to enable automating projectrequirements testing and to facilitate behavioral driven development.

Unlike many other BDD tools, it does not require a separate runner and benefits fromthe power and flexibility of pytest. It enables unifying unit and functionaltests, reduces the burden of continuous integration server configuration and allows the reuse oftest setups.

Pytest fixtures written for unit tests can be reused for setup and actionsmentioned in feature steps with dependency injection. This allows a true BDDjust-enough specification of the requirements without maintaining any context objectcontaining the side effects of Gherkin imperative declarations.

pip install pytest-bdd

An example test for a blog hosting software could look like this.Note thatpytest-splinter is used to get the browser fixture.

# content of publish_article.featureFeature: BlogAsite where you can publish your articles.Scenario: Publishing the articleGivenI'm an author userAndI have an articleWhenI go to the article pageAndI press the publish buttonThenI should not see the error messageAndthe article should be published

Note that only one feature is allowed per feature file.

# content of test_publish_article.pyfrompytest_bddimportscenario,given,when,then@scenario('publish_article.feature','Publishing the article')deftest_publish():pass@given("I'm an author user")defauthor_user(auth,author):auth['user']=author.user@given("I have an article",target_fixture="article")defarticle(author):returncreate_test_article(author=author)@when("I go to the article page")defgo_to_article(article,browser):browser.visit(urljoin(browser.url,'/manage/articles/{0}/'.format(article.id)))@when("I press the publish button")defpublish_article(browser):browser.find_by_css('button[name=publish]').first.click()@then("I should not see the error message")defno_error_message(browser):withpytest.raises(ElementDoesNotExist):browser.find_by_css('.message.error').first@then("the article should be published")defarticle_is_published(article):article.refresh()# Refresh the object in the SQLAlchemy sessionassertarticle.is_published

Functions decorated with the scenario decorator behave like a normal test function,and they will be executed after all scenario steps.

frompytest_bddimportscenario,given,when,then@scenario('publish_article.feature','Publishing the article')deftest_publish(browser):assertarticle.titleinbrowser.html

Sometimes, one has to declare the same fixtures or steps withdifferent names for better readability. In order to use the same stepfunction with multiple step names simply decorate it multiple times:

@given("I have an article")@given("there's an article")defarticle(author,target_fixture="article"):returncreate_test_article(author=author)

Note that the given step aliases are independent and will be executedwhen mentioned.

For example if you associate your resource to some owner or not. Adminuser can’t be an author of the article, but articles should have adefault author.

Feature: Resource ownerScenario: I'm the authorGivenI'm an authorAndI have an articleScenario: I'm the adminGivenI'm the adminAndthere's an article

To avoid redundancy or unnecessary repetition of keywordssuch as "And" or "But" in Gherkin scenarios,you can use an asterisk (*) as a shorthand.The asterisk acts as a wildcard, allowing for the same functionalitywithout repeating the keyword explicitly.It improves readability by making the steps easier to follow,especially when the specific keyword does not add value to the scenario's clarity.

The asterisk will work the same as other step keywords - Given, When, Then - it follows.

For example:

Feature: Resource ownerScenario: I'm the authorGivenI'm an author*I have an article*I have a pen

frompytest_bddimportgiven@given("I'm an author")def_():pass@given("I have an article")def_():pass@given("I have a pen")def_():pass

In the scenario above, the asterisk (*) replaces the And or Given keywords.This allows for cleaner scenarios while still linking related steps together in the context of the scenario.

This approach is particularly useful when you have a series of stepsthat do not require explicitly stating whether they are part of the "Given", "When", or "Then" contextbut are part of the logical flow of the scenario.

Often it's possible to reuse steps giving them a parameter(s).This allows to have single implementation and multiple use, so less code.Also opens the possibility to use same step twice in single scenario and with different arguments!And even more, there are several types of step parameter parsers at your disposal(idea taken frombehave implementation):

string (the default)

This is the default and can be considered as a null or exact parser. It parses no parametersand matches the step name by equality of strings.

parse (based on:pypi_parse)

Provides a simple parser that replaces regular expressions forstep parameters with a readable syntax like{param:Type}.The syntax is inspired by the Python builtinstring.format()function.Step parameters must use the named fields syntax ofpypi_parsein step definitions. The named fields are extracted,optionally type converted and then used as step function arguments.Supports type conversions by using type converters passed via extra_types

cfparse (extends:pypi_parse, based on:pypi_parse_type)

Provides an extended parser with "Cardinality Field" (CF) support.Automatically creates missing type converters for related cardinalityas long as a type converter for cardinality=1 is provided.Supports parse expressions like:*{values:Type+} (cardinality=1..N, many)*{values:Type*} (cardinality=0..N, many0)*{value:Type?} (cardinality=0..1, optional)Supports type conversions (as above).

re

This uses full regular expressions to parse the clause text. You willneed to use named groups "(?P<name>...)" to define the variables pulledfrom the text and passed to yourstep() function.Type conversion can only be done via converters step decorator argument (see example below).

The default parser is string, so just plain one-to-one match to the keyword definition.Parsers except string, as well as their optional arguments are specified like:

for cfparse parser

frompytest_bddimportparsers@given(parsers.cfparse("there are {start:Number} cucumbers",extra_types={"Number":int}),target_fixture="cucumbers",)defgiven_cucumbers(start):return {"start":start,"eat":0}

for re parser

frompytest_bddimportparsers@given(parsers.re(r"there are (?P<start>\d+) cucumbers"),converters={"start":int},target_fixture="cucumbers",)defgiven_cucumbers(start):return {"start":start,"eat":0}

Example:

Feature: Step argumentsScenario: Arguments for given, when, thenGiventhere are 5 cucumbersWhenI eat 3 cucumbersAndI eat 2 cucumbersThenI should have 0 cucumbers

The code will look like:

frompytest_bddimportscenarios,given,when,then,parsersscenarios("arguments.feature")@given(parsers.parse("there are {start:d} cucumbers"),target_fixture="cucumbers")defgiven_cucumbers(start):return {"start":start,"eat":0}@when(parsers.parse("I eat {eat:d} cucumbers"))defeat_cucumbers(cucumbers,eat):cucumbers["eat"]+=eat@then(parsers.parse("I should have {left:d} cucumbers"))defshould_have_left_cucumbers(cucumbers,left):assertcucumbers["start"]-cucumbers["eat"]==left

Example code also shows possibility to pass argument converters which may be useful if you need to postprocess steparguments after the parser.

You can implement your own step parser. It's interface is quite simple. The code can look like:

importrefrompytest_bddimportgiven,parsersclassMyParser(parsers.StepParser):"""Custom parser."""def__init__(self,name,**kwargs):"""Compile regex."""super().__init__(name)self.regex=re.compile(re.sub("%(.+)%","(?P<\1>.+)",self.name),**kwargs)defparse_arguments(self,name):"""Get step arguments.        :return: `dict` of step arguments        """returnself.regex.match(name).groupdict()defis_matching(self,name):"""Match given name with the step name."""returnbool(self.regex.match(name))@given(parsers.parse("there are %start% cucumbers"),target_fixture="cucumbers")defgiven_cucumbers(start):return {"start":start,"eat":0}

Dependency injection is not a panacea if you have complex structure of your test setup data. Sometimes there's a needsuch a given step which would imperatively change the fixture only for certain test (scenario), while for other testsit will stay untouched. To allow this, special parameter target_fixture exists in the given decorator:

frompytest_bddimportgiven@pytest.fixturedeffoo():return"foo"@given("I have injecting given",target_fixture="foo")definjecting_given():return"injected foo"@then('foo should be "injected foo"')deffoo_is_foo(foo):assertfoo=='injected foo'

Feature: Target fixtureScenario: Test given fixture injectionGivenI have injecting givenThenfoo should be"injected foo"

In this example, the existing fixture foo will be overridden by given step I have injecting given only for the scenario it'sused in.

Sometimes it is also useful to let when and then steps provide a fixture as well.A common use case is when we have to assert the outcome of an HTTP request:

# content of test_blog.pyfrompytest_bddimportscenarios,given,when,thenfrommy_app.modelsimportArticlescenarios("blog.feature")@given("there is an article",target_fixture="article")defthere_is_an_article():returnArticle()@when("I request the deletion of the article",target_fixture="request_result")defthere_should_be_a_new_article(article,http_client):returnhttp_client.delete(f"/articles/{article.uid}")@then("the request should be successful")defarticle_is_published(request_result):assertrequest_result.status_code==200

# content of blog.featureFeature: BlogScenario: Deleting the articleGiventhere is an articleWhenI request the deletion of the articleThenthe request should be successful

If 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.Instead, you want to bind all the scenarios found in thefeatures folder(s) recursively automatically, by using thescenarios helper.

frompytest_bddimportscenarios# assume 'features' subfolder is in this file's directoryscenarios('features')

That's all you need to do to bind all scenarios found in thefeatures folder!Note that you can pass multiple paths, and those paths can be either feature files or feature folders.

frompytest_bddimportscenarios# pass multiple paths/filesscenarios('features','other_features/some.feature','some_other_features')

But what if you need to manually bind a certain scenario, leaving others to be automatically bound?Just write your scenario in a "normal" way, but ensure you do itbefore the call ofscenarios helper.

frompytest_bddimportscenario,scenarios@scenario('features/some.feature','Test something')deftest_something():pass# assume 'features' subfolder is in this file's directoryscenarios('features')

In the example above, thetest_something scenario binding will be kept manual, other scenarios found in thefeatures folder will be bound automatically.

Scenarios can be parametrized to cover multiple cases. These are calledScenario Outlines in Gherkin, and the variable templates are written using angular brackets (e.g.<var_name>).

Example:

# content of scenario_outlines.featureFeature: Scenario outlinesScenario Outline: Outlined given, when, thenGiventhere are<start> cucumbersWhenI eat<eat> cucumbersThenI should have<left> cucumbersExamples:        |start |eat |left |        |12   |5  |7   |

frompytest_bddimportscenarios,given,when,then,parsersscenarios("scenario_outlines.feature")@given(parsers.parse("there are {start:d} cucumbers"),target_fixture="cucumbers")defgiven_cucumbers(start):return {"start":start,"eat":0}@when(parsers.parse("I eat {eat:d} cucumbers"))defeat_cucumbers(cucumbers,eat):cucumbers["eat"]+=eat@then(parsers.parse("I should have {left:d} cucumbers"))defshould_have_left_cucumbers(cucumbers,left):assertcucumbers["start"]-cucumbers["eat"]==left

Example parameters from example tables can not only be used in steps, but also embedded directly within docstrings and datatables, allowing for dynamic substitution.This provides added flexibility for scenarios that require complex setups or validations.

Example:

# content of docstring_and_datatable_with_params.featureFeature: Docstring and Datatable with example parametersScenario Outline: Using parameters in docstrings and datatablesGiventhe following configuration:"""            username: <username>            password: <password>            """Whenthe user logs inThenthe response should contain:            |field     |value      |            |username  | <username> |            |logged_in |true       |Examples:        |username  |password  |        |user1     |pass123   |        |user2     |123secure |

frompytest_bddimportscenarios,given,when,thenimportjson# Load scenarios from the feature filescenarios("docstring_and_datatable_with_params.feature")@given("the following configuration:")defgiven_user_config(docstring):print(docstring)@when("the user logs in")defuser_logs_in(logged_in):logged_in=True@then("the response should contain:")defresponse_should_contain(datatable):assertdatatable[1][1]in ["user1","user2"]

In pytest-bdd, you can use multiple example tables in a scenario outline to testdifferent sets of input data under various conditions.You can define separate Examples blocks, each with its own table of data,and optionally tag them to differentiate between positive, negative, or any other conditions.

Example:

# content of scenario_outline.featureFeature: Scenario outlines with multiple examples tablesScenario Outline: Outlined with multiple example tablesGiventhere are<start> cucumbersWhenI eat<eat> cucumbersThenI should have<left> cucumbers@positiveExamples: Positive results            |start |eat |left |            |12   |5  |7   |            |5    |4  |1   |@negativeExamples: Impossible negative results            |start |eat |left |            |3    |9  |  -6  |            |1    |4  |  -3  |

frompytest_bddimportscenarios,given,when,then,parsersscenarios("scenario_outline.feature")@given(parsers.parse("there are {start:d} cucumbers"),target_fixture="cucumbers")defgiven_cucumbers(start):return {"start":start,"eat":0}@when(parsers.parse("I eat {eat:d} cucumbers"))defeat_cucumbers(cucumbers,eat):cucumbers["eat"]+=eat@then(parsers.parse("I should have {left:d} cucumbers"))defshould_have_left_cucumbers(cucumbers,left):assertcucumbers["start"]-cucumbers["eat"]==left

When you filter scenarios by a tag, only the examples associated with that tag will be executed.This allows you to run a specific subset of your test cases based on the tag.For example, in the following scenario outline, if you filter by the @positive tag,only the examples under the "Positive results" table will be executed, and the "Negative results" table will be ignored.

pytest -k"positive"

By default, empty cells in the example tables are interpreted as empty strings ("").However, there may be cases where it is more appropriate to handle them asNone.In such scenarios, you can use a converter with theparsers.re parser to define a custom behavior for empty values.

For example, the following code demonstrates how to use a custom converter to returnNone when an empty cell is encountered:

# content of empty_example_cells.featureFeature: Handling empty example cellsScenario Outline: Using converters for empty cellsGivenI am starting lunchThenthere are<start> cucumbersExamples:        |start |        |       |

frompytest_bddimportthen,parsers# Define a converter that returns None for empty stringsdefempty_to_none(value):returnNoneifvalue.strip()==""elsevalue@given("I am starting lunch")def_():pass@then(parsers.re("there are (?P<start>.*?) cucumbers"),converters={"start":empty_to_none})def_(start):# Example assertion to demonstrate the conversionassertstartisNone

Here, the start cell in the example table is empty.When theparsers.re parser is combined with theempty_to_none converter,the empty cell will be converted toNone and can be handled accordingly in the step definition.

In Gherkin, Rules allow you to group related scenarios or examples under a shared context.This is useful when you want to define different conditions or behavioursfor multiple examples that follow a similar structure.You can use eitherScenario orExample to define individual cases, as they are aliases and function identically.

Additionally,tags applied to a rule will be automatically applied to all theexamples or scenariosunder that rule, making it easier to organize and filter tests during execution.

Example:

Feature: Rules and examples@feature_tag    Rule: A rule for valid cases@rule_tag        Example: Valid case 1GivenI have a valid inputWhenI process the inputThenthe result should be successful    Rule: A rule for invalid cases        Example: Invalid caseGivenI have an invalid inputWhenI process the inputThenthe result should be an error

Thedatatable argument allows you to utilise data tables defined in your Gherkin scenariosdirectly within your test functions. This is particularly useful for scenarios that require tabular data as input,enabling you to manage and manipulate this data conveniently.

When you use thedatatable argument in a step definition, it will return the table as a list of lists,where each inner list represents a row from the table.

For example, the Gherkin table:

|name  |email            ||John  |john@example.com |

Will be returned by thedatatable argument as:

[    ["name","email"],    ["John","john@example.com"]]

Full example:

Feature: Manage user accountsScenario: Creating a new user with roles and permissionsGiventhe following user details:      |name  |email             |age |      |John  |john@example.com  |30  |      |Alice |alice@example.com |25  |Wheneach user is assigned the following roles:      |Admin       |Fullaccesstothesystem |      |Contributor |Canaddcontent           |Andthe page is savedThenthe user should have the following permissions:      |permission     |allowed |      |viewdashboard |true    |      |editcontent   |true    |      |deletecontent |false   |

frompytest_bddimportgiven,when,then@given("the following user details:",target_fixture="users")def_(datatable):users= []forrowindatatable[1:]:users.append(row)print(users)returnusers@when("each user is assigned the following roles:")def_(datatable,users):roles=datatableforuserinusers:forrole_rowindatatable:assign_role(user,role_row)@when("the page is saved")def_():save_page()@then("the user should have the following permissions:")def_(datatable,users):expected_permissions= []forrowindatatable[1:]:expected_permissions.append(row)assertusers_have_correct_permissions(users,expected_permissions)

The docstring argument allows you to access the Gherkin docstring defined in your steps as a multiline string.The content of the docstring is passed as a single string, with each line separated by \n.Leading indentation are stripped.

For example, the Gherkin docstring:

"""This is a sample docstring.It spans multiple lines."""

Will be returned as:

"This is a sample docstring.\nIt spans multiple lines."

Full example:

Feature: DocstringScenario: Step with docstringsGivensome steps will have docstringsThena step has a docstring"""    This is a docstring    on two lines    """Anda step provides a docstring with lower indentation"""This is a docstring    """Andthis step has no docstringAndthis step has a greater indentation"""        This is a docstring    """Andthis step has no docstring

frompytest_bddimportgiven,then@given("some steps will have docstrings")def_():pass@then("a step has a docstring")def_(docstring):assertdocstring=="This is a docstring\non two lines"@then("a step provides a docstring with lower indentation")def_(docstring):assertdocstring=="This is a docstring"@then("this step has a greater indentation")def_(docstring):assertdocstring=="This is a docstring"@then("this step has no docstring")def_():pass

The more features and scenarios you have, the more important the question of their organization becomes.The things you can do (and that is also a recommended way):

• organize your feature files in the folders by semantic groups:

features│├──frontend│  ││  └──auth│     ││     └──login.feature└──backend   │   └──auth      │      └──login.feature

This looks fine, but how do you run tests only for a certain feature?As pytest-bdd uses pytest, and bdd scenarios are actually normal tests. But test filesare separate from the feature files, the mapping is up to developers, so the test files structure can lookcompletely different:

tests│└──functional   │   └──test_auth.py      │      └ """Authentication tests."""        from pytest_bdd import scenario        @scenario('frontend/auth/login.feature')        def test_logging_in_frontend():            pass        @scenario('backend/auth/login.feature')        def test_logging_in_backend():            pass

For picking up tests to run we can use thetests selection technique. The problem is thatyou have to know how your tests are organized, knowing only the feature files organization is not enough.Cucumber usestags as a way of categorizing your featuresand scenarios, which pytest-bdd supports. For example, we could have:

@login@backendFeature: Login@successfulScenario: Successful login

pytest-bdd usespytest markers as a storage of the tags for the givenscenario test, so we can use standard test selection:

pytest -m"backend and login and successful"

The 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 likebdd.Note that if you use pytest with the--strict-markers option, all Gherkin tags mentioned in the feature files should be also in themarkers setting of thepytest.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.

You can customize how tags are converted to pytest marks by implementing thepytest_bdd_apply_tag hook and returningTrue from it:

defpytest_bdd_apply_tag(tag,function):iftag=='todo':marker=pytest.mark.skip(reason="Not implemented yet")marker(function)returnTrueelse:# Fall back to the default behavior of pytest-bddreturnNone

Test setup is implemented within the Given section. Even though these stepsare executed imperatively to apply possible side-effects, pytest-bdd is tryingto benefit of the PyTest fixtures which is based on the dependency injectionand makes the setup more declarative style.

@given("I have a beautiful article",target_fixture="article")defarticle():returnArticle(is_beautiful=True)

The target PyTest fixture "article" gets the return value and any other step can depend on it.

Feature: The power of PyTestScenario: Symbolic name across stepsGivenI have a beautiful articleWhenI publish this article

The When step is referencing thearticle to publish it.

@when("I publish this article")defpublish_article(article):article.publish()

Many other BDD toolkits operate on a global context and put the side effects there.This makes it very difficult to implement the steps, because the dependenciesappear only as the side-effects during run-time and not declared in the code.The "publish article" step has to trust that the article is already in the context,has to know the name of the attribute it is stored there, the type etc.

In pytest-bdd you just declare an argument of the step function that it depends onand the PyTest will make sure to provide it.

Still side effects can be applied in the imperative style by design of the BDD.

Feature: News websiteScenario: Publishing an articleGivenI have a beautiful articleAndmy article is published

Functional tests can reuse your fixture libraries created for the unit-tests and upgradethem by applying the side effects.

@pytest.fixturedefarticle():returnArticle(is_beautiful=True)@given("I have a beautiful article")defi_have_a_beautiful_article(article):pass@given("my article is published")defpublished_article(article):article.publish()returnarticle

This way side-effects were applied to our article and PyTest makes sure that allsteps that require the "article" fixture will receive the same object. The valueof the "published_article" and the "article" fixtures is the same object.

Fixtures are evaluatedonly once within the PyTest scope and their values are cached.

It's often the case that to cover certain feature, you'll need multiple scenarios. And it's logical that thesetup for those scenarios will have some common parts (if not equal). For this, there are backgrounds.pytest-bdd implementsGherkin backgrounds forfeatures.

Feature: Multiple site supportBackground:Givena global administrator named"Greg"Anda blog named"Greg's anti-tax rants"Anda customer named"Wilson"Anda blog named"Expensive Therapy" owned by"Wilson"Scenario: Wilson posts to his own blogGivenI am logged in as WilsonWhenI try to post to"Expensive Therapy"ThenI should see"Your article was published."Scenario: Greg posts to a client's blogGivenI am logged in as GregWhenI try to post to"Expensive Therapy"ThenI should see"Your article was published."

In this example, all steps from the background will be executed before all the scenario's own givensteps, adding a possibility to prepare some common setup for multiple scenarios in a single feature.About best practices for Background, please read Gherkin'sTips for using Background.

Sometimes scenarios define new names for an existing fixture that can beinherited (reused). For example, if we have the pytest fixture:

@pytest.fixturedefarticle():"""Test article."""returnArticle()

Then this fixture can be reused with other names using given():

@given('I have a beautiful article')defi_have_an_article(article):"""I have an article."""

It is possible to define some common steps in the parentconftest.py andsimply expect them in the child test file.

# content of common_steps.featureScenario: All steps are declared in the conftestGivenI have a barThenbar should have value"bar"

# content of conftest.pyfrompytest_bddimportgiven,then@given("I have a bar",target_fixture="bar")defbar():return"bar"@then('bar should have value "bar"')defbar_is_bar(bar):assertbar=="bar"

# content of test_common.py@scenario("common_steps.feature","All steps are declared in the conftest")deftest_conftest():pass

There are no definitions of steps in the test file. They werecollected from the parent conftest.py.

Here is the list of steps that are implemented inside pytest-bdd:

given

• trace - enters the pdb debugger via pytest.set_trace()

when

• trace - enters the pdb debugger via pytest.set_trace()

then

• trace - enters the pdb debugger via pytest.set_trace()

By 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 thepytest root directory.You can also override the features base path on a per-scenario basis, in order to override the path for specific tests.

pytest.ini:

[pytest]bdd_features_base_dir = features/

tests/test_publish_article.py:

frompytest_bddimportscenario@scenario("foo.feature","Foo feature in features/foo.feature")deftest_foo():pass@scenario("foo.feature","Foo feature in tests/local-features/foo.feature",features_base_dir="./local-features/",)deftest_foo_local():pass

The features_base_dir parameter can also be passed to the @scenario decorator.

If you want to avoid retyping the feature file name when defining your scenarios in a test file, usefunctools.partial.This will make your life much easier when defining multiple scenarios in a test file. For example:

# content of test_publish_article.pyfromfunctoolsimportpartialimportpytest_bddscenario=partial(pytest_bdd.scenario,"/path/to/publish_article.feature")@scenario("Publishing the article")deftest_publish():pass@scenario("Publishing the article as unprivileged user")deftest_publish_unprivileged():pass

You can learn more aboutfunctools.partialin the Python docs.

Sometimes you have step definitions that would be much easier to automate rather than writing them manually over and over again.This is common, for example, when using libraries likepytest-factoryboy that automatically creates fixtures.Writing step definitions for every model can become a tedious task.

For this reason, pytest-bdd provides a way to generate step definitions automatically.

The trick is to pass thestacklevel parameter to thegiven,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.

Let's look at a concrete example; let's say you have a classWallet that has some amount of each currency:

# contents of wallet.pyimportdataclass@dataclassclassWallet:verified:boolamount_eur:intamount_usd:intamount_gbp:intamount_jpy:int

You can use pytest-factoryboy to automatically create model fixtures for this class:

# contents of wallet_factory.pyfromwalletimportWalletimportfactoryfrompytest_factoryboyimportregisterclassWalletFactory(factory.Factory):classMeta:model=Walletamount_eur=0amount_usd=0amount_gbp=0amount_jpy=0register(Wallet)# creates the "wallet" fixtureregister(Wallet,"second_wallet")# creates the "second_wallet" fixture

Now we can define a functiongenerate_wallet_steps(...) that creates the steps for any wallet fixture (in our case, it will bewallet andsecond_wallet):

# contents of wallet_steps.pyimportrefromdataclassesimportfieldsimportfactoryimportpytestfrompytest_bddimportgiven,when,then,scenarios,parsersdefgenerate_wallet_steps(model_name="wallet",stacklevel=1):stacklevel+=1human_name=model_name.replace("_"," ")# "second_wallet" -> "second wallet"@given(f"I have a{human_name}",target_fixture=model_name,stacklevel=stacklevel)def_(request):returnrequest.getfixturevalue(model_name)# Generate steps for currency fields:forfieldinfields(Wallet):match=re.fullmatch(r"amount_(?P<currency>[a-z]{3})",field.name)ifnotmatch:continuecurrency=match["currency"]@given(parsers.parse(f"I have {{value:d}}{currency.upper()} in my{human_name}"),target_fixture=f"{model_name}__amount_{currency}",stacklevel=stacklevel,        )def_(value:int)->int:returnvalue@then(parsers.parse(f"I should have {{value:d}}{currency.upper()} in my{human_name}"),stacklevel=stacklevel,        )def_(value:int,_currency=currency,_model_name=model_name)->None:wallet=request.getfixturevalue(_model_name)assertgetattr(wallet,f"amount_{_currency}")==value# Inject the steps into the current modulegenerate_wallet_steps("wallet")generate_wallet_steps("second_wallet")

This last file,wallet_steps.py, now contains all the step definitions for our "wallet" and "second_wallet" fixtures.

We can now define a scenario like this:

# contents of wallet.featureFeature: A featureScenario: Wallet EUR amount stays constantGivenI have 10 EUR in my walletAndI have a walletThenI should have 10 EUR in my walletScenario: Second wallet JPY amount stays constantGivenI have 100 JPY in my second walletAndI have a second walletThenI should have 100 JPY in my second wallet

and finally a test file that puts it all together and run the scenarios:

# contents of test_wallet.pyfrompytest_factoryboyimportscenariosfromwallet_factoryimport*# import the registered fixtures "wallet" and "second_wallet"fromwallet_stepsimport*# import all the step definitions into this test filescenarios("wallet.feature")

pytest-bdd exposes severalpytest hookswhich might be helpful building useful reporting, visualization, etc. on top of it:

• pytest_bdd_before_scenario(request, feature, scenario) - Called before scenario is executed
• pytest_bdd_after_scenario(request, feature, scenario) - Called after scenario is executed(even if one of steps has failed)
• pytest_bdd_before_step(request, feature, scenario, step, step_func) - Called before step functionis executed and its arguments evaluated
• pytest_bdd_before_step_call(request, feature, scenario, step, step_func, step_func_args) - Called before stepfunction is executed with evaluated arguments
• pytest_bdd_after_step(request, feature, scenario, step, step_func, step_func_args) - Called after step functionis successfully executed
• pytest_bdd_step_error(request, feature, scenario, step, step_func, step_func_args, exception) - Called when stepfunction failed to execute
• pytest_bdd_step_func_lookup_error(request, feature, scenario, step, exception) - Called when step lookup failed

Tools recommended to use for browser testing:

• pytest-splinter - pytestsplinter integration for the real browser testing

It's important to have nice reporting out of your bdd tests. Cucumber introduced some kind of standard forjson formatwhich can be used for, for example, bythis Jenkinsplugin.

To have an output in json format:

pytest --cucumberjson=<path to json report>

This will output an expanded (meaning scenario outlines will be expanded to several scenarios) Cucumber format.

To enable gherkin-formatted output on terminal, use --gherkin-terminal-reporter in conjunction with the -v or -vv options:

pytest -v --gherkin-terminal-reporter

For newcomers it's sometimes hard to write all needed test code without being frustrated.To simplify their life, a simple code generator was implemented. It allows to create fully functional(but of course empty) tests and step definitions for a given feature file.It's done as a separate console script provided by pytest-bdd package:

pytest-bdd generate <feature file name> .. <feature file nameN>

It will print the generated code to the standard output so you can easily redirect it to the file:

pytest-bdd generate features/some.feature > tests/functional/test_some.py

For more experienced users, there's a smart code generation/suggestion feature. It will only generate thetest code which is not yet there, checking existing tests and step definitions the same way it's done during thetest execution. The code suggestion tool is called via passing additional pytest arguments:

pytest --generate-missing --feature features tests/functional

The output will be like:

============================= test session starts ==============================platform linux2 -- Python 2.7.6 -- py-1.4.24 -- pytest-2.6.2plugins: xdist, pep8, cov, cache, bdd, bdd, bddcollected 2 itemsScenario 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--------------------------------------------------------------------------------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--------------------------------------------------------------------------------Please place the code above to the test file(s):@scenario('tests/generation.feature', 'Code is generated for scenarios which are not bound to any tests')def test_Code_is_generated_for_scenarios_which_are_not_bound_to_any_tests():    """Code is generated for scenarios which are not bound to any tests."""@given("I have a custom bar")def I_have_a_custom_bar():    """I have a custom bar."""

As as side effect, the tool will validate the files for format errors, also some of the logic bugs, for example theordering of the types of the steps.

The primary focus of the pytest-bdd is the compatibility with the latest gherkin developmentse.g. multiple scenario outline example tables with tags support etc.

In order to provide the best compatibility, it is best to support the features described in the officialgherkin reference. This means deprecation of some non-standard features that were implemented in pytest-bdd.

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

Vertical example tables are no longer supported since the official gherkin doesn't support them.The example tables should have horizontal orientation.

Step parsed arguments conflicted with the fixtures. Now they no longer define fixture.If the fixture has to be defined by the step, the target_fixture param should be used.

In previous versions of pytest, steps containing<variable> would be parsed both byScenario andScenario Outline.Now they are only parsed within aScenario Outline.

Templated steps (e.g.@given("there are <start> 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.

# Old step definition:@given("there are <start> cucumbers")defgiven_cucumbers(start):pass# New step definition:@given(parsers.parse("there are {start} cucumbers"))defgiven_cucumbers(start):pass

Scenario example_converters are removed in favor of the converters provided on the step level:

# Old code:@given("there are <start> cucumbers")defgiven_cucumbers(start):return {"start":start}@scenario("outline.feature","Outlined",example_converters={"start":float})deftest_outline():pass# New code:@given(parsers.parse("there are {start} cucumbers"),converters={"start":float})defgiven_cucumbers(start):return {"start":start}@scenario("outline.feature","Outlined")deftest_outline():pass

The significant downside of combining scenario outline and pytest parametrization approach was an inability to see thetest table from the feature file.

Given steps are no longer fixtures. In case it is needed to make given step setup a fixture,the target_fixture parameter should be used.

@given("there's an article",target_fixture="article")defthere_is_an_article():returnArticle()

Given steps no longer have the fixture parameter. In fact the step may depend on multiple fixtures.Just normal step declaration with the dependency injection should be used.

@given("there's an article")defthere_is_an_article(article):pass

Strict gherkin option is removed, so thestrict_gherkin parameter can be removed from the scenario decoratorsas well asbdd_strict_gherkin from the ini files.

Step validation handlers for the hookpytest_bdd_step_validation_error should be removed.

This software is licensed under theMIT License.

© 2013 Oleg Pidsadnyi, Anatoly Bubenkov and others