.. _api:

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

.. note::

   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:

.. code-block:: python

    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.

.. _`full list of variables imported`: #from-behave-import-*

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:

.. code-block:: python

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


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

.. code-block:: gherkin

 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`_.

.. _`global variables`: #step-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:

.. code-block:: gherkin

  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":

.. code-block:: python

    @given('some other known state')
    def step_impl(context):
        set_up(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 `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`.

.. _`parameters`: tutorial.html#step-parameters


.. autofunction:: behave.use_step_matcher

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

.. autofunction:: behave.register_type

.. hidden:

    # -- SUPERCEEDED BY: behave.register_type documentation
    An example of this in action could be, in steps.py:

    .. code-block:: python

        from behave import register_type
        register_type(custom=lambda s: s.upper())

        @given('a string {param:custom} a custom type')
        def step_impl(context, param):
            assert param.isupper()

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
   :members:

.. autoclass:: behave.model_core.Argument

.. autoclass:: behave.matchers.Match


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:

.. code-block:: python

    @when('I do the same thing as before')
    def step_impl(context):
        context.execute_steps(u'''
            when I press the big red button
             and I duck
        ''')

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


from behave import *
--------------------

The import statement:

.. code-block:: python

    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 environment.py 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:

  .. code-block:: python

      # -- ASSUMING: tags @browser.chrome or @browser.any are used.
      if tag.startswith("browser."):
          browser_type = tag.replace("browser.", "", 1)
          if browser_type == "chrome":
              context.browser = webdriver.Chrome()
          else:
              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:

.. code-block:: python

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

        # -- 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:

.. code-block:: python

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

    @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
   :members:

.. autoclass:: behave.runner.ContextMaskWarning


Fixtures
================

.. excluded:

    .. automodule:: behave.fixture

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

.. parsed-literal::

    before_all
    for feature in all_features:
        before_feature
        for scenario in feature.scenarios:
            before_scenario
            for step in scenario.steps:
                before_step
                    step.run()
                after_step
            after_scenario
        after_feature
    after_all

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:

.. parsed-literal::

    before_all
    for feature in all_features:
        before_feature
        for outline in feature.scenarios:
            for scenario in outline.scenarios:
                before_scenario
                for step in scenario.steps:
                    before_step
                        step.run()
                    after_step
                after_scenario
        after_feature
    after_all


Model Objects
=============

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

**keyword**
    "Feature", "Scenario", "Given", etc.

**name**
    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:

.. parsed-literal::

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

        :class:`~behave.model.Background`
            :class:`~behave.model.Step`
                :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.Step`
                :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.Step`
                :class:`~behave.model.Table` (as :py:attr:`Step.table`)
                MultiLineText (as :py:attr:`Step.text`)
            :class:`~behave.model.Examples`
                :class:`~behave.model.Table`


.. 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
   :members:

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


.. include:: _common_extlinks.rst