Fit Specification, v1.1

Fit is a tool for improving communication between customers, programmers, and testers. It allows the customer to describe his or her requirements in a way that can be checked against the actual program.

The technique Fit uses is called "specification by example." It allows customers to create a document with tables that describe specific examples of how the software should work. Fit looks at the document and checks to see if the software works the way the tables say it should.

Fit uses small programs, called "fixtures," to connect tables to software. Programmers on the development team are responsible for creating those fixtures. Customers are responsible for creating the tables. Testers work with both groups of people to help make sure that all situations are adequately covered. The three groups work together, interactively, to create great software.

This document, and the documents it references, describes Fit using specification by example. It is, itself, an example of how to use Fit. If all the pass cells in the table below are colored green, then you can be confident that your copy of Fit meets this specification.

Using Fit to test itself, as we do here, leads to circular logic that can be unraveled more easily by the computer than by humans. To avoid a headache, ignore the fact that this document is written in HTML or that the tables use Fit fixtures. Instead, just think of it as a regular document--one that happens to be colored green and red.

Functional changes to Fit that are new in this version of the spec are highlighted yellow. Layout, formatting, and other non-functional changes to the specification are not highlighted.

Details

Fit knows how to do these things:

fat.ReferenceFixture
Description	Location	Result()	*Note*
Parse HTML documents	parse.html	pass
Modify HTML documents	annotation.html	pass
Interpret tables using fixtures	fixtures.html		incomplete
Provide a command-line interface	cli.html		incomplete

Click the links for details about how Fit does each of these things. This specification is a work in progress and the fixtures and command-line interface portion are incomplete. Implementers: you may ignore these sections for now.

Fit is available for many programming languages. The sections above apply to all implementations of Fit. Extensions specific to this implementation of Fit are described here:

fat.ReferenceFixture
Description	Location	Result()
Implementation-specific extensions	extensions.html	pass

Errata

Known errors and omissions, to be fixed in a future version:

The <wiki> tag is not specified.
Parsing-related errors are described but the errors arent specified.
Nested tables are not specified
Argument list (next to fixture name) is not specified.
Parser can handle any XML heirarchy, but only <table>, <tr>, <td> is specified.
Files are expected to be CP1252, but this is not specified.

To Do

To look at in a future release:

· Why is info text coming out with a line break when this spec is run? (Because Word creates empty cells with this markup:  . Accomodate this?)

Possible bug: when a variable column has a blank cell (in a ColumnFixture), the value is filled in but it isnt shown in grey.
More flexibility in charset handling.

Possible feature changes:

Add blank keyword?
make fat.ReferenceFixture a standard fit fixture?
Provide a way for ColumnFixture to easily annotate a cell (including when it passes)
Data setup fixture, similar to RowFixture[?]

Change History

Changes in version 1.1:

· HTML to text: Added support for class attribute in MS Word tag parsing

· HTML to text: Clarified handling of leading and trailing line breaks

· Text to HTML: Changed handling of backwards line feed

· Fixture loading: Added specific error messages when fixtures dont load

· Standard annotations: Changed all HTML to put quotes around color attributes

· Standard annotations: Changed error and info annotations to convert new text to HTML.

· Standard annotations: Changed wrong and error annotations to strip mark-up from original cell.

· Standard annotations: Changed error annotation to use standard font size for error message.

· Malformed HTML Parsing: Changed unclosed table, tr, and td tags to generate an error.

· ColumnFixture: Changed headers to allow multiple words. (not yet specified.)

· Fixture loading: Added argument list by fixture name. (not yet specified.)

· Parsing: Added support for nested tables. (not yet specified.)

Changes in version 1.0:

· Rewrite of the spec.

· HTML to text: Changed   entity to combine with other leading and trailing whitespace.

· HTML to text: Changed non-breaking space character to not combine with other internal whitespace.

· HTML to text: Added conversion of and tags to line-feed characters.

· HTML to text: Added conversion of smart quotes to regular quotes.

· Text to HTML: Added conversion of line-feed characters to tags.

· Text to HTML: Added conversion of adjoining spaces to   entities.

Initial version:

· Experimental specification created by Ward Cunningham and Jim Shore.

fit.Summary

-! ---- !contents