You can use @ReportEntry as a simple way to declaratively add metadata to test methods.

In JUnit Jupiter you should use TestReporter where you used to print information to stdout or stderr in JUnit 4. Using @RunWith(JUnitPlatform.class) will output all reported entries to stdout. In addition, some IDEs print report entries to stdout or display them in the user interface for test results.

To see how @ReportEntry helps, let’s first take a look at the conventional approach and then at this extension.

Standard Use of TestReporter

If a constructor or method parameter is of type TestReporter, the TestReporterParameterResolver will supply an instance of TestReporter. The TestReporter can be used to publish additional data about the current test run. The data can be consumed via the reportingEntryPublished() method in a TestExecutionListener, allowing it to be viewed in IDEs or included in reports.

So, you would use it like this:

@Test
void reportingTest(TestReporter reporter) {
    // YOUR TEST CODE HERE
    reporter.publishEntry("Hello World!");
}

With the extension

It can be argued that publishing data about your tests should not be in your test code because it is simply not part of your test. It is meta-data.

So it makes sense that you should be able to add that meta-data to your test declaratively with annotations and have JUnit take care of the publishing. This is what this extension is for!

You can write…​

@Test
@ReportEntry("Hello World!")
void reportingTest() {
    // YOUR TEST CODE HERE
}

…​and the extension will publish your report entry for you after the test was executed!

Multiple entries

You can declare multiple report entries on the same test (the annotation is repeatable).

@Test
@ReportEntry("foo")
@ReportEntry("bar")
void reportingTest() {
    // YOUR TEST CODE HERE
}

Just like TestReporter::publishEntry accepts a single string as value or a key/value pair, @ReportEntry accepts either a single string as value or a key/value pair:

@Test
@ReportEntry(key = "line1",
        value = "Once upon a midnight dreary")
@ReportEntry(key = "line2",
        value = "While I pondered weak and weary")
void edgarAllanPoe() {
    // YOUR TEST CODE HERE
}

Again, just like TestReporter::publishEntry, if no key is given it defaults to "value" (yes, that’s not a mixup).

Publish conditions

You can specify a PublishCondition parameter on the @ReportEntry annotation for better control when the extension should publish your entry. Just so:

@Test
@ReportEntry(
    key = "line",
    value = "success entry",
    when = ReportEntry.PublishCondition.ON_SUCCESS)
void sufferingFromSuccess() {
    // YOUR TEST CODE HERE
}

The publish condition must be a value of the ReportEntry.PublishCondition enum, which has the following values:

ALWAYS

The extension will always publish your entry when the test runs, regardless of its outcome. (This is the default.)

ON_SUCCESS

The extension will publish your report entry if the test finishes successfully.

ON_FAILURE

The extension will publish your report entry if the test fails.

ON_ABORTED

The extension will publish your report entry if the test was aborted (for example because of an Assumption).

Entries will always be published after the test finished.

Publishing test parameters

You can access @ParameterizedTest parameter values and publish them with the @ReportEntry annotation. Add a number (starting from zero) between curly braces to reference the argument with that index. This works just like arguments in Java’s MessageFormat and is in line with how you reference test parameters when customizing the Display Name of a ParameterizedTest. Inside the report entry, the parameters can be referenced in any order and multiple times. For example, if you have a @ParameterizedTest like the following:

@ParameterizedTest
@CsvSource({"Hello, 21", "World, 42"})
@ReportEntry("{1} - {0} - {1}")
void test(String line, int number) {
    // YOUR TEST CODE HERE
}

Then the extension will publish "21 - Hello - 21" and "42 - World - 42".

Accessing test parameters in the key of the report entry is unsupported.

Thread-Safety

This extension is safe to use during parallel test execution.