Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
440 lines (292 sloc) 12.9 KB

Behave API Reference

This reference is meant for people actually writing step implementations for feature tests. It contains way more information than a typical step implementation will need: most implementations will only need to look at the basic implementation of step functions and maybe environment file functions.

The model stuff is for people getting really serious about their step implementations.


Anywhere this document says "string" it means "unicode string" in Python 2.x

behave works exclusively with unicode strings internally.

Step Functions

Step functions are implemented in the Python modules present in your "steps" directory. All Python files (files ending in ".py") in that directory will be imported to find step implementations. They are all loaded before behave starts executing your feature tests.

Step functions are identified using step decorators. All step implementations should normally start with the import line:

from behave import *

This line imports several decorators defined by behave to allow you to identify your step functions. These are available in both PEP-8 (all lowercase) and traditional (title case) versions: "given", "when", "then" and the generic "step". See the full list of variables imported in the above statement.

The decorators all take a single string argument: the string to match against the feature file step text exactly. So the following step implementation code:

@given(u'some known state')
def step_impl(context):
    setup_something(some, state)

will match the "Given" step from the following feature:

Scenario: test something
  Given some known state
  Then  some observed outcome.

You don't need to import the decorators: they're automatically available to your step implementation modules as global variables.

Steps beginning with "and" or "but" in the feature file are renamed to take the name of their preceding keyword, so given the following feature file:

Given some known state
  and some other known state
 when some action is taken
 then some outcome is observed
  but some other outcome is not observed.

the first "and" step will be renamed internally to "given" and behave will look for a step implementation decorated with either "given" or "step":

@given(u'some other known state')
def step_impl(context):
    setup_something(some, other, state)

and similarly the "but" would be renamed internally to "then". Multiple "and" or "but" steps in a row would inherit the non-"and" or "but" keyword.

The function decorated by the step decorator will be passed at least one argument. The first argument is always the :class:`~behave.runner.Context` variable. Additional arguments come from step parameters, if any.

Step Parameters

You may additionally use :ref:`parameters <docid.tutorial.step-parameters>` in your step names. These will be handled by either the default simple parser (:pypi:`parse`), its extension "cfparse" or by regular expressions if you invoke :func:`~behave.use_step_matcher`.

.. autofunction:: behave.use_step_matcher

You may add new types to the default parser by invoking :func:`~behave.register_type`.

.. autofunction:: behave.register_type

You may define a new parameter matcher by subclassing :class:`behave.matchers.Matcher` and registering it with :attr:`behave.matchers.matcher_mapping` which is a dictionary of "matcher name" to :class:`~behave.matchers.Matcher` class.

.. autoclass:: behave.matchers.Matcher

.. autoclass:: behave.model_core.Argument

.. autoclass:: behave.matchers.Match

Step Macro: Calling Steps From Other Steps

If you find you'd like your step implementation to invoke another step you may do so with the :class:`~behave.runner.Context` method :func:`~behave.runner.Context.execute_steps`.

This function allows you to, for example:

@when(u'I do the same thing as before with the {color:w} button')
def step_impl(context, color):
        When I press the big {color} button
         And I duck

This will cause the "when I do the same thing as before with the red button" step to execute the other two steps as though they had also appeared in the scenario file.

from behave import *

The import statement:

from behave import *

is written to introduce a restricted set of variables into your code:

Name Kind Description
given, when, then, step Decorator Decorators for step implementations.
use_step_matcher(name) Function Selects current step matcher (parser).
register_type(Type=func) Function Registers a type converter.

See also the description in step parameters.

Environment File Functions

The module may define code to run before and after certain events during your testing:

before_step(context, step), after_step(context, step)
These run before and after every step. The step passed in is an instance of :class:`~behave.model.Step`.
before_scenario(context, scenario), after_scenario(context, scenario)
These run before and after each scenario is run. The scenario passed in is an instance of :class:`~behave.model.Scenario`.
before_feature(context, feature), after_feature(context, feature)
These run before and after each feature file is exercised. The feature passed in is an instance of :class:`~behave.model.Feature`.
before_tag(context, tag), after_tag(context, tag)

These run before and after a section tagged with the given name. They are invoked for each tag encountered in the order they're found in the feature file. See :ref:`controlling things with tags`. The tag passed in is an instance of :class:`~behave.model.Tag` and because it's a subclass of string you can do simple tests like:

