pytest-bdd implements a subset of Gherkin language for the automation of the project requirements testing and easier behavioral driven development.

Unlike many other BDD tools it doesn't require a separate runner and benefits from the power and flexibility of the pytest. It allows to unify your unit and functional tests, easier continuous integration server configuration and maximal reuse of the tests setup.

Pytest fixtures written for the unit tests can be reused for the setup and actions mentioned in the feature steps with dependency injection, which allows a true BDD just-enough specification of the requirements without maintaining any context object containing the side effects of the Gherkin imperative declarations.

pip install pytest-bdd

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

publish_article.feature:

Feature: Blog
    A site where you can publish your articles.

Scenario: Publishing the article
    Given I'm an author user
    And I have an article
    When I go to the article page
    And I press the publish button
    Then I should not see the error message
    And the article should be published  # Note: will query the database

test_publish_article.py:

from pytest_bdd import scenario, given, when, then

@scenario('publish_article.feature', 'Publishing the article')
def test_publish():
    pass


@given('I have an article')
def article(author):
    return create_test_article(author=author)


@when('I go to the article page')
def go_to_article(article, browser):
    browser.visit(urljoin(browser.url, '/manage/articles/{0}/'.format(article.id)))


@when('I press the publish button')
def publish_article(browser):
    browser.find_by_css('button[name=publish]').first.click()


@then('I should not see the error message')
def no_error_message(browser):
    with pytest.raises(ElementDoesNotExist):
        browser.find_by_css('.message.error').first


@then('And the article should be published')
def article_is_published(article):
    article.refresh()  # Refresh the object in the SQLAlchemy session
    assert article.is_published

Sometimes it is needed to declare the same fixtures or steps with the different names for better readability. In order to use the same step function with multiple step names simply decorate it multiple times:

@given('I have an article')
@given('there\'s an article')
def article(author):
    return create_test_article(author=author)

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

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

Scenario: I'm the author
    Given I'm an author
    And I have an article


Scenario: I'm the admin
    Given I'm the admin
    And there is an article

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! Important thing that argumented step names are not just strings but regular expressions.

Example:

Scenario: Arguments for given, when, thens
    Given there are 5 cucumbers

    When I eat 3 cucumbers
    And I eat 2 cucumbers

    Then I should have 0 cucumbers

The code will look like:

import re
from pytest_bdd import scenario, given, when, then


@scenario('arguments.feature', 'Arguments for given, when, thens')
def test_arguments():
    pass


@given(re.compile('there are (?P<start>\d+) cucumbers'), converters=dict(start=int))
def start_cucumbers(start):
    return dict(start=start, eat=0)


@when(re.compile('I eat (?P<eat>\d+) cucumbers'), converters=dict(eat=int))
def eat_cucumbers(start_cucumbers, eat):
    start_cucumbers['eat'] += eat


@then(re.compile('I should have (?P<left>\d+) cucumbers'), converters=dict(left=int))
def should_have_left_cucumbers(start_cucumbers, start, left):
    assert start_cucumbers['start'] == start
    assert start - start_cucumbers['eat'] == left

Example code also shows possibility to pass argument converters which may be useful if you need argument types different than strings.

As Gherkin, pytest-bdd supports multiline steps (aka PyStrings). But in much cleaner and powerful way:

Scenario: Multiline step using sub indentation
    Given I have a step with:
        Some
        Extra
        Lines
    Then the text should be parsed with correct indentation

Step is considered as multiline one, if the next line(s) after it's first line, is indented relatively to the first line. The step name is then simply extended by adding futher lines with newlines. In the example above, the Given step name will be:

"""I have a step with:\nSome\nExtra\nLines"""

You can of course register step using full name (including the newlines), but it seems more practical to use step arguments and capture lines after first line (or some subset of them) into the argument:

import re

from pytest_bdd import given, then, scenario


@scenario(
    'multiline.feature',
    'Multiline step using sub indentation',
)
def test_multiline():
    pass


