busser-behave 0.1.3

data/vendor/behave/docs/index.rst

@@ -0,0 +1,57 @@
+Welcome to behave!
+==================
+
+behave is behaviour-driven development, Python style.
+
+Behavior-driven development (or BDD) is an agile software development
+technique that encourages collaboration between developers, QA and
+non-technical or business participants in a software project. We have
+a page further describing this :doc:`philosophy <philosophy>`.
+
+:pypi:`behave` uses tests written in a natural language style,
+backed up by Python code.
+
+Once you've :doc:`installed <install>` *behave*, we recommend reading the
+
+  * :doc:`tutorial <tutorial>` first and then
+  * :doc:`feature test setup <gherkin>`,
+  * :doc:`behave API <api>` and
+  * :doc:`related software <related>` (things that you can combine with :pypi:`behave`)
+  * finally: :doc:`how to use and configure <behave>` the :pypi:`behave` tool.
+
+There is also a :doc:`comparison <comparison>` with the other tools available.
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   install
+   tutorial
+   philosophy
+   gherkin
+   behave
+   api
+   django
+   comparison
+   new_and_noteworthy
+   more_info
+   appendix
+
+.. seealso::
+
+    * `behave.example`_: `Behave Examples and Tutorials`_ (HTML)
+    * Peter Parente: `BDD and Behave <http://tott-meetup.readthedocs.org/en/latest/sessions/behave.html>`_ (tutorial)
+
+.. _behave.example: https://github.com/behave/behave.example
+.. _`Behave Examples and Tutorials`: http://behave.github.io/behave.example/
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

data/vendor/behave/docs/install.rst

@@ -0,0 +1,60 @@
+Installation
+============
+
+Using pip (or ...)
+------------------
+
+:Category: Stable version
+:Precondition: :pypi:`pip` (or :pypi:`setuptools`) is installed
+
+Execute the following command to install :pypi:`behave` with :pypi:`pip`:
+
+    pip install behave
+
+To update an already installed :pypi:`behave` version, use:
+
+    pip install -U behave
+
+As an alternative,
+you can also use :pypi:`easy_install <setuptools>` to install :pypi:`behave`::
+
+    easy_install behave         # CASE: New installation.
+    easy_install -U behave      # CASE: Upgrade existing installation.
+
+
+.. hint::
+
+    See also `pip related information`_ for installing Python packages.
+
+.. _`pip related information`:  https://pip.pypa.io/en/latest/installing.html
+
+
+Using a Source Distribution
+---------------------------
+
+After unpacking the :pypi:`behave` source distribution,
+enter the newly created directory "behave-<version>" and run::
+
+    python setup.py install
+
+
+Using the Github Repository
+---------------------------
+
+:Category: Bleading edge
+:Precondition: :pypi:`pip` is installed
+
+Run the following command
+to install the newest version from the `Github repository`_::
+
+
+    pip install git+https://github.com/behave/behave
+
+To install a tagged version from the `Github repository`_, use::
+
+    pip install git+https://github.com/behave/behave@<tag>
+
+where <tag> is the placeholder for an `existing tag`_.
+
+.. _`Github repository`: https://github.com/behave/behave
+.. _`existing tag`:      https://github.com/behave/behave/tags

data/vendor/behave/docs/more_info.rst

