使用 JavaDoc 丰富 JUnit 测试报告 [英] JUnit test report enrichment with JavaDoc

问题描述

对于客户，我们需要为集成测试生成详细的测试报告，不仅表明一切都是绿色的，而且表明测试做了什么.我和我的同事都是懒人，我们不想破解电子表格或文本文档.

For a customer we need to generate detailed test reports for integration tests which not only show, that everything is green, but also what the test did. My colleagues and I are lazy guys and we do not want to hack spreadsheets or text documents.

为此，我想了一种方法来记录更复杂的集成测试，并在每个 @Test 注释方法和每个测试类上使用 JavaDoc 注释.对于测试人员来说，了解哪个要求、Jira 票证或测试链接到的任何内容以及测试实际尝试执行的操作是一个很好的帮助.我们也想向我们的客户提供这些信息.

For that, I think about a way to document the more complex integration tests with JavaDoc comments on each @Test annotated method and each test class. For the test guys it is a good help to see to which requirement, Jira ticket or whatever the test is linked to and what the test actually tries to do. We want to provide this information to our customer, too.

现在最大的问题是:我们如何将每个方法和每个测试类的 JavaDoc 放入 JUnit 报告中?我们使用 JUnit 4.9 和 Maven.

The big question now is: How can we put the JavaDoc for each method and each test class into the JUnit reports? We use JUnit 4.9 and Maven.

我知道，每个 assertXXX() 都有一个描述，但我们确实需要一个很好的 HTML 列表作为结果或一个 PDF 文档，其中列出了所有类和文档，下面是所有 @Test 方法及其描述，测试时间，结果，如果失败，原因.

I know, that there is a description for each assertXXX(), but we really would need a nice HTML list as result or a PDF document which lists all classes and there documentation and below that all @Test methods and their description, the testing time, the result and if failed, the reason why.

或者有另一种生成花哨的测试脚本的替代方法吗?(或者我们应该为此启动一个开源项目！?;-) )

Or is there another alternative to generate fancy test scripts? (Or should we start an OpenSource project on this!? ;-) )

更新:我问了另一个关于如何将 RunListener 添加到 Eclipse 以使其在 Eclipse 中启动时也报告的问题.建议的带有自定义 TestRunner 的解决方案是获得测试结果报告的另一种可能性.看看:如何在 Eclipse 中使用 JUnit RunListener?

Update: I asked another question on how to add a RunListener to Eclipse to have it also report in Eclipse when started there. The proposed solution with a custom TestRunner is another possibility to have the test results report. Have a look: How can I use a JUnit RunListener in Eclipse?

推荐答案

实现此目的的一种方法是使用自定义 RunListener，但需要注意的是，使用注释而不是 javadoc 会更容易.您需要有一个自定义注释，例如:

One way to achieve this would be to use a custom RunListener, with the caveat that it would be easier to use an annotation rather than javadoc. You would need to have a custom annotation such as:

@TestDoc(text="tests for XXX-342, fixes customer issue blahblah")
@Test
public void testForReallyBigThings() {
    // stuff
}

RunListener 监听测试事件，如测试开始、测试结束、测试失败、测试成功等

RunListener listens to test events, such as test start, test end, test failure, test success etc.

public class RunListener {
    public void testRunStarted(Description description) throws Exception {}
    public void testRunFinished(Result result) throws Exception {}
    public void testStarted(Description description) throws Exception {}
    public void testFinished(Description description) throws Exception {}
    public void testFailure(Failure failure) throws Exception {}
    public void testAssumptionFailure(Failure failure) {}
    public void testIgnored(Description description) throws Exception {}
}

Description 包含应用于测试的注释列表方法，因此使用上面的示例，您可以使用以下方法获取 Annotation TestDoc:

Description contains the list of annotations applied to the test method, so using the example above you can get the Annotation TestDoc using:

description.getAnnotation(TestDoc.class);

并正常提取文本.

然后您可以使用 RunListener 生成您想要的文件，其中包含特定于该测试的文本、测试是通过还是失败、或被忽略、所用时间等.这将是您的自定义报告.

You can then use the RunListener to generate the files you want, with the text specific to this test, whether the test passed or failed, or was ignored, the time taken etc. This would be your custom report.

然后，在surefire中，您可以指定自定义侦听器，使用:

Then, in surefire, you can specify a custom listener, using:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>2.10</version>
  <configuration>
    <properties>
      <property>
        <name>listener</name>
        <value>com.mycompany.MyResultListener,com.mycompany.MyResultListener2</value>
      </property>
  </configuration>
</plugin>

这是来自 Maven Surefire 插件，使用 JUnit，使用自定义侦听器和报告器

此解决方案的缺点是，就回车、格式而言，您没有 javadoc 的灵活性，但它的优点是文档位于一个特定位置，即注释 TestDoc.

This solution has the disadvantage that you don't have the flexibility of javadoc as far as carriage returns, formatting is concerned, but it does have the advantage that the documentation is in one specific place, the annotation TestDoc.

这篇关于使用 JavaDoc 丰富 JUnit 测试报告的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！