Exploration Through Example

Example-driven development, Agile testing, context-driven testing, Agile programming, Ruby, and other things of interest to Brian Marick

191.8

⇒

167.2

⇒

186.2

183.6

184.0

183.2

184.6

Fri, 25 Feb 2005

Fit style

Requirements documents or specifications explain how a program is supposed to behave for all possible inputs. Automated tests explain how a program is supposed to behave for certain possible inputs. The understanding gained by reading tests duplicates some of the understanding gained by reading documents. Duplication is (often) bad. One of my goals is to find out how to write and annotate tests so that the redundant parts of those other documents can be eliminated.

Fit has potential for that because the test tables can be embedded in whatever HTML you like. Rick Mugridge's Fit Library increases that potential by providing an improved set of default tables. But we still have to realize that potential by using them well. I've been exploring how. Here's an example, patterned after a table I recently wrote for a client. I have some comments about the style after the table.

A person reading this page would come to it knowing some context. She would know that things called "nodes" are arranged hierarchically. (In the original table, what I'm calling "nodes" were something less abstract.) She would know that nodes are sometimes visible, sometimes invisible.

com.exampler.fixtures.dofixtures.Visibility Visibility Making a node invisible makes its descendants invisible, no matter where the search begins. create node 1 invisible node 1.1 node 1.1.1 check that visibility from invisible node 1.1 is (nothing) check that visibility from node 1.1.1 is (nothing) check that visibility from node 1 is node 1 Siblings are not affected. create node 3 invisible node 3.1 node 3.2 node 3.2.1 check that visibility from invisible node 3.1 is (nothing) check that visibility from node 3.2 is node 3.2, node 3.2.1 check that visibility from node 3 is node 3, node 3.2, node 3.2.1

• First, notice the little Java class name up at the top right. That's a table with the border turned off. The class is a DoFixture, and it will interpret all the other tables on the page. I've made it small and out of the way because that name has no meaning for the business. It's technology-facing, and I want business people to quickly learn not to notice it.
  
  This is to be the only technology-facing name on the page. I think that's important.

• The next table is a row in the DoFixture that does setup for the test. Our friend Rick has written code that turns bulleted lists in a cell into a tree data structure. That's just what I need, so I use it.
  
  I could have made this setup table a ColumnFixture or Rick's new SetupFixture, but both of those would have required more in the table. I will only grudgingly add non-data words to a test. They make it harder to read (usually).

• The next set of sentences are more DoFixture rows. I've again turned off the border, this time because I don't want that ornamentation to distract the reader. I want the checks to look like sentences you'd read in a textbook example. (It would be better if "check" could be written "observe that". Maybe I can talk Rick into that.)
  
  I did, however, follow the convention of making the non-data words in italics as a way of emphasizing what's data. (I left "check" in non-italic font because it's an important signal to the reader.)

• But wait: Those check lines violate the "I will only grudgingly add non-data words to a test" rule. Why all those repetitions of "that visibility from "? Would it be better to put the checks in a ColumnFixture?

  Given this hierarchy: node 3 invisible node 3.1 node 3.2 node 3.2.1 expect that visibility from node is() invisible node 3.1 (nothing) invisible node 3.2 node 3.2, node 3.2.1 node 3 node 3, node 3.2, node 3.2.1

  I'm not sure. My reaction to the two versions is different. The first is more like an explanation of the feature. The second is more like a checklist than something you read for understanding. For example, when reading the second, I'm more bothered that not all the nodes are listed and that node 3 doesn't come first. (The order is not an accident - I wrote the check sentences in the order I'd explain it to a person while pointing at nodes with my finger.)

• It was well after supposedly finishing the tables that I thought of greying out the invisible nodes. I did it because at one point I glanced at a node, wondered if it were visible, then looked up the tree to check. Too much work.

## Posted at 15:31 in category /fit [permalink] [top]