@given(re.compile(r'I have a step with:\n(?P<text>.+)', re.DOTALL))
def i_have_text(text):
    return text


@then('the text should be parsed with correct indentation')
def eat_cucumbers(i_have_text, text):
    assert i_have_text == text == """Some
Extra
Lines"""

Pay attention to the re.DOTALL option used for step registration. When used, .+ will also capture newlines.

Scenario decorator can accept such optional keyword arguments:

• encoding - decode content of feature file in specific encoding. UTF-8 is default.
• example_converters - mapping to pass functions to convert example values provided in feature files.

Scenarios can be parametrized to cover few cases. In Gherkin the variable templates are written using corner braces as <somevalue>. Scenario outlines are supported by pytest-bdd exactly as it's described in be behave docs.

Example:

Scenario Outline: Outlined given, when, thens
    Given there are <start> cucumbers
    When I eat <eat> cucumbers
    Then I should have <left> cucumbers

    Examples:
    | start | eat | left |
    |  12   |  5  |  7   |

pytest-bdd feature file format also supports example tables in different way:

Scenario Outline: Outlined given, when, thens
    Given there are <start> cucumbers
    When I eat <eat> cucumbers
    Then I should have <left> cucumbers

    Examples: Vertical
    | start | 12 | 2 |
    | eat   | 5  | 1 |
    | left  | 7  | 1 |

This form allows to have tables with lots of columns keeping the maximum text width predictable without significant readability change.

The code will look like:

from pytest_bdd import given, when, then, scenario


@scenario(
    'outline.feature',
    'Outlined given, when, thens',
    example_converters=dict(start=int, eat=float, left=str)
)
def test_outlined():
    pass


@given('there are <start> cucumbers')
def start_cucumbers(start):
    assert isinstance(start, int)
    return dict(start=start)


@when('I eat <eat> cucumbers')
def eat_cucumbers(start_cucumbers, eat):
    assert isinstance(eat, float)
    start_cucumbers['eat'] = eat


@then('I should have <left> cucumbers')
def should_have_left_cucumbers(start_cucumbers, start, eat, left):
    assert isinstance(left, str)
    assert start - eat == int(left)
    assert start_cucumbers['start'] == start
    assert start_cucumbers['eat'] == eat

Example code also shows possibility to pass example converters which may be useful if you need parameter types different than strings.

It's also possible to parametrize the scenario on the python side. The reason for this is that it is sometimes not needed to mention example table for every scenario.

The code will look like:

import pytest
from pytest_bdd import mark, given, when, then


# Here we use pytest to parametrize the test with the parameters table
@pytest.mark.parametrize(
    ['start', 'eat', 'left'],
    [(12, 5, 7)])
@mark.scenario(
    'parametrized.feature',
    'Parametrized given, when, thens',
)
# Note that we should take the same arguments in the test function that we use
# for the test parametrization either directly or indirectly (fixtures depend on them).
def test_parametrized(start, eat, left):
    """We don't need to do anything here, everything will be managed by the scenario decorator."""


@given('there are <start> cucumbers')
def start_cucumbers(start):
    return dict(start=start)


@when('I eat <eat> cucumbers')
def eat_cucumbers(start_cucumbers, start, eat):
    start_cucumbers['eat'] = eat


@then('I should have <left> cucumbers')
def should_have_left_cucumbers(start_cucumbers, start, eat, left):
    assert start - eat == left
    assert start_cucumbers['start'] == start
    assert start_cucumbers['eat'] == eat

The significant downside of this approach is inability to see the test table from the feature file.

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

@given('I have a beautiful article')
def article():
    return Article(is_beautiful=True)

This also declares a PyTest fixture "article" and any other step can depend on it.

Given I have a beautiful article
When I publish this article

When step is referring the article to publish it.

@when('I publish this article')
def publish_article(article):
    article.publish()

Many other BDD toolkits operate a global context and put the side effects there. This makes it very difficult to implement the steps, because the dependencies appear only as the side-effects in the 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 on and the PyTest will make sure to provide it.

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

