clover-report

Description

The <clover-report> task generates current and historical reports in multiple formats. The basic nesting of elements within the <clover-report> task is as follows:

Parameters

Nested elements of <clover-report>

These elements represent the actual reports to be generated. You can generate multiple reports by specifying more than one of these inside a <clover-report> element. Each report will contain links to the other reports. See #Linked Report Example.

<current>

Generates a current coverage report. Specify the report format using a nested #Format element. Valid formats are XML, HTML and PDF, although not all configurations support all formats. The default format is PDF if summary="true", or XML if not. See #Examples of Current Report Configurations.

Parameters

<historical>

Generates a historical coverage report. Specify the report format using a nested Format element (see below). Valid formats are HTML or PDF. The default format is PDF. Contents of the historical report are optionally controlled by nested elements. See #Nested elements of <historical>.

Parameters

Nested elements of <current>

<fileset>

<current> supports nested filesets which control which source files are to be included in a report. Only classes which are from the source files in the fileset are included in the report. This allows reports to focus on certain packages or particular classes. By using Ant's fileset selectors, more complicated selections are possible, such as the files which have recently changed, or files written by a particular author.

<sourcepath>

Specifies an Ant path that Clover should use when looking for source files.

<testsources>

<testsources> is an Ant fileset that can be used to distinguish test source code from application source code. All files included in the fileset will be displayed in the separate 'Test' node of the coverage tree. If omitted, Clover's default test detection algorithm will be used to distinguish test sources.
 

<testresults>

<testresults> is an optional Ant fileset that Clover uses to integrate the results of your unit tests into the report. The results should be generated using the Ant junit task with an XML formatter.

<testresults> is generally not required by most users, as the built-in test results will provide all required information in the majority of cases. For more details please see 'Advanced Usage'.

Nested elements of <historical>

These elements represent individual sections of the historical report. If you do not specify any of these elements, all the sections will be included in the report. If you specify more one or more of these elements, only the specified sections will be included. You may specify multiple <overview> and <coverage> elements in the historical report. These may have different properties and include different elements. The charts will appear in the report in the same order they appear in the <historical> element. The <movers> element always appears at the end of the report following these charts regardless of its location in the <historical> element.

<overview>

Specifies a section that provides summary of the total percentage coverage at the last history point. This element does not support any attributes.

<coverage>

Specifies a chart showing percentage coverage over time.

Parameters

<metrics>

Specifies a chart showing other metrics over time.

Parameters

<movers>

Specifies a table that shows those classes that have a coverage delta higher than a specified threshold over a specified time period.

Parameters

The <format> Element

Specifies the output format and various options controlling the rendering of a report.

Parameters

The <columns> Element

Specifies the data columns to be included on summary pages. If not specified, default columns will be output.

Specific columns are defined as sub-elements to this one. See the #Customising Columns Example (below).

Each column element takes an optional format attribute which determines how the column's value is rendered. The format attribute may be one of the following:

• raw — the actual value. Always used for total columns
• bar — render a bar chart (200px wide) showing the coverage percentage
• shortbar — same as bar above, but only 40px wide
• % — The coverage percentage value

Note that bar and % are not valid formats for total columns.

All column elements also take max and/or min threshold attributes. If the value for the column is outside the threshold, the value will be highlighted.

Column Names

Column Attributes

Each of the above column elements can take the following attributes:

Examples of Current Report configurations

<clover-report>
   <current outfile="current.xml"/>
</clover-report>

Generates an XML report of the current coverage.

<clover-report>
   <current outfile="current.pdf">
      <format type="pdf"/>
   </current>
</clover-report>

Generates a PDF report of the current coverage.

<clover-report>
   <current outfile="clover_html" title="My Project" summary="true">
      <format type="html"/>
   </current>
</clover-report>

Generates a summary report, in HTML with a custom title. Note that the "outfile" argument requires a directory instead of a filename.

