Cell Handlers

Cell Handlers are modules that provide special effects when they detect certain patterns in a cell. There are a variety of cell handlers, many of which are active by default.

Cell handlers work through the standard type adapter mechanism. Most of the standard fixtures use this mechanism, although a few do not. Implementation of the cell handler mechanism in the Fit Library is currently spotty.

The cell handler mechanism is shared with the FitNesse C# Fit implementation, but is otherwise not supported by other Fit versions. It should not be used if portability of the Fit tests is an issue.

Contents

Handler Dictionary.

These handlers are supplied with PyFit.

Blank

The blank cell handler checks for the keyword 'blank' in the cell, and stores a zero length string on input, and compares equal to a zero length string on output. It is only availible for strings; it has no meaning for other data types.

Null

The null cell handler checks for the keyword 'null' in the cell, and stores a Python None object on input, and compares equal to a Python None object on output. It is universally availible although its use is discouraged: it is bad programming practice although it is sometimes needed.

asis[]

The asis[] handler allows the entry of leading and trailing white space. It can be nested inside of certain other handlers. It's also the recommended way of handling zero width strings.

error

This cell handler intercepts most exceptions. It reports right (green background) if any exception occured, and wrong (red background) if no exception occured. It is only applicable for result type fields.

exception[name, "message", "value"]

This cell handler intercepts exceptions from the user's fixtures and application. It does not intercept exceptions caused by structural problems in the test, such as incorrect names and the wrong number of rows in a table or cells in a row.

There are three possible formats:

exception[name, "message", "value"]
exception["message"]
exception[name: "message"]

The second and third formats are for compatability with prior versions of Python FIT, and also for compatability with the FitNesse version of the dotNet version of FIT. The first version is prefered.

Each of the individual parts of the first, preferred, version is optional, but at least one must be present. The commas that indicate missing parts are required; trailing commas are not allowed. The message and value must be quoted; the name cannot be quoted. Handling backslashes within the quoted strings is somewhat erattic; they should be avoided.

The value is required if it's used for a given; otherwise an error is raised.

The value is optional for a calculated result, however if it's not present no comparison will be done.

It can check that the correct exception was thrown, and can also check for the correct message. It reports right (green background) if the exception matches, wrong (red background) if there was no exception, and exception (yellow background with stack trace) if the wrong exception occured.

It will check either the exception type, the exception message, both or neither.

Fail[...]

This cell handler reverses the right and wrong status of a cell. It's used mostly for acceptance testing within FIT itself, although it can be used for "anything except" types of tests. It can be nested, and it can contain any cell handler.

For a given, it's only valid if used with the exception[] cell handler. Its presence is not checked for otherwise; it will be taken as part of the given value.

It does not work for most operations in the FIT Library.

Range Checks

This handler allows one to specify a range, greater than or less than check. It's availible by default for integers and floats, and can be added to any type that supports the <= (less than or equal) operation. The syntax is:

operand .. Greater than
.. operand Less than
operand .. operand within
Fail[operand .. operand] outside of

Substring

The three handlers in this package allow one to check the beginning, end or middle of a string. They are: startswith[], endswith[] and contains[]. It checks the string representation of any type, not just strings.

Save and Restore

This handler allows one to save the result of an output operation and then retrieve it for later use as an input operation.

The syntax is "<< name" to save a value for later use, and "name <<" to retrieve it again. Name is used as the key to allow any number of values to be saved and restored.

This is mostly useful for certain kinds of data base tests where the data base will generate a key that needs to be used later.

Using Handlers

Handlers can be added or removed globally by using the handler fixture. They can be added or removed for single fields, methods or properties by using the metadata ".addCellHandlers" and ".removeCellHandlers" key suffixes. The operand of these keys is a list containing either the class names of handlers to be added or removed, or a reference to the classes to be added.

Writing Handlers

A cell handler is a class that supports the cell handler interface. This interface has several methods and fields, some of which are optional. CellHandlerBase provides a number of useful defaults.

Parsing

The Parse(self, cell) method is called for an input field if the 'canParse' identifier has a value of True. Cell can contain either a parse cell or a string.

This method returns a tuple containing a status value and a result object. There are three status values: "ok", "next" and "error". "ok" means that the cell handler has completely finished the parse, and the result object is the final result.

"next" means that the scan of the list of cell handlers is to continue. Since cell handlers do not nest (except for the special cases of the Fail and exception cell handlers), the result object is meaningless.

"error" means that there is something drastically wrong, and the cell handler scanner will throw an exception with the result object as the message.

If no handler in the list returns "ok", then the type adapter's parse method will be called with the original cell or string input.

Checking

The check(self, cell, object, callback) method is called to check a result field if the "canCheck" identifier has a value of True. This is the default inherited from CellHandlerBase.

Object is the result returned from the called method, property or field.

The return protocol is the same as for parse, however the only acceptable values for the result object for the "ok" return are True and False.

If no cell handler returns "ok", then the type adapter's equals method will be called, with the original object passed to the accessor's equals routine.

Callback is the fixture that originally called the type adapter. Its only use at present is to allow access to the symbol table mechanism, which is in Fixture. This may be eliminated in the future.

isTypeAdapterApplicable

This method checks whether the cell handler can be used with the given type adapter. The default routine, in the CellHandlerBase class, checks for the existance of either an "includeList" or an "excludeList" and performs the expected processing. However, a cell handler can have this routine do anything it wants.

The return values are True, False and None. True means it is applicable, False means it isn't. None means that it doesn't know, so the type adapter is asked next. If the type adapter also doesn't know, the cell handler will be used.