BDD.py

Go to the documentation of this file.

#
# Copyright 2013, MeVis Medical Solutions AG
#
# The user may use this file in accordance with the license agreement provided with
# the Software or, alternatively, in accordance with the terms contained in a
# written agreement between the user and MeVis Medical Solutions AG.
#
# For further information use the contact form at https://www.mevislab.de/contact
#
 
"""Tools for writing human readable, behavioral tests.
 
The functions, decorators and classes defined in this module enable
you to write tests describing the desired behavior of a MeVisLab
module (or any other Python object).
 
A typical behavioral test looks like this:
 
def TEST_a_behavioral_test():
    Given().a_precondition(). \
    When().you_do_something(). \
    Then().something_happens()
 
i.e. it is the concatenation of several function calls, or, in other words,
it is a sentence consisting of a Given clause, a When clause, and a Then
clause.
 
Given(), When(), and Then() are predefined functions marking the start of
the Given clause (and of the whole sentence), the When clause, and the Then
clause, respectively.
 
There is another predefined function, And(), which can be used to concatenate
several custom functions of the same type, e.g.
 
    Given().precondition1(). \
    And().precondition2(). \
    [...]
 
The other functions are custom functions that are defined with the help
of three decorators: GivenClause, WhenClause, and ThenClause. (The decorators
add the decorated functions to the context class so that they can be called
as member functions.)
 
The Given() function creates and returns a context object for the test. All
other functions are member functions of this context object. These functions
also return the context object. This allows arbitrary chaining of those
functions. By adding attributes to the context object we can pass arbitrary
state from one function to the next.
 
See ExampleBDDTestCase in MeVisLab/Examples for an example.
 
For more information on Behavior Driven Development (BDD) check the Internet.
 
If you need a more powerful BDD-style language then have a look at one of the
existing Python BDD modules like behave, freshen, lettuce, etc.
"""
 
import functools
 
 
def Given():
    """Initiates a sentence describing a desired behavior.
 
    Creates and returns the context object for the test.
    """
    return _BDDContext()
 
 
def GivenClause(func):
    """Decorator for defining a Given clause.
 
    The first argument that is passed to the decorated function is the
    context object. Custom parameters are passed to the decorated
    function after the context object.
 
    The decorated function always returns the context object.
 
    Example:
    @GivenClause
    def a_precondition(testContext):
        # perform the setup of the test, e.g. by parameterizing a TestPattern
        # module
    """
    return _BDDClause("Given")(func)
 
 
def WhenClause(func):
    """Decorator for defining a When clause.
 
    The first argument that is passed to the decorated function is the
    context of the test case. Custom parameters are passed to the decorated
    function after the context.
 
    The decorated function always returns the context object.
 
    Example:
    @WhenClause
    def you_do_something(testContext):
        # do whatever shall result in a certain behavior, e.g. touch a field
    """
    return _BDDClause("When")(func)
 
 
def ThenClause(func):
    """Decorator for defining a Then clause.
 
    The first argument that is passed to the decorated function is the
    context of the test case. Custom parameters are passed to the decorated
    function after the context.
 
    The decorated function always returns the context object.
 
    Example:
    @ThenClause
    def something_happens(testContext):
        # check for the expected behavior, e.g. by comparing a field value
        # with an expected value
    """
    return _BDDClause("Then")(func)
 
 
# Internal stuff
 
 
class _BDDContext:
    """Context of a BDD test case.
 
    Instances of this class are created with Given(). All functions defined
    with the clause decorators are added to _BDDContext.
    """
 
    def __init__(self):
        self._state = "Given"
 
    def And(self):
        """Conjunction for joining two clauses of the same type.
 
        This method does nothing except returning the context. It is merely
        syntactic sugar for joining two clauses of the same type, i.e. two
        Given clauses, two When clauses, or two Then clauses.
        """
        return self
 
    def With(self):
        """Conjunction for joining two clauses of the same type.
 
        This method does nothing except returning the context. It is merely
        syntactic sugar for joining two clauses of the same type, i.e. two
        Given clauses, two When clauses, or two Then clauses.
        """
        return self
 
    def When(self):
        """Conjunction for marking the start of the When part.
 
        This method starts the When part of the sentence describing the
        desired behavior. It returns the context.
        """
        self._state = "When"
        return self
 
    def Then(self):
        """Conjunction for marking the start of the Then part.
 
        This method starts the Then part of the sentence describing the
        desired behavior. It returns the context.
        """
        self._state = "Then"
        return self
 
    def __getattr__(self, name):
        """Returns Given/When/Then method corresponding to @a name."""
        prefix = self._state + "_"
        if not name.startswith(prefix):
            return getattr(self, prefix + name)
        else:
            raise AttributeError('Attribute with name "%s" not found.' % name)
 
 
def _BDDClause(clauseType):
    """Internal decorator used for defining clauses of different types."""
 
    def func_wrapper(func):
        @functools.wraps(func)
        def wrapper(self, *args, **kwargs):
            func(self, *args, **kwargs)
            return self
 
        setattr(_BDDContext, clauseType + "_" + func.__name__, wrapper)
 
    return func_wrapper