Waferslim 0.9.1 released

This is a minor point-release, including fixes for unicode handling (in the python2.5 branch only), an additional server startup option --encoding, and usage notes in the README file. It's available from the usual places (Python cheese shop and Launchpad).

Using waferslim with fitnesse

Starting waferslim

Fitnesse communicates with waferslim using TCP sockets and needs to start an instance of the waferslim server each time a runnable page ("test" or "suite") is executed. To instruct fitnesse to use waferslim, your top-level wiki page needs to contain the following instructions:

!define TEST_SYSTEM {slim}
!path /some/path/to/src
!define COMMAND_PATTERN {python3 -m waferslim.server --syspath %p }

This tells fitnesse to use the slim protocol, and to start the waferslim server with sys.path as listed in "!path". For multiple path entries, separate each path entry with the OS-specific path separator (the python os.pathsep value i.e. ";" for windows, ":" otherwise). To use the python2.5 branch of waferslim the command pattern should obviously invoke python not python3.
Additional start-up parameters for the waferslim server can be specified in the COMMAND_PATTERN:
-h, --help
   see this list of options
-p PORT, --port=PORT
   listen on port PORT (see below)
-i HOST, --inethost=HOST
   listen on inet address HOST (default: localhost)
-e ENCODING, --encoding=ENCODING
   use byte-encoding ENCODING (default: utf-8)
-v, --verbose
   log verbose messages at runtime (default: False)
-k, --keepalive
   keep the server alive to service multiple requests, requires forked fitnesse code (default: False)
-l FILE, --logconf=FILE
   use logging configuration from FILE

Fitnesse itself supplies the port number by appending it to the end of the COMMAND_PATTERN: a "trailing" numeric value is assumed to be this port number if none is specified explicitly, so the following are equivalent (though the former is preferable):

!define COMMAND_PATTERN {python3 -m waferslim.server --syspath %p }
!define COMMAND_PATTERN {python3 -m waferslim.server --syspath %p --port }

Executing python code from waferslim

Fitnesse offers a variety of test table styles, all of which are supported by waferslim. Each table style causes waferslim to interact with the "system under test" - your python code - in a slightly different way. Examples of each of the table styles are provided in the sub-package waferslim.examples which is intended as a useful reference guide (viewable online.)
In broad terms waferslim interacts with the system under test as follows:

1. waferslim creates an instance of a class in your python code (an "import" table in your fitnesse page helps waferslim to find and load the class)
2. waferslim invokes one or more methods on that class instance, (where the method name is specified in the fitnesse table, usually in the column header), and values from the cells in the fitnesse table are passed as parameters
3. a return value from a method invocation is passed back to fitnesse which interprets it as a pass (green), fail (red) or error (yellow).

Because the fitnesse slim protocol is string-based, all method parameters
passed from fitnesse cells will be unicode strings by default (type "str" in python3, type "unicode" in python2) .
The waferslim.converters module provides a method decorator to simplify the
conversion of these parameters to native python types such as int, float,
bool and datetime, e.g.

from waferslim.converters import convert_arg
...
class SomeClass:
    @convert_arg(to_type=int)
    def some_method(self, int_param)
    ...
    @convert_arg(to_type=(int, bool))
    def another_method(self, int_param, bool_param)
    ...

Method return values passed back to fitnesse must also be converted into strings (again, unicode by default). This conversion should be transparent unless you have a class for which str(instance) does not provide the required conversion. Converters for types not already handled by waferslim may be registered using the register_converter function, e.g.:

from waferslim.converters import register_converter
...
register_converter(for_type, converter_instance)

The converter_instance is an object (which may subclass waferslim.converters.Converter) that has 2 specific methods:

def from_string(self, value): ... # returns type-instance
def to_string(self, value): ... # returns str-instance

An alternative to registering a custom converter (which will be used for all the fitnesse test pages in a suite) is to use a "temporary" converter by passing the named argument using=a_converter_instance to the @convert_arg and/or @convert_result method decorators. This is recommended for fitnesse tables that use the alternative boolean "Yes-No" converter, as in the example classes in waferslim.examples.decision_table. (Registering YesNoConverter for bool instances would override the default bool converter TrueFalseConverter and cause incorrect behaviour in any script tables run in the same suite, as script tables require "True"/"False" values to be returned to fitnesse for bools).

Introducing... waferslim

WaferSlim is a python port of the fitnesse slim server and protocol. Packages for both python2.5 and python3 are distributed through the Python Cheese Shop and the latest source code is available at launchpad.
As well as the code needed to write and run your own fixtures, examples of fixtures for decision, script, query and table tables are provided. While the code is believed to be "feature complete" feedback on 'real world' usage would be welcomed!

Release 0.9 provides:
- a runnable socket server that unpacks slim-protocol messages sent from a fitnesse server and sends back the packed slim-protcol fixture results
- implementations of the slim Import, Make, Call and CallAndAssign instructions
- converter classes and method decorators to make working with native python datatypes easier
- an isolated execution context that dynamically loads systems-under-test in a way that separates them from each other (and opens the door to a fitnesse command runner that does not need to spawn a new process for each suite or page run)
- examples of fixtures for decision, script, query and table tables
- full docstrings and pylint score > 9
- high pycoverage

Lancelot 1.0 released

