busser-behave 0.1.3

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

@@ -0,0 +1,255 @@
+Noteworthy in Version 1.2.6
+==============================================================================
+
+Summary:
+
+* Tagged Examples: Examples in a ScenarioOutline can now have tags.
+
+* Feature model elements have now language attribute based on language tag
+  in feature file (or the default language tag that was used by the parser).
+
+* Gherkin parser: Supports escaped-pipe in Gherkin table cell value
+
+* Configuration: Supports now to define default tags in configfile
+
+* Configuration: language data is now used as default-language that should
+  be used by the Gherkin parser. Language tags in the Feature file override
+  this setting.
+
+* Runner: Can continue after a failed step in a scenario
+
+* Runner: Hooks processing handles now exceptions.
+  Hook errors (exception in hook processing) lead now to scenario failures
+  (even if no step fails).
+
+* Testing support for asynchronuous frameworks or protocols (:mod:`asyncio` based)
+
+
+
+Scenario Outline Improvements
+-------------------------------------------------------------------------------
+
+.. _tagged examples:
+
+.. index::
+    pair:   ScenarioOutline; tagged examples
+    pair:   Gherkin parser; tagged examples
+
+Tagged Examples
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:Since:  behave 1.2.6.dev0
+
+The Gherkin parser (and the model) supports now to use tags with the
+``Examples`` section in a ``Scenario Outline``. This functionality can be
+used to provide multiple ``Examples`` sections, for example one section per
+testing stage (development, integration testing, system testing, ...) or
+one section per test team.
+
+The following feature file provides a simple example of this functionality:
+
+.. code-block:: gherkin
+
+    # -- FILE: features/tagged_examples.feature
+    Feature:
+      Scenario Outline: Wow
+        Given an employee "<name>"
+
+        @develop
+        Examples: Araxas
+          | name  | birthyear |
+          | Alice |  1985     |
+          | Bob   |  1975     |
+
+        @integration
+        Examples:
+          | name   | birthyear |
+          | Charly |  1995     |
+
+.. note::
+
+    The generated scenarios from a ScenarioOutline inherit the tags from
+    the ScenarioOutline and its Examples section::
+
+        # -- FOR scenario in scenario_outline.scenarios:
+        scenario.tags = scenario_outline.tags + examples.tags
+
+To run only the first ``Examples`` section, you use:
+
+.. code-block:: shell
+
+    behave --tags=@develop features/tagged_examples.feature
+
+.. code-block:: gherkin
+
+    Scenario Outline: Wow -- @1.1 Araxas  # features/tagged_examples.feature:7
+      Given an employee "Alice"
+
+    Scenario Outline: Wow -- @1.2 Araxas  # features/tagged_examples.feature:8
+      Given an employee "Bob"
+
+
+Tagged Examples with Active Tags and Userdata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An even more natural fit is to use ``tagged examples`` together with
+``active tags`` and ``userdata``:
+
+.. code-block:: gherkin
+
+    # -- FILE: features/tagged_examples2.feature
+    # VARIANT 2: With active tags and userdata.
+    Feature:
+      Scenario Outline: Wow
+        Given an employee "<name>"
+
+        @use.with_stage=develop
+        Examples: Araxas
+          | name  | birthyear |
+          | Alice |  1985     |
+          | Bob   |  1975     |
+
+        @use.with_stage=integration
+        Examples:
+          | name   | birthyear |
+          | Charly |  1995     |
+
+Select the ``Examples`` section now by using:
+
+.. code-block:: shell
+
+    # -- VARIANT 1: Use userdata
+    behave -D stage=integration features/tagged_examples2.feature
+
+    # -- VARIANT 2: Use stage mechanism
+    behave --stage=integration features/tagged_examples2.feature
+
+
+.. code-block:: python
+
+    # -- FILE: features/environment.py
+    from behave.tag_matcher import ActiveTagMatcher, setup_active_tag_values
+    import sys
+
+    # -- ACTIVE TAG SUPPORT: @use.with_{category}={value}, ...
+    active_tag_value_provider = {
+        "stage":   "develop",
+    }
+    active_tag_matcher = ActiveTagMatcher(active_tag_value_provider)
+
+    # -- BEHAVE HOOKS:
+    def before_all(context):
+        userdata = context.config.userdata
+        stage = context.config.stage or userdata.get("stage", "develop")
+        userdata["stage"] = stage
+        setup_active_tag_values(active_tag_value_provider, userdata)
+
+    def before_scenario(context, scenario):
+        if active_tag_matcher.should_exclude_with(scenario.effective_tags):
+            sys.stdout.write("ACTIVE-TAG DISABLED: Scenario %s\n" % scenario.name)
+            scenario.skip(active_tag_matcher.exclude_reason)
+
+
+Testing asyncio Frameworks
+-------------------------------------------------------------------------------
+
+:Since:  behave 1.2.6.dev0
+
+The following support was added to simplify testing asynchronuous
+framework and protocols that are based on :mod:`asyncio` module
+(since Python 3.4).
+
+There are basically two use cases:
+
+* async-steps (with event_loop.run_until_complete() semantics)
+* async-dispatch step(s) with async-collect step(s) later on
+
+
+Async-steps
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is now possible to use ``async-steps`` in ``behave``.
+An async-step is basically a coroutine as step-implementation for behave.
+The async-step is wrapped into an ``event_loop.run_until_complete()`` call
+by using the ``@async_run_until_complete`` step-decorator.
+
+This avoids another layer of indirection that would otherwise be necessary,
+to use the coroutine.
+
+A simple example for the implementation of the async-steps is shown for:
+
+* Python 3.5 with new ``async``/``await`` keywords
+* Python 3.4 with ``@asyncio.coroutine`` decorator and ``yield from`` keyword
+
+.. literalinclude:: ../examples/async_step/features/steps/async_steps35.py
+    :language: python
+    :prepend:
+        # -- FILE: features/steps/async_steps35.py
+
+
+.. literalinclude:: ../examples/async_step/features/steps/async_steps34.py
+    :language: python
+    :prepend:
+        # -- FILE: features/steps/async_steps34.py
+
+When you use the async-step from above in a feature file and run it with behave:
+
+.. literalinclude:: ../examples/async_step/testrun_example.async_run.txt
+    :language: gherkin
+    :prepend:
+        # -- TEST-RUN OUTPUT:
+        $ behave -f plain features/async_run.feature
+
+.. hidden:
+
+    .. literalinclude:: ../examples/async_step/features/async_run.feature
+        :language: gherkin
+        :prepend: # -- FILE: features/async_run.feature
+
+.. note::
+
+    The async-step is wrapped with an ``èvent_loop.run_until_complete()`` call.
+    As the timings show, it actually needs approximatly 0.3 seconds to run.
+
+
+
+
+Async-dispatch and async-collect
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The other use case with testing async frameworks is that
+
+* you dispatch one or more async-calls
+* you collect (and verify) the results of the async-calls later-on
+
+A simple example of this approach is shown in the following feature file:
+
+.. literalinclude:: ../examples/async_step/features/async_dispatch.feature
+    :language: gherkin
+    :prepend: # -- FILE: features/async_dispatch.feature
+
+When you run this feature file:
+
+.. literalinclude:: ../examples/async_step/testrun_example.async_dispatch.txt
+    :language: gherkin
+    :prepend:
+        # -- TEST-RUN OUTPUT:
+        $ behave -f plain features/async_dispatch.feature
+
+.. note::
+
+    The final async-collect step needs approx. 0.2 seconds until the two
+    dispatched async-tasks have finished.
+    In contrast, the async-dispatch steps basically need no time at all.
+
+    An :class:`AsyncContext` object is used on the context,
+    to hold the event loop information and the async-tasks that are of interest.
+
+The implementation of the steps from above:
+
+.. literalinclude:: ../examples/async_step/features/steps/async_dispatch_steps.py
+    :language: gherkin
+    :prepend:
+        # -- FILE: features/steps/async_dispatch_steps.py
+        # REQUIRES: Python 3.4 or newer
+

