Tessa takes the pain out of documenting your test suite. Say goodbye to outdated and incomplete test documentation and hello to easily maintainable test suites with Tessa.
Tessa stands for Test documentation Engine for Java using Asciidoctor (and only ChatGPT knows how the name maps exactly).
Tessa aims to simplify the task of documenting tests and reduces the risk of documentation becoming outdated or incomplete. With Tessa, you can easily keep your test documentation up-to-date and ensure that your test suite is well-documented and easily maintainable.
Predominantly, the pain point the project addresses is the need to switch between documentation and source code when implementing or reviewing tests. It more often than not is hard to match what is documented against what has been implemented, and not having a single source of truth makes the overall process quite error-prone.
Following the general idea of "documentation as code", Tessa wants to bridge the gap between test documentation and implementation by moving the two parts closer together.
Test documentation is supposed to be human-readable, and while test implementation also needs to be readable by humans the nature of tests and implementation details often do not make the tests particularly easy to read.
Tessa relies on test documentation that is included in the code: Various kind of comments in the source code, as well as commonly used annotations used in (JUnit) tests, are the foundation for generated test documentation. At the same time, the comments in the code are expected to help understanding the test implementation. For further information on how comments and annotations are used to generate the test documentation, see the Conventions section.
The Tessa project consists of:
-
Tessa Test Annotations - a set of (optional) annotations for providing additional information in the code
-
Tessa Maven Plugin - a Maven plugin parsing Java test files to automatically generate test documentation files in Asciidoctor format
Add the test dependency and plugin to the pom.xml file of your project to get started automating your test documentation:
<dependency>
<groupId>de.andreassiegel</groupId>
<artifactId>tessa-test-annotations</artifactId>
<version>${tessa.version}</version>
<scope>test</scope>
</dependency><plugin>
<groupId>de.andreassiegel</groupId>
<artifactId>tessa-maven-plugin</artifactId>
<version>${tessa.version}</version>
<executions>
<execution>
<goals>
<goal>generate-test-docs</goal>
</goals>
</execution>
</executions>
</plugin>For more information on how to configure the Tessa Maven Plugin, see the plugin configuration documentation.
In general, Tessa attempts to make use of standard JUnit annotations and uses comments to extract test descriptions and further information for test documentation pages:
| Information | Origin | Example |
|---|---|---|
Document Title |
|
@DisplayName("My Tests")
class MyTest {} |
Overall Test Description |
Javadoc comment of the test class |
/**
* This is a sample test to illustrate how information gets extracted.
*/
class MyTest {} |
Overall Status |
|
@Status("Documented")
class MyTest {} |
Further overall information |
First block comment in the test class (supports Asciidoc syntax) |
class MyTest {
/*
== Prerequisites
This describes high-level aspects that are relevant even before setting up the test.
You can basically put any content in Asciidoc syntax here.
*/
} |
Setup information |
Javadoc comment of the method annotated with |
class MyTest {
/** This needs to be done before all the tests can run. */
@BeforeAll
static void setup() {}
} |
Cleanup information |
Javadoc comment of the method annotated with |
class MyTest {
/** This needs to be done after all tests ran. */
@AfterAll
static void cleanup() {}
} |
Overall Warning |
|
@Disabled("These tests are not working")
class MyTest {} |
Test Categories |
Regions in the class that contain test methods, i.e., methods that are annotated with either |
class MyTest {
// region Happy Cases
@Test
void happyCase() {}
// endregion
// region Failure Cases
@Test
void failureCase() {}
// endregion
} |
Test Case Title |
|
@Test
@DisplayName("My first test case")
void testCase() {} |
Test Case Description |
Javadoc comment of the test method |
/**
* This is a sample test case.
*/
@Test
void testCase() {} |
Test Case Status |
|
@Status("Implemented")
@Test
void testCase() {} |
Test Case Warning |
|
@Disabled("This test is not working")
@Test
void testCase() {} |
Further information about the test case |
First block comment in the test method (supports Asciidoc syntax) |
@Test
void testCase() {
/*
Some general information
*/
} |
Test Case Sections |
Regions in the test methods |
@Test
void testCase() {
// region Arrange
...
// endregion
// region Act
...
// endregion
// region Assert
...
// endregion
} |
Test Steps |
Line and block comments inside a test method, either inside or outside regions (not both). Asciidoc syntax is supported. |
@Test
void testCase() {
// region Arrange
// Some first step
// Some other step
// endregion
// region Act
/*
|===
|Header 1 |Header 2
|Some
|table
|===
*/
// endregion
} |
|
📎
|
Wherever regions are used to extract information from the code, the regions are optional:
If you do not group your test code and its comments using region line comments // region My Region and // endregion, the generated documentation will just be missing the subheadings that are derived from the region names.
|
Check out the examples/ directory to see what Tessa could do for you.
It contains:
-
pom.xml- sample project configuration -
some sample tests
-
examples.adoc- a generated index file -
examples/- generated documentation for the tests
Furthermore, the example is enhanced with the Confluence Publisher Maven plugin to publish the documentation generated by Tessa to Confluence: Sample Documentation in Confluence
|
📎
|
To access the example in Confluence, an Atlassian Cloud account might be required. |
So far, Tessa handles only general (meta) information and descriptions about tests, and while this might be a good start, there are still various moving parts left that make documenting and implementing tests tedious:
-
Test data documentation (and initialization)
-
Interactions with API mocks
-
Execution of the functionality to test
-
Assertions
-
Parameters or parameterized tests
Some use cases may require very specific (and potentially complex) implementations that benefit from separate documentation using code comments as an abstraction level. For such cases, Tessa is already well-suited.
Other use cases, like using REST assured, already provide a code structure that would allow for extraction of execution and assertion information from the test implementation. So this could be a potential enhancement of Tessa’s capabilities in the future.
Once a good sweet spot between specific/individual and standardized/conventional test implementation is identified, further information could be extracted right from the code. Ideally, this might further avoid redundancy between documentation and implementation.
And, last but not least, Tessa currently supports only a single documentation style but extending the configuration options to support the use of custom templates for the generated documentation could follow.