Given I have a beautiful article
And my article is published

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

given('I have a beautiful article', fixture='article')

@given('my article is published')
def published_article(article):
    article.publish()
    return article

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

Fixtures are evaluated only once within the PyTest scope and their values are cached. In case of Given steps and the step arguments mentioning the same given step makes no sense. It won't be executed second time.

Given I have a beautiful article
And some other thing
And I have a beautiful article  # Won't be executed, exception is raised

pytest-bdd will raise an exception even in the case of the steps that use regular expression patterns to get arguments.

Given I have 1 cucumbers
And I have 2 cucumbers  # Exception is raised

Will raise an exception if the step is using the regular expression pattern.

@given(re.compile('I have (?P<n>\d+) cucumbers'))
def cucumbers(n):
    return create_cucumbers(n)

Sometimes scenarios define new names for the fixture that can be inherited. Fixtures can be reused with other names using given():

given('I have beautiful article', fixture='article')

It is possible to define some common steps in the parent conftest.py and simply expect them in the child test file.

common_steps.feature:

Scenario: All steps are declared in the conftest
    Given I have a bar
    Then bar should have value "bar"

conftest.py:

from pytest_bdd import given, then


@given('I have a bar')
def bar():
    return 'bar'


@then('bar should have value "bar"')
def bar_is_bar(bar):
    assert bar == 'bar'

test_common.py:

@scenario('common_steps.feature', 'All steps are declared in the conftest')
def test_conftest():
    pass

There are no definitions of the steps in the test file. They were collected from the parent conftests.

But default, pytest-bdd will use current module’s path as base path for finding feature files, but this behaviour can be changed by having fixture named ‘pytestbdd_feature_base_dir’ which should return the new base path.

test_publish_article.py:

import pytest
from pytest_bdd import scenario


@pytest.fixture
def pytestbdd_feature_base_dir():
    return '/home/user/projects/foo.bar/features'


@scenario('publish_article.feature', 'Publishing the article')
def test_publish():
    pass

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

For example:

test_publish_article.py:

from functools import partial

import pytest_bdd


scenario = partial(pytest_bdd.scenario, '/path/to/publish_article.feature')


@scenario('Publishing the article')
def test_publish():
    pass


@scenario('Publishing the article as unprivileged user')
def test_publish_unprivileged():
    pass

You can learn more about functools.partial in the Python docs.

pytest-bdd exposes several pytest hooks which might be helpful building useful reporting, visualization, etc on top of it:

• pytest_bdd_before_step(request, feature, scenario, step, step_func, step_func_args) - Called before step function is executed
• pytest_bdd_after_step(request, feature, scenario, step, step_func, step_func_args) - Called after step function is successfully executed
• pytest_bdd_step_error(request, feature, scenario, step, step_func, step_func_args, exception) - Called when step function failed to execute
• pytest_bdd_step_validation_error(request, feature, scenario, step, step_func, step_func_args, exception) - Called when step failed to validate
• 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
  • pytest splinter integration for the real browser testing

In version 2.0.0, the backwards-incompartible change was introduced: scenario function can now only be used as a decorator. Reasons for that:

• test code readability is much higher using normal python function syntax;
• pytest-bdd internals are much cleaner and shorter when using single approach instead of supporting two;

* after moving to parsing-on-import-time approach for feature files, it's not possible to detect whether it's a

decorator more or not, so to support it along with functional approach there needed to be special parameter for that, which is also a backwards-incompartible change.

To help users migrate to newer version, there's migration console script provided with migrate extra:

# install extra for migration
pip install pytest-bdd[migrate]

# run migration script
pytestbdd_migrate_tests <your test folder>

Under the hood the script does the replacement from this:

test_function = scenario('publish_article.feature', 'Publishing the article')

to this:

@scenario('publish_article.feature', 'Publishing the article')
def test_function():
    pass

This software is licensed under the MIT license.

© 2013 Oleg Pidsadnyi