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:

<clover-report>
   <current>
      <fileset/>
      <sourcepath/>
      <format/>
      <columns/>
      <testresults/>
      <testsources/>
   </current>
   <historical>
      <format/>
      <overview/>
      <coverage/>
      <metrics/>
      <movers/>
   </historical>
</clover-report>

Note
If you do not require such fine-grained control over your Clover reports, use the <clover-html-report> or <clover-pdf-report> tasks.

Parameters

Attribute	Description	Required
initstring	The initstring of the coverage database.	No; if not specified here, Clover will look in the default location (`${basedir}.clover`). If you have specified an `initstring` on the `<clover-setup>` task, you must ensure `<clover-setup>` is called prior the execution of this task.
failOnError	If true, failure to generate a report causes a build failure.	No; defaults to "`true`".
projectName	Overrides the project name set in the Ant build file. This is used for display purposes only.	No; defaults to the project name of the Ant build file.

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

Attribute	Description	Required
title	Specifies a title for the report.	No.
titleAnchor	If specified, the report title will be rendered as a hyperlink to this href.	No; default is to not render the report title as a hyperlink.
titleTarget	Specifies the href target if the title is to be rendered as a hyperlink (see `titleAnchor` above). HTML format only.	No; default is "`_top`".
alwaysReport	If set to true, a report will be generated even in the absence of coverage data.	No; defaults to "`false`".
outfile	The outfile to write output to. If it does not exist, it is created. Depending on the specified format, this either represents a regular file (PDF, XML) or a directory (HTML).	Yes.
summary	Specifies whether to generate a summary report or detailed report.	No; defaults to "`false`".
package	Restricts the report to a particular package.	No.
span	Specifies how far back in time to include coverage recordings from since the last Clover build. See Using Spans.	No; defaults to "`0s`".
maxTestsPerFile	Specifies the maximum number of tests (ranked by coverage contribution) to display on a source file report page. This parameter can be used to reduce the size of reports for projects with very large numbers of tests.	No; unlimited if not specified or `-1.`
includeFailedTestCoverage	Specifies whether or not to include coverage attributed to a test that has failed.	No; default is "`false`".
homepage	Specifies the start page to use. This can be one of the predefined pages: `dashboard`, `overview`, `aggregate`, `testresults`, `quickwins`, `projectrisks` or an arbitrary URL.	No; defaults to "`dashboard`".
numThreads	The number of threads to start when generating an HTML report. A value of 0 will disable multi-threading for report generation.	No. Default is 2.
timeout	The amount of time to wait for report generation to finish before failing the build. This value must be an Interval.	No. Default is no timeout.

<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

Attribute	Description	Required
title	Specifies a title for the report.	No.
titleAnchor	if specified, the report title will be rendered as a hyperlink to this href.	No; default is to not render the report title as a hyperlink.
titleTarget	Specifies the href target if the title is to be rendered as a hyperlink (see `titleAnchor` above). HTML format only	No; default is "`_top`".
outfile	The outfile to write output to. If it does not exist, it is created. Depending on the specified format, this either represents a regular file (PDF) or a directory (HTML).	Yes.
historyDir	The directory containing Clover historical data as produced by the <clover-historypoint> task.	Yes.
historyIncludes	An Ant GLOB to select specific history point files within the `historyDir` directory	No; default is `clover-*.xml.gz`
package	Restricts the report to a particular package.	No.
from	Specifies the date before which data points will be ignored. The date must be specified either using the default java.text.SimpleDateFormat for your locale or using the pattern defined in the "dateFormat" attribute.	No.
to	Specifies the date after which data points will be ignored. The date must be specified either using the default java.text.SimpleDateFormat for your locale or using the pattern defined in the "dateFormat" attribute.	No.
dateFormat	Specifies a date format string for parsing the "from" and "to" fields. The string must contain a valid java.text.SimpleDateFormat pattern.	No; default is set to java.text.SimpleDateFormat using the default pattern and date format symbols for the default locale.

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.

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

Attribute	Description	Required
include	A comma- or space-separated list of coverage metrics to include in the chart. Valid values are: `branches`, `statements`, `methods`, `total`	No; the default is that everything is included.

<metrics>

Specifies a chart showing other metrics over time.

Parameters

Attribute	Description	Required
include	A comma or space separated list of metrics to include in the chart. Valid values are: `loc`, `ncloc`, `statements`, `methods`, `classes`, `files`, `packages`	No; defaults to `loc, ncloc, methods, classes.`
logscale	Specifies that a log scale be used on the Range Axis. This can be useful if you are including, for example, LOC and packages in the same chart.	No; defaults to "`true`".

<movers>

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

Parameters

Attribute	Description	Required
threshold	The absolute point change in percent coverage that class must have changed by for inclusion. e.g "`10%`".	No; defaults to `1%.`
range	The maximum number of classes to show. If the value is 5, then a maximum of 5 "gainers" and 5 "losers" will be shown.	No; defaults to `5.`
interval	The time interval over which the delta should be calculated (from the last history point). Uses the Interval format. The range is automatically adjusted to the closest smaller interval available.	No; the default is to take the delta of the last two history points.

The <format> Element

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

Parameters

