Adding references to JUnit tests

Sometimes it may be desirable or required in order to comply with regulations to link unit tests back to requirements or risks. In that case you’d need to generate a unit test report listing test name, execution date/time, test result, and requirement/risk IDs. To show you what I mean here’s a standard JUnit HTML test report augmented with extra information:

Adding references to JUnit tests
The information in two extra columns links a particular test back to requirements and risks.


The idea is actually quite simple. Use custom annotations on test classes/methods to reference requirements and risks. Then have a custom JUnit RunListener process those annotations to make the information available in the report.

In Java code an excerpt from the sample above would look as follows


What you need for this recipe are four ingredients:

  1. @Risk and @Requirement annotations for test classes/methods
  2. JUnit RunListener implementation
  3. Two types of “persisters” which save the annotation data for later use in the JUnit report
  4. XSLT style sheet which renders requirement/risk references when the XML report is transformed to HTML

The integration of the ingredients is done with Maven and its Surefire Plugin.

Check out my project on GitHub for all the source code presented here. If you’re stuck please either leave comments here or create an issue on GitHub.






The information collected by the RunListener is persisted in two ways to allow for flexible post-processing:

  • self-contained additional JSON file target/surefire-reports/references.json
  • augmented Surefire XML file target/surefire-reports/TEST-<class-name>.xml

In the standard Surefire file each <testcase> element will have two extra attributes like so

Both persister implementations implement the same interface


Surefire XML persister

This implementation depends on JDOM.


JSON persister

This implementation depends on Jackson.


Maven configuration

There a basically two things you need to add to your POM:

Source: pom.xml

The first caveat here is that the XSLT style sheet cannot be loaded from a JAR file but needs to be available through a “regular” file path (line 36). I keep mine in src/main/resources if its a Maven project, Maven will copy it to target/classes during the build process.

The second caveat is that one needs a custom style sheet that includes the extra attributes on the <testcase> element in the final HTML. To get you started you may use mine of course (line 271 has an embedded GIF using data URIs).


4 thoughts on “Adding references to JUnit tests

  1. Thanx for the interesting blog about adding custom columns to unit test reports, this is exactly what I was looking for! 🙂 Unfortunately the imports in your code examples are missing, for some classes aren’t easy to create without. Would it be possible to add the imports here or please just send me the classes if possible? Would be quite helpful. Anyway, thanx again for all the ideas! Great work!

  2. works fine also with tycho-surefire-plugin!

Leave a Reply