@@ -0,0 +1,184 @@
+.. _id.appendix.more_info:
+
+More Information about Behave
+==============================================================================
+
+
+Tutorials
+------------------------------------------------------------------------------
+
+For new users, that want to read, understand and explore the concepts in Gherkin
+and `behave`_ (after reading the behave documentation):
+
+* "`Behave by Example <http://behave.github.io/behave.example/>`_"
+  (on `github <https://github.com/behave/behave.example>`_)
+
+The following small tutorials provide an introduction how you use `behave`_
+in a specific testing domain:
+
+* Phillip Johnson, `Getting Started with Behavior Testing in Python with Behave`_
+* `Bdd with Python, Behave and WebDriver`_
+* Wayne Witzel III, `Using Behave with Pyramid`_, 2014-01-10.
+
+.. _`Getting Started with Behavior Testing in Python with Behave`: https://semaphoreci.com/community/tutorials/getting-started-with-behavior-testing-in-python-with-behave
+.. _`Bdd with Python, Behave and WebDriver`: https://testingbot.com/support/getting-started/behave.html
+.. _`Using Behave with Pyramid`:    https://www.safaribooksonline.com/blog/2014/01/10/using-behave-with-pyramid/
+
+.. warning::
+
+    A word of caution if you are new to **"behaviour-driven development" (BDD)**.
+    In general, you want to avoid "user interface" (UI) details in your
+    scenarios, because they describe **how something is implemented**
+    (in this case the UI itself), like:
+
+    * ``press this button``
+    * then ``enter this text into the text field``
+    * ...
+
+    In **BDD** (or testing in general), you should describe **what should be done**
+    (meaning the intention). This will make your scenarios much more robust
+    and stable because you can change the underlying implementation of:
+
+    * the "system under test" (SUT) or
+    * the test automation layer, that interacts with the SUT.
+
+    without changing the scenarios.
+
+
+Books
+------------------------------------------------------------------------------
+
+`Behave`_ is covered in the following books:
+
+.. [TDD-Python] Harry Percival,
+    `Test-Driven Web Development with Python`_, O'Reilly, June 2014,
+    `Appendix E: BDD <http://chimera.labs.oreilly.com/books/1234000000754/ape.html>`_
+    (covers behave)
+
+.. _`Test-Driven Web Development with Python`: http://chimera.labs.oreilly.com/books/1234000000754
+
+
+Presentation Videos
+------------------------------------------------------------------------------
+
+* Benno Rice: `Making Your Application Behave`_ (30min),
+  2012-08-12, PyCon Australia.
+
+* Selenium: `First behave python tuorial with selenium`_ (8min), 2015-01-28,
+  http://www.seleniumframework.com/python-basic/first-behave-gherkin/
+
+* Jessica Ingrasselino: `Automation with Python and Behave`_ (67min), 2015-12-16
+
+* `Selenium Python Webdriver Tutorial - Behave (BDD)`_ (14min), 2016-01-21
+
+
+.. hidden:
+
+    PREPARED:
+    ---------------------
+
+    .. ifconfig:: not supports_video
+
+        * Benno Rice: `Making Your Application Behave`_ (30min),
+          PyCon Australia, 2012-08-12
+
+        * Selenium: `First behave python tuorial with selenium`_ (8min), 2015-01-28,
+          http://www.seleniumframework.com/python-basic/first-behave-gherkin/
+
+        * Jessica Ingrasselino: `Automation with Python and Behave`_ (67min), 2015-12-16
+
+        * `Selenium Python Webdriver Tutorial - Behave (BDD)`_ (14min), 2016-01-21
+
+
+        .. hint::
+
+            Manually install `sphinxcontrib-youtube`_
+            (from "youtube" subdirectory in sphinx-extensions bundle)
+            to have embedded videos on this page (when this page is build).
+
+
+    .. ifconfig:: supports_video
+
+        Benno Rice: `Making Your Application Behave`_
+        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+        :Conference: PyCon Australia
+        :Date: 2012-08-12
+        :Duration: 30min
+
+        ..  youtube:: u8BOKuNkmhg
+            :width: 600
+            :height: 400
+
+        Selenium: `First behave python tuorial with selenium`_
+        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+        :Date: 2015-01-28
+        :Duration: 8min
+
+        ..  youtube:: D24_QrGUCFk
+            :width: 600
+            :height: 400
+
+        RELATED: http://www.seleniumframework.com/python-basic/what-is-python/
+
+        Jessica Ingrasselino: `Automation with Python and Behave`_
+        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+        :Date: 2015-12-16
+        :Duration: 67min
+
+        ..  youtube:: e78c7h6DRDQ
+            :width: 600
+            :height: 400
+
+        `Selenium Python Webdriver Tutorial - Behave (BDD)`_
+        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+        :Date: 2016-01-21
+        :Duration: 14min
+
+        ..  youtube:: mextSo0UExc
+            :width: 600
+            :height: 400
+
+
+.. _`Making Your Application Behave`: https://www.youtube.com/watch?v=u8BOKuNkmhg
+.. _`First behave python tuorial with selenium`: https://www.youtube.com/watch?v=D24_QrGUCFk
+.. _`Automation with Python and Behave`: https://www.youtube.com/watch?v=e78c7h6DRDQ
+.. _`Selenium Python Webdriver Tutorial - Behave (BDD)`: https://www.youtube.com/watch?v=mextSo0UExc
+
+.. _sphinxcontrib-youtube: https://bitbucket.org/birkenfeld/sphinx-contrib
+
+
+Tool-oriented Tutorials
+------------------------------------------------------------------------------
+
+JetBrains PyCharm:
+
+* Blog: `In-Depth Screencast on Testing`_ (2016-04-11; video offset=2:10min)
+* Docs: `BDD Testing Framework Support in PyCharm 2016.1
+  <https://www.jetbrains.com/help/pycharm/2016.1/bdd-testing-framework.html>`_
+
+
+.. _`Getting Started with PyCharm`: https://www.youtube.com/playlist?list=PLQ176FUIyIUZ1mwB-uImQE-gmkwzjNLjP
+.. _`PyCharm In-Depth: Testing`: https://youtu.be/nmBbR97Vsv8?list=PLQ176FUIyIUZ1mwB-uImQE-gmkwzjNLjP
+.. _`In-Depth Screencast on Testing`: http://blog.jetbrains.com/pycharm/2016/04/in-depth-screencast-on-testing/
+
+
+
+Find more Information
+------------------------------------------------------------------------------
+
+.. seealso::
+
+    * google:`python-behave examples <https://www.google.com/?q=python-behave%20examples>`_
+    * google:`python-behave tutorials <https://www.google.com/?q=python-behave%20tutorials>`_
+    * google:`python-behave videos <https://www.google.com/?q=python-behave%20videos>`_
+
+
+.. _Behave:     https://github.com/behave/behave
+.. _behave:     https://github.com/behave/behave
+.. _Selenium:   http://docs.seleniumhq.org/
+.. _behave4cmd:     https://github.com/behave/behave4cmd
+.. _behave-django: https://github.com/behave/behave-django