data/vendor/behave/docs/parse_builtin_types.rst

@@ -0,0 +1,59 @@
+.. _id.appendix.parse_builtin_types:
+
+Predefined Data Types in ``parse``
+==============================================================================
+
+:pypi:`behave` uses the :pypi:`parse` module (inverse of Python `string.format`_)
+under the hoods to parse parameters in step definitions.
+This leads to rather simple and readable parse expressions for step parameters.
+
+.. code-block:: python
+
+    # -- FILE: features/steps/type_transform_example_steps.py
+    from behave import given
+
+    @given('I have {number:d} friends')  #< Convert 'number' into int type.
+    def step_given_i_have_number_friends(context, number):
+        assert number > 0
+        ...
+
+Therefore, the following ``parse types`` are already supported
+in step definitions without registration of any *user-defined type*:
+
+
+===== =========================================== ============
+Type  Characters Matched                          Output Type
+===== =========================================== ============
+ w    Letters and underscore                      str
+ W    Non-letter and underscore                   str
+ s    Whitespace                                  str
+ S    Non-whitespace                              str
+ d    Digits (effectively integer numbers)        int
+ D    Non-digit                                   str
+ n    Numbers with thousands separators (, or .)  int
+ %    Percentage (converted to value/100.0)       float
+ f    Fixed-point numbers                         float
+ e    Floating-point numbers with exponent        float
+      e.g. 1.1e-10, NAN (all case insensitive)
+ g    General number format (either d, f or e)    float
+ b    Binary numbers                              int
+ o    Octal numbers                               int
+ x    Hexadecimal numbers (lower and upper case)  int
+ ti   ISO 8601 format date/time                   datetime
+      e.g. 1972-01-20T10:21:36Z
+ te   RFC2822 e-mail format date/time             datetime
+      e.g. Mon, 20 Jan 1972 10:21:36 +1000
+ tg   Global (day/month) format date/time         datetime
+      e.g. 20/1/1972 10:21:36 AM +1:00
+ ta   US (month/day) format date/time             datetime
+      e.g. 1/20/1972 10:21:36 PM +10:30
+ tc   ctime() format date/time                    datetime
+      e.g. Sun Sep 16 01:03:52 1973
+ th   HTTP log format date/time                   datetime
+      e.g. 21/Nov/2011:00:07:11 +0000
+ tt   Time                                        time
+      e.g. 10:21:36 PM -5:30
+===== =========================================== ============
+
+
+.. _string.format: https://docs.python.org/2/library/string.html#format-string-syntax

