How to use unit tests as a source of information?

Question

A colleague of mine was one a seminar about agile development, where he heard it is possible to use unit tests as a technical documentation. Something like using unit tests as example how to use the class.

A quick google search provided TDD and Documentation, which proves it should be possible. But looking at our code, I see that we obviously failed to implement unit tests in such a way.

In my opinion unit tests are there to test code as a minimal unit, even with help of mock and fake classes and functions.

So, the questions are :

• isn't it the task of functional tests to show how a class (or set of classes) should be used?
• if it is possible to use unit tests as a technical documentation, are there some guidelines on how to implement such unit tests?

Answer 1

If you are applying TDD, then each unit test you wrote corresponds to a functionality of a class. So as you write tests you are actually creating the class functionalities, dependencies, exceptions and also class documentation.

If you are not applying TDD, still unit tests give you idea about the class and what it does. Unit test names are very descriptive so you don't need to create a documentation mostly.

Consider a unit test like

public void Customer_Service_Can_Register_New_Customers(){...}
public void Customer_Service_Cannot_Register_Customers_With_Duplicate_Emails(){...}

These are self descriptive methods and easy to read too. So they also serve as documentation.

Answer 2

While functional tests can help you understand a whole piece of functionality, a unit test can help with understanding a small scope of code (like a single method).

Good unit tests will also server as good technical documentation, and there are a few things that can help write good, simple, and useful tests. The two most important points I've encountered are

• Make sure that all your tests are independent. You should be able to run any subset of tests, in any order.

• Make sure that you only test a single thing in each test. This keeps your tests specific, simple, but not brittle.

Answer 3

Unit tests, if well written DO serve as some documentation of a class or method or whatever.

Well written ones lead to more understanding by being easy to figure out what they are testing, but even poor tests give the reader some idea of how the thing being tested is supposed to act, and what things the author thought were important to test.

Heck, I've been known to write unit tests for external libraries - not because they need testing, but because I want to make sure my understanding of the library is correct. And in the future, if someone has questions about how I'm using things, well there's my understanding, right in the test code.

Answer 4

The idea of tests as acceptance criterias/documentation is an excellent one. However, unit tests tend to focus on architecture/code design rather than user stories - trying to document higher level use cases or requirements can be awkward. I haven't looked much into it (yet), but Behavior Driven Development might help with that problem.

Answer 5

I find examples much easier to learn from than documentation and unit tests serve great as that. Not only that, but they show me, by example, what NOT to do with a unit.

However, they can't be the only form of documentation. One must realize that brains all work differently. That's one thing I think people who recommend using JUST unit tests as your documentation or JUST the code completely miss. Even more poignant is the fact that even single brains learn different things from different mediums. I learn something completely different from a class diagram than I do just looking at code or reading API docs.

But at the end of the day, if diagrams and API docs are all you have then I'm probably screwed. I need examples. I need to see something being used. I might search the code for this, and lacking any other examples that's what I'm stuck with, but this will never tell me as much as a good unit test.