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