data/vendor/behave/docs/philosophy.rst

@@ -0,0 +1,235 @@
+===========================
+Behavior Driven Development
+===========================
+
+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. It was
+originally named in 2003 by `Dan North`__ as a response to test-driven
+development (TDD), including acceptance test or customer test driven
+development practices as found in extreme programming. It has `evolved over
+the last few years`__.
+
+__ http://dannorth.net/introducing-bdd
+__ https://forums.pragprog.com/forums/95/topics/3035
+
+On the "Agile specifications, BDD and Testing eXchange" in November 2009 in
+London, Dan North `gave the following definition of BDD`__:
+
+  BDD is a second-generation, outside–in, pull-based, multiple-stakeholder,
+  multiple-scale, high-automation, agile methodology. It describes a cycle
+  of interactions with well-defined outputs, resulting in the delivery of
+  working, tested software that matters.
+
+__ https://skillsmatter.com/skillscasts/923-how-to-sell-bdd-to-the-business
+
+BDD focuses on obtaining a clear understanding of desired software behavior
+through discussion with stakeholders. It extends TDD by writing test cases
+in a natural language that non-programmers can read. Behavior-driven
+developers use their native language in combination with the ubiquitous
+language of domain-driven design to describe the purpose and benefit of
+their code. This allows the developers to focus on why the code should be
+created, rather than the technical details, and minimizes translation
+between the technical language in which the code is written and the domain
+language spoken by the business, users, stakeholders, project management,
+etc.
+
+
+BDD practices
+-------------
+
+The practices of BDD include:
+
+- Establishing the goals of different stakeholders required for a vision to
+  be implemented
+- Drawing out features which will achieve those goals using feature
+  injection
+- Involving stakeholders in the implementation process through outside–in
+  software development
+- Using examples to describe the behavior of the application, or of units
+  of code
+- Automating those examples to provide quick feedback and regression
+  testing
+- Using 'should' when describing the behavior of software to help clarify
+  responsibility and allow the software's functionality to be questioned
+- Using 'ensure' when describing responsibilities of software to
+  differentiate outcomes in the scope of the code in question from
+  side-effects of other elements of code.
+- Using mocks to stand-in for collaborating modules of code which have not
+  yet been written
+
+
+Outside–in
+----------
+
+BDD is driven by `business value`__; that is, the benefit to the business
+which accrues once the application is in production. The only way in which
+this benefit can be realized is through the user interface(s) to the
+application, usually (but not always) a GUI.
+
+__ http://lizkeogh.com/2007/06/13/bdd-tdd-done-well/
+
+In the same way, each piece of code, starting with the UI, can be
+considered a stakeholder of the other modules of code which it uses. Each
+element of code provides some aspect of behavior which, in collaboration
+with the other elements, provides the application behavior.
+
+The first piece of production code that BDD developers implement is the UI.
+Developers can then benefit from quick feedback as to whether the UI looks
+and behaves appropriately. Through code, and using principles of good
+design and refactoring, developers discover collaborators of the UI, and of
+every unit of code thereafter. This helps them adhere to the principle of
+YAGNI, since each piece of production code is required either by the
+business, or by another piece of code already written.
+
+
+The Gherkin language
+--------------------
+
+The requirements of a retail application might be, "Refunded or exchanged
+items should be returned to stock." In BDD, a developer or QA engineer
+might clarify the requirements by breaking this down into specific
+examples. The language of the examples below is called Gherkin and is used
+by *behave* as well as many other tools.
+
+.. code-block:: gherkin
+
+ Scenario: Refunded items should be returned to stock
+   Given a customer previously bought a black sweater from me
+     and I currently have three black sweaters left in stock.
+    When he returns the sweater for a refund
+    then I should have four black sweaters in stock.,
+
+ Scenario: Replaced items should be returned to stock
+   Given that a customer buys a blue garment
+     and I have two blue garments in stock
+     and three black garments in stock.
+    When he returns the garment for a replacement in black,
+    then I should have three blue garments in stock
+     and two black garments in stock.
+
+Each scenario is an exemplar, designed to illustrate a specific aspect of behavior of the application.
+
+When discussing the scenarios, participants question whether the outcomes
+described always result from those events occurring in the given context.
+This can `help to uncover further scenarios which clarify the
+requirements`__. For instance, a domain expert noticing that refunded items
+are not always returned to stock might reword the requirements as "Refunded
+or replaced items should be returned to stock, unless faulty.".
+
+__ http://dannorth.net/whats-in-a-story
+
+This in turn helps participants to pin down the scope of requirements,
+which leads to better estimates of how long those requirements will take to
+implement.
+
+The words Given, When and Then are often used to help drive out the
+scenarios, but are not mandated.
+
+These scenarios can also be automated, if an appropriate tool exists to
+allow automation at the UI level. If no such tool exists then it may be
+possible to automate at the next level in, i.e.: if an MVC design pattern
+has been used, the level of the Controller.
+
+
+Programmer-domain examples and behavior
+---------------------------------------
+
+The same principles of examples, using contexts, events and outcomes are
+used to drive development at the level of abstraction of the programmer, as
+opposed to the business level. For instance, the following examples
+describe an aspect of behavior of a list:
+
+.. code-block:: gherkin
+
+ Scenario: New lists are empty
+   Given a new list
+    then the list should be empty.
+
+ Scenario: Lists with things in them are not empty.
+   Given a new list
+    when we add an object
+    then the list should not be empty.
+
+Both these examples are required to describe the boolean nature of a list
+in Python and to derive the benefit of the nature. These examples are
+usually automated using TDD frameworks. In BDD these examples are often
+encapsulated in a single method, with the name of the method being a
+complete description of the behavior. Both examples are required for the
+code to be valuable, and encapsulating them in this way makes it easy to
+question, remove or change the behavior.
+
+For instance as unit tests, the above examples might become:
+
+.. code-block:: python
+
+ class TestList(object):
+    def test_empty_list_is_false(self):
+        list = []
+        assertEqual(bool(list), False)
+
+    def test_populated_list_is_true(self):
+        list = []
+        list.append('item')
+        assertEqual(bool(list), True)
+
+.. Other practitioners[who?], particularly in the Ruby community, prefer to split these into two separate examples, based on separate contexts for when the list is empty or has items in. This technique is based on Dave Astels' practice, "One assertion per test"[12].
+.. 12. http://techblog.daveastels.com/tag/bdd/
+
+Sometimes the difference between the context, events and outcomes is made more explicit. For instance:
+
+.. code-block:: python
+
+ class TestWindow(object):
+    def test_window_close(self):
+        # Given
+        window = gui.Window("My Window")
+        frame = gui.Frame(window)
+
+        # When
+        window.close()
+
+        # Then
+        assert_(not frame.isVisible())
+
+However the example is phrased, the effect describes the behavior of the
+code in question. For instance, from the examples above one can derive:
+
+- lists should know when they are empty
+- window.close() should cause contents to stop being visible
+
+The description is intended to be useful if the test fails, and to provide
+documentation of the code's behavior. Once the examples have been written
+they are then run and the code implemented to make them work in the same
+way as TDD. The examples then become part of the suite of regression tests.
+
+
+Using mocks
+-----------
+
+BDD proponents claim that the use of "should" and "ensureThat" in BDD
+examples encourages developers to question whether the responsibilities
+they're assigning to their classes are appropriate, or whether they can be
+delegated or moved to another class entirely. Practitioners use an object
+which is simpler than the collaborating code, and provides the same
+interface but more predictable behavior. This is injected into the code
+which needs it, and examples of that code's behavior are written using this
+object instead of the production version.
+
+These objects can either be created by hand, or created using a
+mocking framework such as :pypi:`mock`.
+
+Questioning responsibilities in this way, and using mocks to fulfill the
+required roles of collaborating classes, encourages the use of Role-based
+Interfaces. It also helps to keep the classes small and loosely coupled.
+
+
+Acknowledgement
+---------------
+
+This text is partially taken from the wikipedia text on `Behavior Driven
+Development`_ with modifications where appropriate to be more specific to
+*behave* and Python.
+
+.. _`Behavior Driven Development`: http://en.wikipedia.org/wiki/Behavior_Driven_Development
+