= testdoc =

testdoc helps you better describe the behaviour of your system by turning your
Python unit tests into human-readable documents.

One of the great benefits of unit tests is that they cast light on the system
they are testing. A well-tested system is often easier to understand than a
poorly-tested one, because the tests provide self-contained chunks of
information about the system's behavior.

If the tests have informative names and useful docstrings, then unit tests can
be used to provide a relatively high-level overview of a system's behavior and
its _purpose_.

testdoc helps you write more useful documentation by extracting the names,
docstrings and comments from unit tests and converting them into a
human-readable document. This helps you improve the layout and content of your
documentation.

For example:

    class TestSSHUserAuthServer(unittest.TestCase):
        """Tests for SSHUserAuthServer."""

        def setUp(self):
            self.realm = Realm()
            portal = Portal(self.realm)
            portal.registerChecker(MockChecker())
            self.authServer = userauth.SSHUserAuthServer()
            self.authServer.transport = FakeTransport(portal)
            self.authServer.serviceStarted()

        def tearDown(self):
            self.authServer.serviceStopped()
            self.authServer = None

        def test_successfulAuthentication(self):
            """When provided with correct authentication information, the server
            should respond by sending a MSG_USERAUTH_SUCCESS message with no other
            data.

            See RFC 4252, Section 5.1.
            """
            packet = NS('foo') + NS('none') + NS('password') + chr(0) + NS('foo')
            d = self.authServer.ssh_USERAUTH_REQUEST(packet)
            def check(ignored):
                # Check that the server reports the failure, including 'password'
                # as a valid authentication type.
                self.assertEqual(
                    self.authServer.transport.packets,
                    [(userauth.MSG_USERAUTH_SUCCESS, '')])
            return d.addCallback(check)


Running the snippet through testdoc transforms it into:

    == SSH User Auth Server ==

    Tests for SSHUserAuthServer.

    === Successful Authentication ===

    When provided with correct authentication information, the server
    should respond by sending a MSG_USERAUTH_SUCCESS message with no other
    data.

    See RFC 4252, Section 5.1.


This is much easier to read. testdoc has helped make the layout of the
documentation much clearer. The test names are converted into English titles
that begin sections of the document. The docstrings form the body of the
document.

Now that the layout is clearer, it's easier to identify the gaps in the
document. For example, the paragraph 'Tests for SSHUserAuthServer' is
unhelpful. In the context of code, it's obvious. In a stand-alone document,
it's irrelevant. Instead, that paragraph should provide an overview of the
purpose of the 'SSH User Auth Server', or at the least say what a 'User Auth
Server' actually is.

If you start using testdoc on all of your unit tests, your project will begin
to build the expectation that the purpose of tests is to describe the behaviour
of your system in both Python and English (or your natural language of choice).
This will make your code base easier to approach and easier to manipulate.

It's also a really easy way to write docs.