Jennitta Andrea sent me her position paper developed for the Tests as Documentation workshop. Unfortunately, she was unable to attend the workshop, but sent this paper with test examples. I like her approach, and encourage you to take a look at her examples. Here are some of her thoughts in the paper on the Tests as Documentation concept:

• You must work VERY hard for your tests to be actually used as documentation for the system requirements.
  • They must be both organized and named extremely well so that someone looking for the details on some aspect of the system can find them.
  • They must be written with the reader in mind … all of the well known test automation patterns describe these details.
• The automated acceptance tests must be built upon a clear and concise domain specific testing language (this is a superset of the ubiquitous language described by Evans).
• The system requirements are spread out amongst a number of different kinds of tests
  • User acceptance tests cover the big-picture work flow and business process description
  • Unit tests cover the specific business rules for individual / small groups of components.
• I still think you need some actual textual / graphical documentation that serves as an overview of the business process and the system. We recently put this kind of thing on a wiki at the very end of the project for the support team (should have done it incrementally during the project)
• Stories should be thrown away once they are implemented. They should not be used as a permanent artifact for describing the system. A story is only a small chunk of the big picture, and it may contradict/overturn an earlier story. We need to create the big picture as it evolves when we implement various stories.

It’s interesting to note her emphasis on writing tests with an audience in mind which was a major theme in the workshop. She also noted that user acceptance tests document the business side of the product while the unit tests document the system process side of the product. This was also noted by one of the groups in the workshop.

I especially like the approach she has used for tabular test data. Check out “Example 2: Tabular Test Specification” of her test examples in the paper. The format for the test data in a spreadsheet is very intuitive and reads nicely.