Tips For Core Implementors

First of all we have a set of goals that we try to meet on every implemntation. These are ...

Uniform support for the testing methodology.

At its heart the framework is a structured way for people to communicate. There are dozens of little tradeoffs we make to insure it works well this way. We don't want to reverse any of these decisions without knowing it.

All basic fixtures abstractions (row, column and action)

The different table formats are our most powerful way to introduce abstractions into the tables. We don't think anyone will be happy with the framework unless they have at least the three basic formats available.

Effective use of unique platform capabilities.

We ask that every implementer start by duplicating the core used in every other platform. We know that this leads to a lowest-common-denominator mentality unless implementors then show off the unique capabilities offered by their platform. We only ask that features not preceed the core and that users know which is which.

Consistent licensing.

We've chosen the GNU GPL which we understand makes a bit of a political statment. We feel the CopyLeft properties of the GPL match well with what is essentially the vocabulary of a discipline. We ask that all downloads from this site be licensed under GPL, though we are happy to point to sites with add-ons under different licensing.

We also would like to keep the ownership of the Fit copyright simple. This allows us to offer interpretations of the GPL and be solely accountable for them when lawyers are still learning about concepts like "linking". For this reason we ask that the copyright of code contributions be transfered to us, Cunningham & Cunningham, Inc. Email if you have questions.

Fit Community

Take advantage of the Fit community. Start by subscribing to the mailing list on yahoo!:

• mailto:fitlist@yahoogroups.com
• Subscription interface: http://tech.groups.yahoo.com/group/fitlist/

Next, download the latest Fit release from http://fit.c2.com/wiki.cgi?DownloadNow. The Java version is the Fit reference implementation. Feel free to download other implementations, too, for source code ideas.

Unzip the Java release and take a look at the Fit Specification in the /spec/output folder. Your mission, should you choose to accept it, is to get this spec to pass in your language.

To get started, I'd recommend taking a look at the Java source code. It's in /source/imp/java. Take a look at the major components: FileRunner, Parse, and Fixture.

Once you start implementing your version, you don't have to follow the Java structure. But that's an easy way to start. For more detailed advice, see below.

Welcome aboard! Please feel comfortable participating in the mailing list discussions. Be sure to post to the list any time you have questions or suggestions.

Now, how to do it. We've found all implementations so far follow the same general sequence. This sequence introduces abstractions at a fairly uniform rate with each building on the previous. It is a bottom-up sequence that offers a lot of checks to keep you on track along the way.

Run unit tests to get Parse working.

Parse is the internal representation of the test data. Don't be seduced by generalized html/xml parsers. This one has unique features. Make it work. Consider replacing it only after you've used this one a while.

• Get a unit testing framework running that can at least do assertEquals.
• Copy test from FrameworkTest, one at a time, starting with the first.
• Implement class Parse only as required by the first three parsing tests.
• Try parsing arithmetic.html
• Add print() to Parse and try printing arithmetic.html

Specifically run ArithmeticFixture which is the fixture used by the first table in arithmetic.html. This doesn't use reflection so it is a good place to see how everything works before we open that can of worms.

• Create the base Fixture class and implement traversal without any reflection.
• Make a FileRunner and run arithmetic.html. Or do the equivalent with a simple little main program if this is easier.
• Implement addToTag in Fixture and use it to color every cell of arithmetic.html green. Enjoy your output. Then remove this little hack.
• Create PrimitiveFixture (which has some sample parsing) and ArithmeticFixture on top of it.
• Modify doTables in Fixture to find ArithmeticFixture by reflection.
• Debug until you get results similar to http://files:result.html

Run a ColumnFixture test

The second test table in arithmetic.html is a ColumnFixture. You will need to get reflection working and the basics of TypeAdapter right. Use the rest of the unit tests to help you get this right. You may feel that this stuff is overly heavy and that there are shortcuts that I missed. Again I encourage you to go ahead and make this stuff work and use it in later tests before you customize too much.

Run the CalculatorExample

This has a more substantial fixture and even has a separate system under test instead of just doing arithmetic in the fixture. If you have a web server, see if you can get a RunScript running and serve it your own copy of CalculatorExample.html.

Run the MusicExample

This is a big example and introduces two new fixture types. Work through it table by table but skip the realtime tables until the end.

Make the Runners

By now you will be wondering how many places you can hook this stuff in. That means you'll be imagining cool fixtures on the one side and exotic runners on the other. Go wild.

Run the ExampleTests megatest.

This is a simple fixture that runs all the tests and checks that they produce the expected counts. Use it and the unit tests when you refactor.

Run the FitSpecification.

The Fit Specification is the last word on Fit behavior. Once your implementation works with ExampleTests and passes the spec, it's ready to release.