Configuration of Reports

Before stepping any further into using the project Web site, it is important to understand how the report configuration is handled in Maven.

You might recall from Chapter 2 that a plugin is configured using the configuration element inside the plugin declaration in pom.xml, for example:

[...]
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <source>1.5</source>
                <target>1.5</target>
            </configuration>
        </plugin>
    </plugins>
</build>
[...]

Configuration for a reporting plugin is very similar, however it is added to the reporting section of the POM. For example, the report can be modified to only show test failures by adding the following configuration in pom.xml:

[...]
<reporting>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-report-plugin</artifactId>
            <configuration>
                <showSuccess>false</showSuccess>
            </configuration>
        </plugin>
    </plugins>
</reporting>
[...]

The addition of the plugin element triggers the inclusion of the report in the Web site, as seen in the previous section, while the configuration can be used to modify its appearance or behavior.

If a plugin contains multiple reports, they will all be included.

However, some reports apply to both the site, and the build. To continue with the Surefire report, consider if you wanted to create a copy of the HTML report in the directory target/surefire-reports every time the build ran. To do this, the plugin would need to be configured in the build section instead of, or in addition to, the reporting section:

[...]
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-report-plugin</artifactId>
            <configuration>
                <outputDirectory> ${project.build.directory}/surefire-reports </outputDirectory>
            </configuration>
            <executions>
                <execution>
                    <phase>test</phase>
                    <goals>
                        <goal>report</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
[...]

“Executions” such as this were introduced in Chapter 3. The plugin is included in the build section to ensure that the configuration, even though it is not specific to the execution, is used only during the build, and not site generation.

However, what if the location of the Surefire XML reports that are used as input (and would be configured using the reportsDirectory parameter) were different to the default location? Initially, you might think that you’d need to configure the parameter in both sections. Fortunately, this isn’t the case – adding the configuration to the reporting section is sufficient.

When you configure a reporting plugin, always place the configuration in the reporting section – unless one of the following is true:

1. The reports will not be included in the site.
2. The configuration value is specific to the build stage.

When you are configuring the plugins to be used in the reporting section, by default all reports available in the plugin are executed once. However, there are cases where only some of the reports that the plugin produces will be required, and cases where a particular report will be run more than once, each time with a different configuration.

Both of these cases can be achieved with the reportSets element, which is the reporting equivalent of the executions element in the build section. Each report set can contain configuration, and a list of reports to include. For example, consider if you had run Surefire twice in your build, once for unit tests and once for a set of performance tests, and that you had had generated its XML results to target/surefire-reports/unit and target/surefire-reports/perf respectively.

To generate two HTML reports for these results, you would include the following section in your pom.xml:

[...]
<reporting>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-report-plugin</artifactId>
            <reportSets>
                <reportSet>
                    <id>unit</id>
                    <configuration>
                        <reportsDirectory> ${project.build.directory}/surefire-reports/unit </reportsDirectory>
                        <outputName>surefire-report-unit</outputName>
                    </configuration>
                    <reports>
                        <report>report</report>
                    </reports>
                </reportSet>
                <reportSet>
                    <id>perf</id>
                    <configuration>
                        <reportsDirectory> ${project.build.directory}/surefire-reports/perf </reportsDirectory>
                        <outputName>surefire-report-perf</outputName>
                    </configuration>
                    <reports>
                        <report>report</report>
                    </reports>
                </reportSet>
            </reportSets>
        </plugin>
    </plugins>
</reporting>
[...]

Running mvn site with this addition will generate two Surefire reports: target/site/surefire-report-unit.html and target/site/surefire-report-perf.html.

However, as with executions, running mvn surefire-report:report will not use either of these configurations. When a report is executed individually, Maven will use only the configuration that is specified in the plugin element itself, outside of any report sets.

The reports element in the report set is a required element. If you want all of the reports in a plugin to be generated, they must be enumerated in this list. The reports in this list are identified by the goal names that would be used if they were run from the command line.

*It is also possible to include only a subset of the reports in a plugin. For example, to generate only the mailing list and license pages of the standard reports, add the following to the reporting section of the pom.xml file:

[...]
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-project-info-reports-plugin</artifactId>
    <reportSets>
        <reportSet>
            <reports>
                <report>mailing-list</report>
                <report>license</report>
            </reports>
        </reportSet>
    </reportSets>
</plugin>
[...]

While the defaults are usually sufficient, this customization will allow you to configure reports in a way that is just as flexible as your build.