Introduction
This project provides tools to generate documentation from tests.
The tools make the stories behind tests visible. They use the tests of a software project to generate a documentation from the executable code. Since the test code itself is documentation, we talk about executable documentation.
Ron Jeffries, Essential XP: DocumentationUnit tests are also documentation. The unit tests show how to create the objects, how to exercise the objects, and what the objects will do. This documentation, like the acceptance tests belonging to the customer, has the advantage that it is executable. The tests don’t say what we think the code does: they show what the code actually does.
Test Stories
Briefly a test story is a sentence that is derived from the name of the test case method and the code of the test case body. While the first tells the intention of the test, the latter shows how this goal is archived.
Three tools of the testdoc project help you on writing test stories:
testdoc-annotations
All tools rely on annotations to be used with test case classes. The annotation tells what code a given test case actually tests. This establishes a bidirectional connection between tested classes and the classes that tests them.
For more details please refer to Usage of Annotations.
eclipse-testdoc-plugin
The testdoc plugin for Eclipse uses the connections to show the tested classes with their test classes and displays the sentences of the test cases. This makes it easy to navigate between the test and production classes and visualizes the responsibility of a class by listing the test sentences.
For more details please refer to eclipse-testdoc-plugin.
testdoc-maven-report-plugin
The testdoc report plugin for Maven uses the test documentation information to generate a compact report on the test stories. There are means to filter the stories to be reported for a particular view on the tests.
For more details please refer to Usage of the report plugin.