[Tutor] Test Drive Development, DocTest, UnitTest

[Steven D'Aprano]

On Wed, 22 Sep 2010 01:37:42 am Tino Dai wrote:

> I am 
> torn between the DocTest and UnitTest. I like the one "fileness" of
> the DocTest, but am concerned
> about the length of my tests being several orders of magnitude bigger
> than the actual code. I
> like the UnitTest having a separate file but am worried about the
> tests getting lost or never getting
> executed because a junior developer doesn't know about them. I'm
> wondering in respect to TDD, which
> is better or is it a matter of taste?

Neither is better. They're just different, with different purposes.

The *primary* purpose of doctests are to be executable examples. When 
you write documentation, including example code is the most natural 
thing in the world. doctest lets you execute those examples, to ensure 
that they work. They're certainly not meant as an exhaustive test of 
every single feature in the program, but as *documentation* that 
happens to also work as tests.

Unit tests can be a little heavyweight, but they're designed for 
exhaustive tests of the *entire* program, not just the parts with 
user-documentation. You should write whitebox tests, not just blackbox 
tests. That means don't just write tests for the published interface, 
but write tests for the unpublished internal details as well.

E.g. if your function has special processing to deal with lists of 
strings, then you need a test for input that is a list of strings. But 
it's not necessary to document that fact in the doc string. What do the 
users care that your function calls a special subroutine to deal with 
lists of strings? So it would be inappropriate to draw attention to 
this fact with a doctest.
    
Doctests don't just execute themselves. If your developers, junior or 
otherwise, don't know about the tests, don't keep the tests up to date, 
and don't run the tests, then it doesn't matter what testing framework 
you use.

Doctests and unittests are complementary. They work well together. In 
fact, the unittest module can even execute doctests.


-- 
Steven D'Aprano