# -- ASSUMING: tags or @browser.any are used.
# BETTER: Use Fixture for this example.
def before_tag(context, tag):
    if tag.startswith("browser."):
        browser_type = tag.replace("browser.", "", 1)
        if browser_type == "chrome":
            context.browser = webdriver.Chrome()
            context.browser = webdriver.PlainVanilla()
before_all(context), after_all(context)
These run before and after the whole shooting match.

Some Useful Environment Ideas

Here's some ideas for things you could use the environment for.

Logging Setup

The following recipe works in all cases (log-capture on or off). If you want to use/configure logging, you should use the following snippet:

# -- FILE:features/
def before_all(context):
    # -- SET LOG LEVEL: behave --logging-level=ERROR ...
    # on behave command-line or in "behave.ini".

    # -- ALTERNATIVE: Setup logging with a configuration file.
    # context.config.setup_logging(configfile="behave_logging.ini")

Capture Logging in Hooks

If you wish to capture any logging generated during an environment hook function's invocation, you may use the :func:`~behave.log_capture.capture` decorator, like:

# -- FILE:features/
from behave.log_capture import capture

def after_scenario(context):

This will capture any logging done during the call to after_scenario and print it out.

Detecting that user code overwrites behave Context attributes

The context variable in all cases is an instance of :class:`behave.runner.Context`.

.. autoclass:: behave.runner.Context

.. autoclass:: behave.runner.ContextMaskWarning


Provide a Fixture

.. autofunction:: behave.fixture.fixture

Use Fixtures

.. autofunction:: behave.fixture.use_fixture

.. autofunction:: behave.fixture.use_fixture_by_tag

.. autofunction:: behave.fixture.use_composite_fixture_with

Runner Operation

Given all the code that could be run by behave, this is the order in which that code is invoked (if they exist.)

for feature in all_features:
    for scenario in feature.scenarios:
        for step in scenario.steps:

If the feature contains scenario outlines then there is an additional loop over all the scenarios in the outline making the running look like this:

for feature in all_features:
    for outline in feature.scenarios:
        for scenario in outline.scenarios:
            for step in scenario.steps:

Model Objects

The feature, scenario and step objects represent the information parsed from the feature file. They have a number of common attributes:

"Feature", "Scenario", "Given", etc.
The name of the step (the text after the keyword.)
filename and line
The file name (or "<string>") and line number of the statement.

The structure of model objects parsed from a feature file will typically be:

:class:`~behave.model.Tag` (as :py:attr:`Feature.tags`)
:class:`~behave.model.Feature` : TaggableModelElement
    Description (as :py:attr:`Feature.description`)

            :class:`~behave.model.Table` (as :py:attr:`Step.table`)
            MultiLineText (as :py:attr:`Step.text`)

    :class:`~behave.model.Tag` (as :py:attr:`Scenario.tags`)
    :class:`~behave.model.Scenario` : TaggableModelElement
        Description (as :py:attr:`Scenario.description`)
            :class:`~behave.model.Table` (as :py:attr:`Step.table`)
            MultiLineText (as :py:attr:`Step.text`)

    :class:`~behave.model.Tag` (as :py:attr:`ScenarioOutline.tags`)
    :class:`~behave.model.ScenarioOutline` : TaggableModelElement
        Description (as :py:attr:`ScenarioOutline.description`)
            :class:`~behave.model.Table` (as :py:attr:`Step.table`)
            MultiLineText (as :py:attr:`Step.text`)
.. autoclass:: behave.model.Feature

.. autoclass:: behave.model.Background

.. autoclass:: behave.model.Scenario

.. autoclass:: behave.model.ScenarioOutline

.. autoclass:: behave.model.Examples

.. autoclass:: behave.model.Tag

.. autoclass:: behave.model.Step

Tables may be associated with either Examples or Steps:

.. autoclass:: behave.model.Table

.. autoclass:: behave.model.Row

And Text may be associated with Steps:

.. autoclass:: behave.model.Text

Logging Capture

The logging capture behave uses by default is implemented by the class :class:`~behave.log_capture.LoggingCapture`. It has methods

.. autoclass:: behave.log_capture.LoggingCapture

The log_capture module also defines a handy logging capture decorator that's intended to be used on your environment file functions.

.. autofunction:: behave.log_capture.capture

You can’t perform that action at this time.