<clover-report>
   <current outfile="clover_html" title="Util Coverage">
      <format type="html" orderBy="ElementsCoveredAsc"/>
      <testsources dir="src/test" includes="\**/*.java"/>
   </current>
</clover-report>

Generates a detailed coverage report in HTML with output ordered by total number of covered elements, rather than percentage coverage. All source files under src/test will be in the separate 'Test' coverage node in the report.

<clover-report>
   <current outfile="clover_html" title="My Project">
      <format type="html"/>
      <sourcepath>
         <pathelement path="/some/other/location"/>
      </sourcepath>
   </current>
</clover-report>

Generates a source-level report in HTML. Clover will search for source files in the directory /some/other/location.

<tstamp>
   <format property="report.limit" pattern="MM/dd/yyyy hh:mm aa"
       offset="-1" unit="month"/>
</tstamp>
<clover-report>
   <current outfile="report-current"
          title="Coverage since ${report.limit}">
      <fileset dir="src/main">
         <date datetime="${report.limit}" when="after"/>
      </fileset>
      <format srclevel="true" type="html"/>
   </current>
</clover-report>

This example generates a current coverage report for all files in the project that have changed in the last month. Replacing the <date> selector with <contains text="@author John Doe"/> would generate a coverage report for all code where John Doe is the author.

<clover-report>
<current outfile="report-current" title="Coverage">
<fileset dir="src">
<patternset refid="clover.files"/>
</fileset>
<format srclevel="true" type="html"/>
</current>
</clover-report>

In this example the standard Clover patternset is used to restrict the report to the currently included source files. You could use this if you have changed the exclude or include definitions in the <clover-setup> task and you have not removed the coverage database. It will prevent classes, currently in the database but now excluded, from being included in the report. It is prudent, however, to delete the coverage database, coverage information and recompile when you change these settings.

Example of customising columns

<clover-report>
   <current outfile="report-current" title="Coverage">
      <format type="html"/>
      <columns>
         <coveredMethods format="bar" min="75"/>
         <coveredStatements format="%"/>
         <coveredBranches format="raw"/>
      </columns>
   </current>
</clover-report>

Generates a HTML report that will only include a bar chart showing the percentage of methods covered, the actual percentage of statements covered and the actual number of branches covered. If less than 75% of methods are covered, those values will be highlighted.

Example of linked reports

<clover-report>
      <current outfile="report1" title="Coverage Report 1">
        <format type="html"/>
        <fileset dir="src">
          <patternset refid="clover.files"/>
        </fileset>
      </current>

     <current outfile="report2" title="Coverage Report 2">
        <format type="html"/>
        <fileset dir="othersrc">
          <patternset refid="other.clover.files"/>
        </fileset>
     </current>
    </clover-report>

Generates two HTML reports. Each of these reports will contain a link to the other.

Examples of Historical Report Configurations

<clover-report>
   <historical outfile="historical.pdf"
               historyDir="clover_history">
   </historical>
</clover-report>

Generates a historical report in PDF. Assumes that <clover-historypoint> has generated more than one history file in the directory "clover_history". Writes the output to the file specified in the outfile parameter.

<clover-report>
   <historical outfile="two_months" title="My Project"
               from="020101" to="020301" dateFormat="yyMMdd"
               historyDir="clover_history">
      <format type="html"/>
   </historical>
</clover-report>

Generates a basic historical report in HTML for a certain time period. Clover will scan the historyDir and use any history points that fall within the requested time period. The outfile attribute will be treated as a directory; a file historical.html will be written into this directory. If the directory doesn't exist, it will be created.

<clover-report>
   <historical outfile="report.pdf" title="My Project"
               historyDir="clover_history">
      <overview/>
      <movers threshold="5%" range="20" interval="2w"/>
   </historical>
</clover-report>

Generates a PDF historical report that only includes an overview section (showing summary coverage at the last history point) and a movers table showing classes that have a code coverage delta of greater than +- 5% over the two weeks prior to the last history point. Will include at most 20 gainers and 20 losers.