Attribute	Description	Required
type	The output format in which to render the report. Valid values are `pdf`, `xml`, `html`. Note that not all reports support all formats.	Yes, unless `refid` is set.
refid	The id of another format element that will be used for this report. See Sharing Report Formats.	No.
id	The id of this format element.	No.
bw	Specify that the report should be black-and-white. This will make HTML reports smaller (with no syntax highlighting) and make PDF reports suitable for printing on a non-colour printer.	No; defaults to "`false`".
orderBy	Specify how to order coverage tables. This attribute has no effect on XML format. Valid values are: `Alpha` — Alpabetical. `PcCoveredAsc` — Percent total coverage, ascending. `PcCoveredDesc` — Percent total coverage, descending. `ElementsCoveredAsc` — Total elements covered, ascending. `ElementsCoveredDesc` — Total elements covered, descending. `ElementsUncoveredAsc` — Total elements uncovered, ascending. `ElementsUncoveredDesc` — Total elements uncovered, descending.	No; defaults to `PcCoveredAsc.`
noCache	(HTML only) If true, insert nocache directives in HTML output.	No; defaults to "`false`".
srcLevel	If true, include source-level coverage information in the report.	No; defaults to "`true`".
filter	comma or space separated list of contexts to exclude when generating coverage reports. See Using Coverage Contexts.	No.
pageSize	(PDF only) Specify the page size to use. Valid values are `A4`, `LETTER.`	No; defaults to "`A4`".
showEmpty	If true, classes, files and packages that do not contain any executable code (i.e. methods, statements, or branches) are included in reports. These are normally not shown.	No; defaults to "`false`".
tabWidth	(Source level reports only) The number of space chars to replace TAB characters with.	No; defaults to `4.`
maxNameLength	The maximum length in chars of package or classnames in the report. Longer names will be truncated. A value < 0 indicates no limit.	No; defaults to no limit.

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	Description	Valid Format Attributes
totalPercentageCovered	The total coverage.	`raw`;`bar`;`%`;`shortbar`
totalElements	The total number of elements (branches + statements) in the project.	`raw`
coveredElements	The total number of covered elements (branches + statements) in the project.	`raw`;`bar`;`%`;`shortbar`
totalBranches	The total number of branches in the project.	`raw`
coveredBranches	The amount of covered branches.	`raw`;`bar`;`%`;`shortbar`
totalStatements	The total number of statements in the project.	`raw`
coveredStatements	The amount of covered statements.	`raw`;`bar`;`%`;`shortbar`
totalMethods	The total number of methods in the project.	`raw`
coveredMethods	The amount of covered methods.	`raw`;`bar`;`%`;`shortbar`
totalChildren	The number of lower order elements. The order of elements is: Project, Package, File, Class, Method, Statement	`raw`
complexity	Cyclomatic Complexity is a measure of the number of paths in your code.	`raw`
avgMethodComplexity	The average number of paths per method.	`raw`
complexityDensity	The average complexity per statement.	`raw`
avgClassesPerFile	The average number of classes per file.	`raw`
avgMethodsPerClass	The average number of methods per class.	`raw`
avgStatementsPerMethod	The average number of statements per method.	`raw`
totalFiles	The total number of files below the package or project.	`raw`
totalClasses	The total number of classes below the package, project or file.	`raw`
lineCount	The total number of lines.	`raw`
ncLineCount	The total number of non-comment lines.	`raw`

Column Attributes

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

Attribute	Description	Required
format	Determines how the value is rendered. Depending on the column, this may be one of `raw`, `bar`, `%` or `shortbar`.	No.
min	Sets a minimum threshold on the value of the column. If the value is less than this it will be highlighted.	No.
max	Sets a maximum threshold on the value of the column. If the value is greater than this it will be highlighted.	No.

The <testresults> fileset element

<testresults> is an 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.

The <testsources> fileset element

<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.

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"/>
      <testresults dir="test/results" includes="TEST*.xml"/>
   </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"/>
      <testresults dir="test/results" includes="TEST*.xml"/>
      <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>
      <testresults dir="test/results" includes="TEST*.xml"/>
   </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"/>
      <testresults dir="test/results" includes="TEST*.xml"/>
   </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.

Customising Columns Example

<clover-report>
   <current outfile="report-current" title="Coverage">
      <format type="html"/>
      <columns>
         <coveredMethods format="bar" min="75"/>
         <coveredStatements format="%"/>
         <coveredBranches format="raw"/>
      </columns>
      <testresults dir="test/results" includes="TEST*.xml"/>
   </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.

Linked Report Example

<clover-report>
      <current outfile="report1" title="Coverage Report 1">
        <format type="html"/>
        <fileset dir="src">
          <patternset refid="clover.files"/>
        </fileset>
        <testresults dir="test/results" includes="TEST*.xml"/>
      </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.

clover-report

Labels:

Description

Parameters

Nested elements of <clover-report>

<current>

Parameters

<historical>

Parameters

Nested elements of <current>

<fileset>

<sourcepath>

Nested elements of <historical>

<overview>

<coverage>

Parameters

<metrics>

Parameters

<movers>

Parameters

The <format> Element

Parameters

The <columns> Element

Column Names

Column Attributes

The <testresults> fileset element

The <testsources> fileset element

Examples of Current Report Configurations

Customising Columns Example

Linked Report Example

Examples of Historical Report Configurations