Programmer Guide

When we say you're a "programmer," we mean that you're someone who helps implement the product your team is creating. Your job title might include "architect," "designer," "software engineer," or even "programmer." We'll just call you a programmer to make things easy.

Before we get started, you may want to read IntroductionToFit and FitWorkflow. They introduce Fit and provide a process for using it on your team.

The Programmer's Role

As a programmer, you have a crucial role: you build the software. Your challenge is doing so correctly. It's hard enough to write bug-free code without the added difficulty of guessing what your customers want. Fit exists to help you understand your customers' needs and to allow you to demonstrate what the software is doing.

Fit works with HTML documents. Those documents include tables which are interpreted by fixtures. Those fixtures are your responsibility.

Creating Fixtures

Fit works by parsing HTML, finding tables, and passing the information in the tables to fixtures that you write. The fixtures take the information from the tables and turn them into method calls on the actual application. Here's an example of a ColumnFixture:

As you can see, fixtures are actually pretty easy to write. Fit comes with three base class fixtures which you extend. These base fixtures do the heavy lifting. The three base fixtures are:

• ColumnFixture - best for checking rules and calculations
• ActionFixture - best for step-by-step processing
• RowFixture - best for checking sets of data

(Note: You can also write your own base class fixtures or use base fixtures provided by others. Doing so is beyond the scope of this document.)

Fixture Conventions

When a fixture runs, it compares the data in some cells against the data returned by your application. By convention, fixtures color-code the cells according to the result of the check:

• Green: The software was right.
• Red: The software was wrong.
• Yellow: An exception was thrown.
• Grey background: The cell was ignored for some reason.
• Grey text: The cell was blank, so Fit filled in the answer from your software.

(It's possible for you to write new base fixtures that don't follow these conventions, but we don't recommend it!)

Running Fit

Fit is a command-line application. The standard Fit runner takes a single HTML file, processes it, and outputs the result to a different file. There are third-party runners that will process entire directories, such as RickMugridge's FolderRunner in his FitLibrary.

Many business-grade tools will save documents as HTML, including Microsoft Word. Just say "File->Save As" and pick HTML. Fit works great with Word documents that have been saved as HTML.

Excel also saves documents as HTML, but it saves the whole document as a giant table. As a result, Fit won't work directly with Excel documents. Instead, cut-and-paste examples from Excel to Word. They'll come across as tables and work fine from there.

Working With Customers

Although Fit tests examples against your code, Fit's not just a testing tool. At its heart, Fit is a tool for collaboration. It's about giving you a rigorous way to discuss details with your customers. And it's about giving your customers a way to see what your software really does.

Because Fit reads and writes HTML, and because Word and similar business tools read and write HTML, Fit documents can be written, directly, by customers. It allows customers to own their examples. That's important. Encourage them to do so. Show them the feedback and control they'll get. Customer involvement is critical to software success. Fit will help you get it, and if you do, your software will be better.

A big part of using Fit is helping customers participate, so you may want to read FitWorkflow and the CustomerGuide. Pay particular attention to the Fit lifecycle and look for ways you can help your customers participate.

Many customers are more comfortable talking about the UI of an application than underlying requirements. In the beginning, you're likely to get examples that talk about what the user does rather than underlying business rules. These sorts of examples obscure the customer's real needs and they're hard to write and maintain. Gently steer your customer in the direction of discussing examples around business rules. For example, if the customer says "accounting will press this button and the software will take the timecard and calculate the employee's pay," you can ask for examples of timecards and resulting pay.

As your customer describes examples, you'll probably think of questions. Use those questions to get additional examples that demonstrate the answer to the question. Sometimes your customer won't know or will be flustered by the question. In that case, put it aside for later.

After you have a few key examples, help your customer turn the examples into tables. Don't try to make the tables work with fixtures just yet. Just get the examples down. Once you're all satisfied with the tables, reformat them so they're easy to implement with Fit. Be careful not to lose the customer's perspective when you do this.

As you implement the feature, you'll probably come across questions that aren't covered by the examples you have. Bring these questions back to your customer and, as before, use them to help guide your customer in creating additional examples.

Fit isn't just a way for you to get details from your customer. It's also a way for your customer to get feedback from your program. Show your customer how to run Fit against the latest build. Demonstrate how he or she can make changes to Fit documents, rerun Fit, and see the results. This will allow your customer to experiment and come up with more examples. You want your customer to be able to say, "I wonder how the software handles this situation...?" and get the answer by adding a new example to a Fit document.

Conclusion

We've only touched the tip of the Fit iceberg. See FitDocumentation for more information about writing fixtures, for examples of tests, and to learn more about using Fit with your specific programming language.

This concludes the Fit documentation trail. The previous document in the series was FitWorkflow. You may DownloadNow or return to FitDocumentation.