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 aren’t 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: “<p>&nbsp;</p>”.  Accomodate this?)

  • Possible bug: when a variable column has a blank cell (in a ColumnFixture), the value is filled in but it isn’t 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 <p> 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 don’t 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 &nbsp; 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 <br> and <p> 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 <br> tags.

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

 

Initial version:

·        Experimental specification created by Ward Cunningham and Jim Shore.

 

 

 

fit.Summary

 



Contents: