$ cat "

Tests as Documentation


A couple of weeks ago there was an internal seminar at work about Test-Driven Development. The seminar was held by one of the senior devs who has been doing TDD for a few years. As a part of the seminar he presented a few levels of TDD practice, corresponding to different "aha" moments.

One of the "aha" moments was the realization that tests are documentation. When I heard this I thought for a while if I had had this "aha" moment yet or not. I could see how tests could be considered documentation, but that was not how I primarily saw it.

However, about a week ago I actually had that "aha" moment, and then once again today. Last week I had to go through some complex import/export code that I had worked with maybe a month earlier. Since I had worked on the code not that long ago I thought that I would remember how the code was supposed to work. That was not the case. I found myself wondering if a specific behaviour was by design or if it was a bug. After a few seconds of thinking I realized that the tests could tell me ("aha!"). A quick look in the test fixture and I knew that the code worked according to spec.

Today I was setting up a new hobby project, and I was rewriting some old configuration code for Fluent-NHibernate, since that project is changing quite rapidly. I was writing the database configuration and tried to find the correct way to specify "integrated security" as login for a MS SQL Server connection. Intellisense showed that there was a "TrustedConnection()" method of the configuration object, but it had no XML comments.

A quick google search turned up the Fluent NHibernate SVN repository, so I though to myself that I might as well take a quick look in the source. The search function at google code found the unit test for TrustedConnection().

The test look as follows:

public void ConnectionString_for_trustedConnection_is_added_to_the_configuration()
.ConnectionString(c => c
.ToProperties().ShouldContain("connection.connection_string" ,
"Data Source=db-srv;Initial Catalog=tables;Integrated Security=True");

Integrated security it is then. Unit tests to the rescue! ("aha!")

However, when it comes to public libraries and API:s like Fluent NHibernate I really think that there is no excuse for not writing XML comments. Documentation in Intellisense is such a productivity boost that it is a must have for all API:s.

From now on, I can say without a doubt that I believe that unit tests are documentation.

Written by Erik Öjebo 2009-05-17 21:22