clover-report
はじめに
The <clover-report>
task generates current and historical reports in multiple formats.
If you do not require fine-grained control over your Clover reports, use the <clover-html-report>
or <clover-pdf-report>
tasks.
このページの内容
概要
The basic nesting of elements within the <clover-report>
task is as follows: (click any item for detailed user documentation).
<clover-report>
<current>
<columns>
(one or more columns)
</columns/>
<fileset/>
<format/>
<sourcepath/>
<testsources/>
<testresults/>
</current>
<historical>
<added>
<columns>
(a single column)
</columns/>
</added>
<chart>
(one or more columns)
</chart/>
<coverage/>
<format/>
<metrics/>
<movers>
<columns>
(a single column)
</columns/>
</movers>
<overview/>
</historical>
</clover-report>
パラメーター
The <clover-report>
task generates current and historical reports in multiple formats. Parameters for <clover-report>:
属性 | 説明 | 必須 |
---|---|---|
coverageCacheSize | This is a performance tuning option, which is used to specify the maximum size of coverage data kept in memory when generating a report. Accepts storage values such as 256m (256 megabytes) or 1g (1 gigabyte). Also accepts the value "nocache" to force all coverage data to be loaded into memory. | No. Default is 256m. |
initstring | The initstring of the coverage database. | No; if not specified here, Clover will look in the default location ( |
failOnError | If true, failure to generate a report causes a build failure. | No; defaults to " |
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. |
ネスト要素
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 clover-report.
<current>
Generates a current coverage report. Specify the report format using a nested Format element. Valid formats are XML, HTML, PDF and JSON, although not all configurations support all formats. The default format is PDF if summary="true", or XML if not. See clover-report.
Parameters for <current>
属性 | 説明 | 必須 |
---|---|---|
alwaysReport | If set to true, a report will be generated even in the absence of coverage data. | No; defaults to " |
文字セット | The character set to use in the HTML reports. | No. Default is UTF-8 |
homepage | Specifies the start page to use. This can be one of the predefined pages: | No; defaults to " |
includeFailedTestCoverage | Specifies whether or not to include coverage attributed to a test that has failed. | No; default is " |
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 |
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. |
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, JSON). | はい。 |
span | Specifies how far back in time to include coverage recordings from since the last Clover build. See Using Spans. | No; default includes "all coverage data found". |
要約 | Specifies whether to generate a summary report or detailed report. Currently this applies for XML and PDF reports. See srcLevel on the format element for HTML. | No; defaults to " |
showLambdaFunctions | Whether to present lambda functions in the report. If set to false, they are hidden on the methods' list, but code metrics still include them. | No; defaults to "false ". |
showInnerFunctions | Whether to show inner functions, i.e. functions declared inside methods in the report. This applies to Java8 lambda functions for instance. If set to false, then they are hidden on the methods' list, but code metrics still include them. | No; defaults to "false ". |
showUniqueCoverage | Calculate and show unique per-test coverage (for large projects, this can take a significant amount of time). Defaults to | いいえ。 |
タイムアウト | 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. |
title | Specifies a title for the report. | いいえ。 |
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 | No; default is " |
Nested elements of <current>
These elements represent individual sections of the 'current' 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 'current' 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 <current> element. The <movers> element always appears at the end of the report following these charts regardless of its location in the <current> element.
<columns>
Specific columns are defined as sub-elements to this one. See the clover-report.
Columns can be defined in a <clover-columns/> Ant type for referencing elsewhere in the build file.
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 columnsbar
— render a bar chart (40px wide) showing the coverage percentagelongbar
— same asbar
above, except 200px 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.
Table of Column Names
列 | 説明 | Valid Format Attributes |
---|---|---|
avgClassesPerFile | The average number of classes per file. |
|
avgMethodComplexity | The average number of paths per method. |
|
avgMethodsPerClass | The average number of methods per class. |
|
avgStatementsPerMethod | The average number of statements per method. |
|
complexity | Cyclomatic Complexity is a measure of the number of paths in your code. |
|
complexityDensity | The average complexity per statement. |
|
coveredBranches | The amount of covered branches. |
|
coveredElements | The total number of covered elements (branches + statements) in the project. |
|
coveredMethods | The amount of covered methods. |
|
coveredStatements | The amount of covered statements. |
|
expression | The body of this element will be evaluated as an arithmetic expression. All other column names can be referenced. See Clover EL. This column takes an optional title attribute. | raw |
filteredElements | The amount of elements that have been filtered out of the report. |
|
ncLineCount | The total number of non-comment lines. |
|
lineCount | The total number of lines. |
|
SUM | Scientifically Untested Metric. This is very similar to crap4j and is defined by this expression:
| raw |
percentageCoveredContribution | Helps you to work out how much an individual package, file or class contributes (percentage-wise) to the overall number of covered elements in the project. Useful for spotting quick wins. | raw;bar;%;longbar |
percentageUncoveredContribution | Helps you to work out how much an individual package, file or class contributes (percentage-wise) to the overall number of uncovered elements in the project. Useful for spotting quick wins. | raw;bar;%;longbar |
totalBranches | The total number of branches in the project. |
|
totalChildren | The number of lower order elements. The order of elements is: Project, Package, File, Class, Method, Statement |
|
totalClasses | The total number of classes below the package, project or file. |
|
totalElements | The total number of elements (branches + statements) in the project. |
|
totalFiles | The total number of files below the package or project. |
|
totalMethods | The total number of methods in the project. |
|
totalPercentageCovered | The total coverage. |
|
totalStatements | The total number of statements in the project. |
|
uncoveredBranches | Branches that were not executed. | raw;bar;%;longbar |
uncoveredElements | Elements that were not executed. | raw;bar;%;longbar |
uncoveredMethods | Methods that were not executed. | raw;bar;%;longbar |
uncoveredStatements | Statements that were not executed. | raw;bar;%;longbar |
Column Attributes
Each of the above column elements can take the following attributes:
属性 | 説明 | 必須 |
---|---|---|
フォーマット | Determines how the value is rendered. Depending on the column, this may be one of | いいえ。 |
min | Sets a minimum threshold on the value of the column. If the value is less than this it will be highlighted. | いいえ。 |
max | Sets a maximum threshold on the value of the column. If the value is greater than this it will be highlighted. | いいえ。 |
scope | Controls at which level in the report the column will appear. The scope attribute can be one of: "package", "class" or "method". If omitted, the column will be used at every level in the report. Note that only the following columns support the scope attribute: expression, complexity, complexityDensity, coveredXXX, uncoveredXXX and totalXXX. | いいえ。 |
Clover Expression Language
Clover Expression Language enables you to combine any of Clover's built-in column types to produce a custom column. The following arithmetic operators are available: +, - , *, /, ^, (). Any of Clover's columns may be referenced.
A percentage sign, '%', before a column identifier will evaluate to the percentage of that columns data, rather than its raw value. e.g. %CoveredElements == (CoveredElements/TotalElements) * 100
Example:
<columns>
<expression title="SUM">complexity^2 * ((1 - %coveredElements/100)^3) + complexity</expression>
</columns>
<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 fileset selectors, more complicated selections are possible, such as the files which have recently changed, or files written by a particular author.
<format>
Parameters for <format>
属性 | 説明 | 必須 |
---|---|---|
type | The output format in which to render the report. Valid values are | Yes, unless |
refid | The id of another format element that will be used for this report. See Sharing Report Formats. | いいえ。 |
ID | The id of this format element. | いいえ。 |
bw | Specify that the report should be black-and-white. Supported by PDF reports only. | No; defaults to " |
orderBy | Specify how to order coverage tables. This attribute has no effect on XML format. Valid values are: | No; defaults to |
noCache | (HTML only) If true, insert nocache directives in HTML output. | No; defaults to " |
srcLevel | If true, include source-level coverage information in the report. | No; defaults to " |
filter | comma or space separated list of contexts to exclude when generating coverage reports. See Using Coverage Contexts. | いいえ。 |
pageSize | (PDF only) Specify the page size to use. Valid values are | No; defaults to " |
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 " |
tabWidth | (Source level reports only) The number of space chars to replace TAB characters with. | No; defaults to |
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. |
callback | The name of the callback function to wrap the JSON. If set to an empty string, " ", then the JSON will not be wrapped. | No; default is 'processClover'. |
<sourcepath>
Specifies an Ant path that Clover should use when looking for source files. This option is useful when sources are located in a different directory than during compilation.
Note that you have to list all source roots (and not just a workspace root), e.g.:
<sourcepath>
<pathelement location="moduleA/src"/>
<pathelement location="moduleA/test"/>
</sourcepath>
In case your source roots have a common naming pattern, you can use a <dirset> with wildcards, e.g.:
<sourcepath>
<dirset dir=".">
<include name="**/src/main/java"/>
<include name="**/src/main/groovy"/>
<include name="**/src/test/java"/>
<include name="**/src/test/groovy"/>
</dirset>
</sourcepath>
<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'.
<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 HTML. Contents of the historical report are optionally controlled by nested elements. See clover-report.
Parameters for <historical>
属性 | 説明 | 必須 |
---|---|---|
title | Specifies a title for the report. | いいえ。 |
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 | No; default is " |
文字セット | The character set to use in the HTML reports. | No. Default is UTF-8 |
日付形式 | 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. |
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. | いいえ。 |
historyDir | The directory containing Clover historical data as produced by the <clover-historypoint> task. | はい。 |
historyIncludes | An Ant GLOB to select specific history point files within the | No; default is |
json | A true or false value. If set to true, then a file called | No. Default is "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) or a directory (HTML). | Yes; default format is HTML. |
package | Restricts the report to a particular package. | いいえ。 |
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. | いいえ。 |
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.
<added>
<added>
displays new classes for the given column.
Parameters for <added>
属性 | 説明 | 必須 |
---|---|---|
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 |
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. |
Nested elements of <added>
The <added> element can take a single column element, allowing you to add one additional metric to the data shown in <added>.
Example: <totalStatements>
You could add totalStatements to <added> with the following code.
<added>
<columns>
<totalStatements/>
</columns>
</added>
No more than one additional column can be attached to <added>. The 'added' classes table will always appear above the Movers section in the report - regardless of its order in the XML.
<chart>
Parameters for <chart>
属性 | 説明 | 必須 |
---|---|---|
title | The title to use for the chart. | いいえ。 |
logscale | Use a log scale for the y axis. | No; default is set to 'true'. |
x 軸ラベル | The x label to use. | いいえ。 |
y 軸ラベル | The x label to use. | いいえ。 |
width | The width of the chart image. | No; default is set to 640 pixels (640px). |
height | The height of the chart image. | No; default is set to 480 pixels (480px). |
upperBound | The maximum y value to display. | No; default is set to -1 (unbounded). |
autoRange | If set to 'true', the y-axis will be chosen automatically to fit the data best. | No; default is 'false'. |
Nested elements of <chart>
The <chart> element can take arbitrary columns, but the format of each column can be only 'raw', or '%'. The supported columns are identical to columns in the <current>element. If no columns nested element is supplied, then the default columns from the <coverage> element are used.
<coverage>
- Note that the 'include' attribute from Clover 2.0 has been replaced by the <columns> element.
Specifies a chart showing percentage coverage over time.
This element does not support any attributes. The default behavior is that everything is included.
<format>
Parameters for <format>
属性 | 説明 | 必須 |
---|---|---|
type | The output format in which to render the report. Valid values are | Yes, unless |
refid | The id of another format element that will be used for this report. See Sharing Report Formats. | いいえ。 |
ID | The id of this format element. | いいえ。 |
bw | Specify that the report should be black-and-white. Supported by PDF reports only. | No; defaults to " |
orderBy | Specify how to order coverage tables. This attribute has no effect on XML format. Valid values are: | No; defaults to |
noCache | (HTML only) If true, insert nocache directives in HTML output. | No; defaults to " |
srcLevel | If true, include source-level coverage information in the report. | No; defaults to " |
filter | comma or space separated list of contexts to exclude when generating coverage reports. See Using Coverage Contexts. | いいえ。 |
pageSize | (PDF only) Specify the page size to use. Valid values are | No; defaults to " |
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 " |
tabWidth | (Source level reports only) The number of space chars to replace TAB characters with. | No; defaults to |
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. |
callback | The name of the callback function to wrap the JSON. If set to an empty string, " ", then the JSON will not be wrapped. | No; default is 'processClover'. |
<metrics>
- Note that the 'include' attribute from Clover 2.0 has been replaced by the <columns> element.
Specifies a chart showing other metrics over time.
Parameters for <metrics>:
属性 | 説明 | 必須 |
---|---|---|
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 " |
The default metrics included in the chart are loc, ncloc, methods and classes.
<movers>
Parameters for <movers>:
属性 | 説明 | 必須 |
---|---|---|
threshold | The absolute point change in percent coverage that class must have changed by for inclusion. e.g " | No; defaults to |
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 |
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. |
Nested elements of <movers>
The <movers> element can take a single column element, allowing you to add one additional metric to the data shown in <movers>.
Example: <totalStatements>
You could add totalStatements to <movers> with the following code.
<movers>
<columns>
<totalStatements/>
</columns>
</movers>
No more than one additional column can be added to <movers>.
<overview>
Specifies a section that provides summary of the total percentage coverage at the last history point. This element does not support any 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" summary="true">
<format type="pdf"/>
</current>
</clover-report>
Generates a PDF report of the current coverage.
<target name="report.json" depends="with.clover">
<clover-report>
<current outfile="clover_json">
<format type="json"/>
<columns>
<lineCount/>
<ncLineCount/>
</columns>
</current>
</clover-report>
</target>
Generates a JSON report, where the chart elements are customized by specifying them with <columns>
. See the JSON reference page.
<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="report-current" title="Coverage">
<fileset dir="src/main/java">
<exclude name="**/*Blah.java"/>
</fileset>
<format srclevel="true" type="html"/>
</current>
</clover-report>
Generates a HTML clover report and excludes all *Blah.java classes from the report.
<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 customizing 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">
<format type="pdf"/>
</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"/>
<format type="pdf"/>
</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.