Python3 and 2.5 packages are available at the Python Cheese Shop The launchpad release summary has the details, and there are only a couple of changes from the RC2 release:

• added ability to give MockSpec instances meaningful names that appear in unmet specification messages (useful when several colloborations are being specified)
• bug fix 341071: after will_raise() raised exception the mock would not verify()
• bug fix 31073: after specification unmet would not generate meaningful error messages for tuple comparisons

Upcoming features - some thoughts

I've got some ideas in mind for the next release of lancelot:

• Provide a bridge (in both directions) between unittest and lancelot, so that lancelot specs can be run as if they were TestCase-s, and unit tests can be verified in lancelot.
• Allow documentation to be generated from specs as they are run.
• Add some syntactic sugar to improve the readability of "given/when/then..." statements
• Introduce a spec mutator similar to Pester (and Jester), to ensure confidence in verified specs

I won't have as much free time to work on this next release so I doubt whether more than one of these will make it into the codebase over the next 4 weeks... we'll see! :-)

Lancelot 1.0RC2 available

Python3 and 2.5 packages are available at the Python Cheese Shop Here are the release details, taken from the launchpad release summary:

This release is intended to be the last before the final 1.0 release. It includes:

• a Spec class to allow BDD-style specifications (given, when, then...) to be made about the behaviour of an object instance or standalone-function (e.g. should_be, should_contain, should_raise, should_collaborate_with)
• a MockSpec class to allow collaborations with other object instances to be specified
• an @verifiable function decorator to allow specifications to be verified
• an @grouping class decorator to allow specifications to be logically grouped together
• a verify() function to use when verifying one or all verifiable specifications
• a number of Comparable classes to use in specifications
• example code to illustrate the various features
• package, class and method docstrings
• a comprehensive set of specifications for the specification classes themselves

Changes made since rc1 are generally minor:

• new MockResult class has been added, to clarify will_return() behaviour and allow will_raise() statements
• new @grouping class decorator has been added, to allow @verifiable specifications to be logically grouped together
• fail_fast option has been added to verify() function
• it() method has been added to Spec class
• there's been a general tidying-up of code, docstrings and specs to keep pylint score above 9.0 and pycoverage at 99%

A couple of Specs

Here are a couple of snippets of sample code for lancelot.

First up, a standalone function:
import lancelot

def fib(ordinal=0):
    '''Simple fibonacci generator'''
    ...

@lancelot.verifiable
def specify_fib_zero_to_five():
    '''First five fibonacci numbers should be 1,2,3,5,8'''
    spec = lancelot.Spec(fib)
    spec.fib(1).should_be(1)
    spec.fib(2).should_be(2)
    spec.fib(3).should_be(3)
    spec.fib(4).should_be(5)
    spec.fib(5).should_be(8)


Next, a standalone class:
import lancelot

class Stack:
    '''A simple stack with push, pop and peek'''
    ...

@lancelot.verifiable
def behavior_of_stack_with_values():
    '''Should be able to peek() and pop() values after push()'''
    stack = lancelot.Spec(Stack, given=new_stack)
    stack.when(stack.push(value='a'))
    stack.then(stack.peek()).should_be('a')
    stack.then(stack.pop()).should_be('a')
    stack.then(stack.peek()).should_raise(IndexError)
    stack.then(stack.pop()).should_raise(IndexError)


Finally, a class whose behaviour involves collaborations with other classes:
import lancelot

class Observable:
    '''Simple class that sends notifications to its observers'''
    ...

@lancelot.verifiable
def observable_observer_behaviour():
    '''Added Observers should receive Observer notifications.'''
    observer = lancelot.MockSpec()
    observable = Observable()
    spec = lancelot.Spec(observable)
    spec.when(spec.add_observer(observer))
    spec.then(spec.send_notification())
    spec.should_collaborate_with(observer.notify(observable))


Introducing... Lancelot

I've been working on lancelot: a specification and verification library for python, inspired by the particular idiom of test driven development that goes under the banner of BDD. (And the word idiom is a film reference: Sir Lancelot: "Um, I think when I'm in this idiom, I sometimes get a bit, uh, sort of carried away.")

The code is available in a launchpad bazaar repository at http://launchpad.net/lancelot, and the packages can be downloaded from the Cheese Shop at http://pypi.python.org/pypi/lancelot. Versions for both Python 3.x and 2.5 are available: if you check them out please let me know what you think!

PS: Although I'm aware of PySpec and SpeciPy, I haven't actually used them, so I can't really compare lancelot with what they offer. My motivation for starting a new project was that I wanted something to use with Python 3, and I thought I could put my long experience with TDD to good use. (Perhaps I should qualify "long experience"... I've been using JUnit since 2000, was a committer on the Java XmlUnit project, and in 2003-4 I had the pleasure of working alongside Steve Purcell, the author of the Python unittest package, and Nat Pryce, Steve Freeman and Joe Walnes, the authors of the JMock framework. More recently, after some discussion with Andrew Glover, I have been experimenting with easyb, the Java/Groovy BDD framework).

Origins

The title of the blog refers to a scene from one of the Monty Python films. Because, sometimes, practicing test-driven development in Python (compared to say Java or Ruby) does feel a little like being asked to cut down a mighty tree with a fish...