Software Tests as Documentation

Writing and keeping up to date documentation in software development projects has always been a problem. In this blog post, Jim Bird discusses the idea of using automated tests to document a software system. He also ask the questions: what do tests document? who will find this documentation useful?

He proposes four principles to define automated tests as useful documentation:
1. comprehensive
2. run often and work
3. written to be read
4. at the right level of abstraction

He discusses extensively the third principle, saying that “writing a test that works, and writing a test that can be used as documentation, are two different things”. This involves using good, descriptive names for each test class and test method. His conclusion is however that you shouldn’t try to use automated tests as documentation as test code should be focused mainly on software testing and shouldn’t aim at other objectives.

Read the complete post on