data/vendor/behave/docs/new_and_noteworthy.rst

@@ -0,0 +1,18 @@
+New and Noteworthy
+==============================================================================
+
+In the good tradition of the `Eclipse IDE`_,
+a number of news, changes and improvements are described here to provide
+better background information about what has changed and how to make use of it.
+
+This page orders the information by newest version first.
+
+.. _`Eclipse IDE`:  http://www.eclipse.org/
+
+.. toctree::
+   :maxdepth: 2
+
+   new_and_noteworthy_v1.2.6
+   new_and_noteworthy_v1.2.5
+   new_and_noteworthy_v1.2.4
+

data/vendor/behave/docs/new_and_noteworthy_v1.2.4.rst

@@ -0,0 +1,11 @@
+Noteworthy in Version 1.2.4
+==============================================================================
+
+
+Diagnostics: Start Debugger on Error
+-------------------------------------------------------------------------------
+
+:Since: behave 1.2.4a1
+
+See also :ref:`debug-on-error` .
+

data/vendor/behave/docs/new_and_noteworthy_v1.2.5.rst

@@ -0,0 +1,814 @@
+Noteworthy in Version 1.2.5
+==============================================================================
+
+Scenario Outline Improvements
+-------------------------------------------------------------------------------
+
+.. index::
+    single: ScenarioOutline; name annotation
+    pair:   ScenarioOutline; file location
+
+Better represent Example/Row
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:Since:  behave 1.2.5a1
+:Covers: Name annotation, file location
+
+A scenario outline basically a parametrized scenario template.
+It represents a macro/script that is executed for a data-driven set of examples
+(parametrized data). Therefore, a scenario outline generates several scenarios,
+each representing one example/row combination.
+
+.. code-block:: gherkin
+
+    # -- file:features/xxx.feature
+    Feature:
+      Scenario Outline: Wow            # line 2
+        Given an employee "<name>"
+
+        Examples: Araxas
+          | name  | birthyear |
+          | Alice |  1985     |         # line 7
+          | Bob   |  1975     |         # line 8
+
+        Examples:
+          | name   | birthyear |
+          | Charly |  1995     |        # line 12
+
+
+Up to now, the following scenarios were generated from the scenario outline:
+
+.. code-block:: gherkin
+
+    Scenario Outline: Wow          # features/xxx.feature:2
+      Given an employee "Alice"
+
+    Scenario Outline: Wow          # features/xxx.feature:2
+      Given an employee "Bob"
+
+    Scenario Outline: Wow          # features/xxx.feature:2
+      Given an employee "Charly"
+
+Note that  all generated scenarios had the:
+
+  * same name (scenario_outline.name)
+  * same file location (scenario_outline.file_location)
+
+From now on, the generated scenarios better
+represent the example/row combination within a scenario outline:
+
+.. code-block:: gherkin
+
+    Scenario Outline: Wow -- @1.1 Araxas  # features/xxx.feature:7
+      Given an employee "Alice"
+
+    Scenario Outline: Wow -- @1.2 Araxas  # features/xxx.feature:8
+      Given an employee "Bob"
+
+    Scenario Outline: Wow -- @2.1         # features/xxx.feature:12
+      Given an employee "Charly"
+
+Note that:
+
+  * scenario name is now unique for any examples/row combination
+  * scenario name optionally contains the examples (group) name (if one exists)
+  * each scenario has a unique file location, based on the row's file location
+
+Therefore, each generated scenario from a scenario outline can be selected
+via its file location (and run on its own). In addition, if one fails,
+it is now possible to rerun only the failing example/row combination(s).
+
+The name annoations schema for the generated scenarios from above provides
+the new default name annotation schema.
+It can be adapted/overwritten in "behave.ini":
+
+.. code-block:: ini
+
+    # -- file:behave.ini
+    [behave]
+    scenario_outline_annotation_schema = {name} -- @{row.id} {examples.name}
+
+    # -- REVERT TO: Old naming schema:
+    # scenario_outline_annotation_schema = {name}
+
+
+The following additional placeholders are provided within a
+scenario outline to support this functionality.
+They can be used anywhere within a scenario outline.
+
+=============== ===============================================================
+Placeholder     Description
+=============== ===============================================================
+examples.name   Refers name of the example group, may be an empty string.
+examples.index  Index of the example group (range=1..N).
+row.index       Index of the current row within an example group (range=1..R).
+row.id          Shortcut for schema: "<examples.index>.<row.index>"
+=============== ===============================================================
+
+
+.. index::
+    single: ScenarioOutline; name with placeholders
+
+Name may contain Placeholders
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:Since: behave 1.2.5a1
+
+A scenario outline can now use placeholders from example/rows in its name
+or its examples name. When the scenarios a generated,
+these placeholders will be replaced with the values of the example/row.
+
+Up to now this behavior did only apply to steps of a scenario outline.
+
+EXAMPLE:
+
+.. code-block:: gherkin
+
+    # -- file:features/xxx.feature
+    Feature:
+      Scenario Outline: Wow <name>-<birthyear>  # line 2
+        Given an employee "<name>"
+
+        Examples:
+          | name  | birthyear |
+          | Alice |  1985     |         # line 7
+          | Bob   |  1975     |         # line 8
+
+        Examples: Benares-<ID>
+          | name   | birthyear | ID |
+          | Charly |  1995     | 42 |   # line 12
+
+
+This leads to the following generated scenarios,
+one for each examples/row combination:
+
+.. code-block:: gherkin
+
+    Scenario Outline: Wow Alice-1985 -- @1.1         # features/xxx.feature:7
+      Given an employee "Alice"
+
+    Scenario Outline: Wow Bob-1975 -- @1.2           # features/xxx.feature:8
+      Given an employee "Bob"
+
+    Scenario Outline: Wow Charly-1885 -- @2.1 Benares-42 # features/xxx.feature:12
+      Given an employee "Charly"
+
+.. index::
+    pair:   ScenarioOutline; tags with placeholders
+
+Tags may contain Placeholders
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:Since: behave 1.2.5a1
+
+Tags from a Scenario Outline are also part of the parametrized template.
+Therefore, you may also use placeholders in the tags of a Scenario Outline.
+
+.. note::
+
+    * Placeholder names, that are used in tags, should not contain whitespace.
+    * Placeholder values, that are used in tags, are transformed to contain
+      no whitespace characters.
+
+
+EXAMPLE:
+
+.. code-block:: gherkin
+
+    # -- file:features/xxx.feature
+    Feature:
+
+      @foo.group<examples.index>
+      @foo.row<row.id>
+      @foo.name.<name>
+      Scenario Outline: Wow            # line 6
+        Given an employee "<name>"
+
+        Examples: Araxas
+          | name  | birthyear |
+          | Alice |  1985     |         # line 11
+          | Bob   |  1975     |         # line 12
+
+        Examples: Benares
+          | name   | birthyear | ID |
+          | Charly |  1995     | 42 |   # line 16
+
+
+This leads to the following generated scenarios,
+one for each examples/row combination:
+
+.. code-block:: gherkin
+
+    @foo.group1 @foo.row1.1 @foo.name.Alice
+    Scenario Outline: Wow -- @1.1 Araxas   # features/xxx.feature:11
+      Given an employee "Alice"
+
+    @foo.group1 @foo.row1.2 @foo.name.Bob
+    Scenario Outline: Wow -- @1.2 Araxas   # features/xxx.feature:12
+      Given an employee "Bob"
+
+    @foo.group2 @foo.row2.1 @foo.name.Charly
+    Scenario Outline: Wow -- @2.1 Benares  # features/xxx.feature:16
+      Given an employee "Charly"
+
+.. index::
+    single: ScenarioOutline; select-group-by-tag
+
+It is now possible to run only the examples group "Araxas" (examples group 1)
+by using the select-by-tag mechanism:
+
+.. code-block:: sh
+
+    $ behave --tags=@foo.group1 -f progress3 features/xxx.feature
+    ...  # features/xxx.feature
+      Wow -- @1.1 Araxas  .
+      Wow -- @1.2 Araxas  .
+
+
+.. index::
+    single: ScenarioOutline; select-group-by-name
+
+Run examples group via select-by-name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:Since: behave 1.2.5a1
+
+The improvements on unique generated scenario names for a scenario outline
+(with name annotation) can now be used to run all rows of one examples group.
+
+EXAMPLE:
+
+.. code-block:: gherkin
+
+    # -- file:features/xxx.feature
+    Feature:
+      Scenario Outline: Wow            # line 2
+        Given an employee "<name>"
+
+        Examples: Araxas
+          | name  | birthyear |
+          | Alice |  1985     |         # line 7
+          | Bob   |  1975     |         # line 8
+
+        Examples: Benares
+          | name   | birthyear |
+          | Charly |  1995     |        # line 12
+
+
+This leads to the following generated scenarios (when the feature is executed):
+
+.. code-block:: gherkin
+
+    Scenario Outline: Wow -- @1.1 Araxas  # features/xxx.feature:7
+      Given an employee "Alice"
+
+    Scenario Outline: Wow -- @1.2 Araxas   # features/xxx.feature:8
+      Given an employee "Bob"
+
+    Scenario Outline: Wow -- @2.1 Benares  # features/xxx.feature:12
+      Given an employee "Charly"
+
+
+You can now run all rows of the "Araxas" examples (group)
+by selecting it by name (name part or regular expression):
+
+.. code-block:: sh
+
+    $ behave --name=Araxas -f progress3 features/xxx.feature
+    ...  # features/xxx.feature
+      Wow -- @1.1 Araxas  .
+      Wow -- @1.2 Araxas  .
+
+    $ behave --name='-- @.* Araxas' -f progress3 features/xxx.feature
+    ...  # features/xxx.feature
+      Wow -- @1.1 Araxas  .
+      Wow -- @1.2 Araxas  .
+
+
+.. index::
+    single: Scenario; exclude from test run
+    pair:   Scenario; exclude from test run
+    single: Feature; exclude from test run
+    pair:   Feature; exclude from test run
+
+
+Exclude Feature/Scenario at Runtime
+-------------------------------------------------------------------------------
+
+:Since:  behave 1.2.5a1
+
+A test writer can now provide a runtime decision logic to exclude
+a feature, scenario or scenario outline from a test run
+within the following hooks:
+
+  * ``before_feature()`` for a feature
+  * ``before_scenario()`` for a scenario
+  * step implementation (normally only: given step)
+
+by using the ``skip()`` method before a feature or scenario is run.
+
+.. code-block:: python
+
+    # -- FILE: features/environment.py
+    # EXAMPLE 1: Exclude scenario from run-set at runtime.
+    import sys
+
+    def should_exclude_scenario(scenario):
+        # -- RUNTIME DECISION LOGIC: Will exclude
+        #  * Scenario: Alice
+        #  * Scenario: Alice in Wonderland
+        #  * Scenario: Bob and Alice2
+        return "Alice" in scenario.name
+
+    def before_scenario(context, scenario):
+        if should_exclude_scenario(scenario):
+            scenario.skip()  #< EXCLUDE FROM RUN-SET.
+            # -- OR WITH REASON:
+            # reason = "RUNTIME-EXCLUDED"
+            # scenario.skip(reason)
+
+.. code-block:: python
+
+    # -- FILE: features/steps/my_steps.py
+    # EXAMPLE 2: Skip remaining steps in step implementation.
+    from behave import given
+
+    @given('the assumption "{assumption}" is met')
+    def step_check_assumption(context, assumption):
+        if not is_assumption_valid(assumption):
+            # -- SKIP: Remaining steps in current scenario.
+            context.scenario.skip("OOPS: Assumption not met")
+            return
+
+        # -- NORMAL CASE:
+        ...
+
+
+
+.. index::
+    single: Stage
+    pair: Stage; Test Stage
+
+Test Stages
+-------------------------------------------------------------------------------
+
+:Since:  behave 1.2.5a1
+:Intention: Use different Step Implementations for Each Stage
+
+A test stage allows the user to provide different step and environment
+implementation for each stage. Examples for test stages are:
+
+   * develop (example: development environment with simple database)
+   * product (example: use the real product and its database)
+   * systemint (system integration)
+   * ...
+
+Each test stage may have a different test environment and needs to
+fulfill different testing constraints.
+
+EXAMPLE DIRECTORY LAYOUT (with ``stage=testlab`` and default stage)::
+
+  features/
+    +-- steps/                # -- Step implementations for default stage.
+    |   +-- foo_steps.py
+    +-- testlab_steps/        # -- Step implementations for stage=testlab.
+    |   +-- foo_steps.py
+    +-- environment.py          # -- Environment for default stage.
+    +-- testlab_environment.py  # -- Environment for stage=testlab.
+    +-- *.feature
+
+To use the ``stage=testlab``, you run behave with::
+
+
+    behave --stage=testlab ...
+
+or define the environment variable ``BEHAVE_STAGE=testlab``.
+
+
+.. _userdata:
+.. index::
+    single: userdata
+    pair: userdata; user-specific configuration data
+
+Userdata
+-------------------------------------------------------------------------------
+
+:Since:  behave 1.2.5a1
+:Intention: User-specific Configuration Data
+
+The userdata functionality allows a user to provide its own configuration data:
+
+  * as command-line option ``-D name=value`` or ``--define name=value``
+  * with the behave configuration file in section ``behave.userdata``
+  * load more configuration data in ``before_all()`` hook
+
+.. code-block:: ini
+
+    # -- FILE: behave.ini
+    [behave.userdata]
+    browser = firefox
+    server  = asterix
+
+.. note::
+
+    Command-line definitions override userdata definitions in the
+    configuration file.
+
+    If the command-line contains no value part, like in ``-D NEEDS_CLEANUP``,
+    its value is ``"true"``.
+
+
+The userdata settings can be accessed as dictionary in hooks and steps
+by using the ``context.config.userdata`` dictionary.
+
+.. code-block:: python
+
+    # -- FILE: features/environment.py
+    def before_all(context):
+        browser = context.config.userdata.get("browser", "chrome")
+        setup_browser(browser)
+
+.. code-block:: python
+
+    # -- FILE: features/steps/userdata_example_steps.py
+    @given('I setup the system with the user-specified server"')
+    def step_setup_system_with_userdata_server(context):
+        server_host = context.config.userdata.get("server", "beatrix")
+        context.xxx_client = xxx_protocol.connect(server_host)
+
+.. code-block:: sh
+
+    # -- ADAPT TEST-RUN: With user-specific data settings.
+    # SHELL:
+    behave -D server=obelix features/
+    behave --define server=obelix features/
+
+Other examples for user-specific data are:
+
+   * Passing a URL to an external resource that should be used in the tests
+
+   * Turning off cleanup mechanisms implemented in environment hooks,
+     for debugging purposes.
+
+
+Type Converters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The userdata object provides basic support for "type conversion on demand",
+similar to the :mod:`configparser` module. The following type conversion
+methods are provided:
+
+  * ``Userdata.getint(name, default=0)``
+  * ``Userdata.getfloat(name, default=0.0)``
+  * ``Userdata.getbool(name, default=False)``
+  * ``Userdata.getas(convert_func, name, default=None, ...)``
+
+Type conversion may raise a ``ValueError`` exception if the conversion fails.
+
+The following example shows how the type converter functions for integers are used:
+
+.. code-block:: python
+
+    # -- FILE: features/environment.py
+    def before_all(context):
+        userdata = context.config.userdata
+        server_name  = userdata.get("server", "beatrix")
+        int_number   = userdata.getint("port", 80)
+        bool_answer  = userdata.getbool("are_you_sure", True)
+        float_number = userdata.getfloat("temperature_threshold", 50.0)
+        ...
+
+.. hidden:
+
+  * :py:meth:`behave.configuration.Userdata.getint()`
+  * :py:meth:`behave.configuration.Userdata.getfloat()`
+  * :py:meth:`behave.configuration.Userdata.getbool()`
+  * :py:meth:`behave.configuration.Userdata.getas()`
+
+
+Advanced Cases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The last section described the basic use cases of userdata.
+For more complicated cases, it is better to provide your own configuration setup
+in the ``before_all()`` hook.
+
+This section describes how to load a JSON configuration file and store its
+data in the ``userdata`` dictionary.
+
+.. code-block:: py
+
+    # -- FILE: features/environment.py
+    import json
+    import os.path
+
+    def before_all(context):
+        """Load and update userdata from JSON configuration file."""
+        userdata = context.config.userdata
+        configfile = userdata.get("configfile", "userconfig.json")
+        if os.path.exists(configfile):
+            assert configfile.endswith(".json")
+            more_userdata = json.load(open(configfile))
+            context.config.update_userdata(more_userdata)
+            # -- NOTE: Reapplies userdata_defines from command-line, too.
+
+
+Provide the file "userconfig.json" with:
+
+.. code-block:: json
+
+    {
+        "browser": "firefox",
+        "server":  "asterix",
+        "count":   42,
+        "cleanup": true
+    }
+
+Other advanced use cases:
+
+  * support configuration profiles via cmdline "... -D PROFILE=xxx ..."
+    (uses profile-specific configuration file or profile-specific config section)
+  * provide test stage specific configuration data
+
+
+.. index::
+    single: Active Tags
+
+Active Tags
+-------------------------------------------------------------------------------
+
+:Since:  behave 1.2.5a1
+
+**Active tags** are used when it is necessary to decide at runtime
+which features or scenarios should run (and which should be skipped).
+The runtime decision is based on which:
+
+  * platform the tests run (like: Windows, Linux, MACOSX, ...)
+  * runtime environment resources are available (by querying the "testbed")
+  * runtime environment resources should be used (via `userdata`_ or ...)
+
+Therefore, for *active tags* it is decided at runtime if a tag is enabled or
+disabled. The runtime decision logic excludes features/scenarios with disabled
+active tags before they are run.
+
+.. note::
+
+  The active tag mechanism is applied after the normal tag filtering
+  that is configured on the command-line.
+
+  The active tag mechanism uses  the :class:`~behave.tag_matcher.ActiveTagMatcher`
+  for its core functionality.
+
+
+.. index::
+    single: Active Tag Logic
+
+Active Tag Logic
+~~~~~~~~~~~~~~~~~
+
+  * A (positive) active tag is enabled,
+    if its value matches the current value of its category.
+
+  * A negated active tag (starting with "not") is enabled,
+    if its value does not match the current value of its category.
+
+  * A sequence of active tags is enabled,
+    if all its active tags are enabled (logical-and operation).
+
+
+.. index::
+    single: Active Tag Schema
+    pair:   @active.with_{category}={value}; active tag schema (dialect 1)
+    pair:   @not_active.with_{category}={value}; active tag schema (dialect 1)
+    pair:   @use.with_{category}={value}; active tag schema (dialect 2)
+    pair:   @not.with_{category}={value}; active tag schema (dialect 2)
+    pair:   @only.with_{category}={value}; active tag schema (dialect 2)
+
+Active Tag Schema
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following two tag schemas are supported for active tags (by default).
+
+**Dialect 1:**
+
+  * @active.with_{category}={value}
+  * @not_active.with_{category}={value}
+
+**Dialect 2:**
+
+  * @use.with_{category}={value}
+  * @not.with_{category}={value}
+  * @only.with_{category}={value}
+
+
+
+
+Example 1
+~~~~~~~~~~
+
+Assuming you have the feature file where:
+
+  * scenario "Alice" should only run when browser "Chrome" is used
+  * scenario "Bob" should only run when browser "Safari" is used
+
+.. code-block:: gherkin
+
+    # -- FILE: features/alice.feature
+    Feature:
+
+        @use.with_browser=chrome
+        Scenario: Alice (Run only with Browser Chrome)
+            Given I do something
+            ...
+
+        @use.with_browser=safari
+        Scenario: Bob (Run only with Browser Safari)
+            Given I do something else
+            ...
+
+
+.. code-block:: python
+
+    # -- FILE: features/environment.py
+    # EXAMPLE: ACTIVE TAGS, exclude scenario from run-set at runtime.
+    # NOTE: ActiveTagMatcher implements the runtime decision logic.
+    from behave.tag_matcher import ActiveTagMatcher
+    import os
+    import sys
+
+    active_tag_value_provider = {
+        "browser": "chrome"
+    }
+    active_tag_matcher = ActiveTagMatcher(active_tag_value_provider)
+
+    def before_all(context):
+        # -- SETUP ACTIVE-TAG MATCHER VALUE(s):
+        active_tag_value_provider["browser"] = os.environ.get("BROWSER", "chrome")
+
+    def before_scenario(context, scenario):
+        # -- NOTE: scenario.effective_tags := scenario.tags + feature.tags
+        if active_tag_matcher.should_exclude_with(scenario.effective_tags):
+            # -- NOTE: Exclude any with @use.with_browser=<other_browser>
+            scenario.skip(reason="DISABLED ACTIVE-TAG")
+
+
+.. note::
+
+    By using this mechanism, the ``@use.with_browser=*`` tags become
+    **active tags**. The runtime decision logic decides when these tags
+    are enabled or disabled (and uses them to exclude their scenario/feature).
+
+
+
+
+Example 2
+~~~~~~~~~~
+
+Assuming you have scenarios with the following runtime conditions:
+
+  * Run scenario Alice only on Windows OS
+  * Run scenario Bob only with browser Chrome
+
+.. code-block:: gherkin
+
+    # -- FILE: features/alice.feature
+    # TAG SCHEMA: @use.with_{category}={value}, ...
+    Feature:
+
+      @use.with_os=win32
+      Scenario: Alice (Run only on Windows)
+        Given I do something
+        ...
+
+      @use.with_browser=chrome
+      Scenario: Bob (Run only with Web-Browser Chrome)
+        Given I do something else
+        ...
+
+
+.. code-block:: python
+
+    # -- FILE: features/environment.py
+    from behave.tag_matcher import ActiveTagMatcher
+    import sys
+
+    # -- MATCHES ANY TAGS: @use.with_{category}={value}
+    # NOTE: active_tag_value_provider provides category values for active tags.
+    active_tag_value_provider = {
+        "browser": os.environ.get("BEHAVE_BROWSER", "chrome"),
+        "os":      sys.platform,
+    }
+    active_tag_matcher = ActiveTagMatcher(active_tag_value_provider)
+
+    # -- BETTER USE: from behave.tag_matcher import setup_active_tag_values
+    def setup_active_tag_values(active_tag_values, data):
+        for category in active_tag_values.keys():
+            if category in data:
+                active_tag_values[category] = data[category]
+
+    def before_all(context):
+        # -- SETUP ACTIVE-TAG MATCHER (with userdata):
+        # USE: behave -D browser=safari ...
+        setup_active_tag_values(active_tag_value_provider, context.config.userdata)
+
+    def before_feature(context, feature):
+        if active_tag_matcher.should_exclude_with(feature.tags):
+            feature.skip(reason="DISABLED ACTIVE-TAG")
+
+    def before_scenario(context, scenario):
+        if active_tag_matcher.should_exclude_with(scenario.effective_tags):
+            scenario.skip("DISABLED ACTIVE-TAG")
+
+
+By using the `userdata`_ mechanism, you can now define on command-line
+which browser should be used when you run behave.
+
+.. code-block:: sh
+
+    # -- SHELL: Run behave with browser=safari, ... by using userdata.
+    # TEST VARIANT 1: Run tests with browser=safari
+    behave -D browser=safari features/
+
+    # TEST VARIANT 2: Run tests with browser=chrome
+    behave -D browser=chrome features/
+
+
+.. note::
+
+    Unknown categories, missing in the ``active_tag_value_provider`` are ignored.
+
+
+User-defined Formatters
+-------------------------------------------------------------------------------
+
+:Since:  behave 1.2.5a1
+
+Behave formatters are a typical candidate for an extension point.
+You often need another formatter that provides the desired output format for a
+test-run.
+
+Therefore, behave supports now formatters as extension point (or plugin).
+It is now possible to use own, user-defined formatters in two ways:
+
+  * Use formatter class (as "scoped class name") as ``--format`` option value
+  * Register own formatters by name in behave's configuration file
+
+.. note::
+
+    Scoped class name (schema):
+
+      * ``my.module:MyClass``   (preferred)
+      * ``my.module::MyClass``  (alternative; with double colon as separator)
+
+
+User-defined Formatter on Command-line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Just use the formatter class (as "scoped class name") on the command-line
+as value for the ``-format`` option (short option: ``-f``):
+
+.. code-block:: sh
+
+    behave -f my.own_module:SimpleFormatter ...
+    behave -f behave.formatter.plain:PlainFormatter ...
+
+.. code-block:: python
+
+    # -- FILE: my/own_module.py
+    # (or installed as Python module: my.own_module)
+    from behave.formatter.base import Formatter
+
+    class SimpleFormatter(Formatter):
+        description = "A very simple NULL formatter"
+
+
+Register User-defined Formatter by Name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is also possible to extend behave's built-in formatters
+by registering one or more user-defined formatters by name in the
+configuration file:
+
+.. code-block:: ini
+
+    # -- FILE: behave.ini
+    [behave.formatters]
+    foo = behave_contrib.formatter.foo:FooFormatter
+    bar = behave_contrib.formatter.bar:BarFormatter
+
+.. code-block:: python
+
+    # -- FILE: behave_contrib/formatter/foo.py
+    from behave.formatter.base import Formatter
+
+    class FooFormatter(Formatter):
+        description = "A FOO formatter"
+        ...
+
+Now you can use the name for any registered, user-defined formatter:
+
+.. code-block:: sh
+
+    # -- NOTE: Use FooFormatter that was registered by name "foo".
+    behave -f foo ...
+