Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Turns Python unit tests into human-readable documentation
* REST, Moin and Shiny formatters * Bug 120141 is fixed, testdoc no longer generates documentation for imported tests.
Latest commit f0940e6
Sep 8, 2010
|Type||Name||Latest commit message||Commit time|
|Failed to load latest commit information.|
= 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.