About GroboUtils

For Developers

grobo-report: GroboCoverage Ant Tasks

Author:Matt Albrecht

grobo-report

Description

Tallies the coverage log data from the classes that were logged during runtime execution, and combines it with the post-compilation generated data, to allow for a set of different reports to be created. Reports are specified as a set of sub-tasks. Currently, this task supports all included channel outputs (safe, cache, and fast) natively. Other formats will need a <logFilter> tag to translate its format to the standard.

Note that there are two different categories of reports: simple and complex. The simple report types generate one report per analysis module. The complex reports generate one report that's based on all the analysis modules.

Nested Elements

logFilter

Translates the probe log format from the one used by the logger specified in the <grobo-instrument> task to the standard format. Currently, this only needs to be specified if you use the "single" logger.

Parameters

Attribute	Description	Required
`type`	the logger native format to translate from. Defaults to "none". Alternate value is "single".	No

xml

Simply copies the XML passed to all report types to disk.

Parameters

Attribute	Description	Required
`prefix`	The text to prefix all output XML files (defaults to `CoverageReport-`).	No
`suffix`	The text to suffix all output XML files (defaults to `.xml`).	No
`destDir`	The directory to place the XML report files.	Yes

xsl

Uses an XSL-T stylesheet to transform the simple XML reports into another format. It accepts parameters to pass to the XSL-T stylesheet in the form of param tags.

Parameters

Attribute	Description	Required
`style`	The XSL-T file.	One of `style` or `styleURL` must be specified.
`styleURL`	A URL pointing to the XSL-T file.	One of `style` or `styleURL` must be specified.
`prefix`	The text to prepend all output HTML file names. The output name will look like `prefixModuleNamesuffix`. Default prefix is `CoverageReport-`.	No
`suffix`	The text to append to all output HTML file names. The output name will look like `prefixModuleNamesuffix`. Default prefix is `CoverageReport-`. Default suffix is `.html`.	No
`destdir`	The output directory to place the HTML files. Default directory is `.`.	No
`removeEmpty`	A boolean value. This describes whether the output report should remove all methods and classes that don't have any code attributed to them (such as interfaces and abstract methods). Default is `false`.	No

Nested Elements

param

Used to pass a parameter to the underlying XSL stylesheet. The usage is exactly like the param structure for the style Ant task.

Parameters

Attribute	Description	Required
`name`	Name of the XSL parameter	Yes
`expression`	Text value to be placed into the param.	Yes
`if`	The param will only pass if this property is set.	No
`unless`	The param will only pass unless this property is set.	No

simplehtml

Based on the XSL report task above. This uses a built-in XSL-T stylesheet to generate one HTML file for each analysis module, which look something like this.

All of the attributes and nested elements are identical to the XSL style above, except that this will fail if either style or styleURL are specified.

This report task is also aliased as simple.

sourcexsl

Uses a set of XSL-T styesheets to transform several XML files into reports. The XML files include the complex XML report, a per-package XML report, and an XML report per Java source file that includes the Java source (if available). This allows the user to generate their own source-linked reports.

This report task takes param tags just as the xsl report task above. All defined parameters will be passed to every stylesheet.

Parameters

Attribute	Description	Required
`srcdir`	Directory containing the source files.	Yes
`destdir`	The output directory to place the HTML files. Default directory is `.`.	No
`removeEmpty`	A boolean value. This describes whether the output report should remove all methods and classes that don't have any code attributed to them (such as interfaces and abstract methods). Default is `false`.	No

Nested Elements

rootstyle

Defines an XSL stylesheet that runs against the base complex XML report, and puts its files into the root report output directory.

Parameters

Attribute	Description	Required
`file`	file location of the stylesheet	One of `file` or `url` must be specified
`url`	URL location of the stylesheet	One of `file` or `url` must be specified
`dest`	text appended to the root report output directory name for the output file name (be sure to include the leading '/')	Yes

file

Defines a file that will be copied into the root report output directory.

Parameters

Attribute	Description	Required
`file`	location of the file	One of `file` or `url` must be specified
`url`	URL location of the file	One of `file` or `url` must be specified
`dest`	text appended to the root report output directory name for the output file name (be sure to include the leading '/')	Yes

packagestyle

Defines an XSL stylesheet that runs against the package XML report, once per package, and puts its files into the package directory, under the root report output directory.

Parameters

Attribute	Description	Required
`file`	file location of the stylesheet	One of `file` or `url` must be specified
`url`	URL location of the stylesheet	One of `file` or `url` must be specified
`dest`	Text appended to the package directory file name for the output file name. Be sure to include the leading '/' if this output file is unique per package.	Yes

sourcestyle

Defines an XSL stylesheet that runs against the source-linked XML report, once per Java source file, and puts its files into the package directory, under the root report output directory.

Parameters

Attribute	Description	Required
`file`	file location of the stylesheet	One of `file` or `url` must be specified
`url`	URL location of the stylesheet	One of `file` or `url` must be specified
`dest`	The output file name will be in the form of (root report output directory)`/`(package subdirectory`/`(java class name without package) appended by the contents of this attribute.	Yes

srcdir

In addition to the srcdir attribute, you can include multiple source directories for searching. The first directory containing the source file will be used in the report.

Parameters

Attribute	Description	Required
`name`	The name of the directory containing a source tree.	Yes

sourcehtml

Generates a JavaDoc-like collection of HTML files for all the analysis modules, linking the coverage reports to the source files. This report shows the contents of the source files and highlights whichever lines were not covered.

All of the attributes and nested elements are identical to the sourcexsl style above, except that it includes some helper parameters for the underlying XSL stylesheets.

This report task is also aliased as source.

Parameters

Attribute	Description	Required
`title`	The title text to be placed on the top of every HTML file. Default is `Summary Coverage Report`.	No
`footertext`	Text to be put at the bottom of every center frame's page (default is an advertisement for GroboUtils).	No
`footerhref`	Link to have the `footertext` point to (default is an advertisement for GroboUtils).	No
`stylesheet`	Stylesheet file to use in replacement of the default.	No

failOn

Checks the coverage numbers to see if they meet or exceed a build requirement. If the coverage numbers do not meet the specified percentage, then it's a failure. A failure means that the property will be set to the actual coverage percentage (if property is specified), and the grobo-report task will fail after generating its reports if the grobo-report task's failonerror is turned on. If the grobo-report task's failonerror is turned off, then the build file can fail later by checking if the property is set.

Parameters

Attribute	Description	Required
`property`	The property to set if the coverage number check fails. If it fails, then the property will be set to the actual coverage percentage.	No
`percentage`	The minimum percent coverage required for the build to pass. If the percentage is not met, then the failOn report task will process its failure conditions (see above).	Yes

Nested Elements

include

Much like a FileSet's include tag. This specifies a classname filter that will be included in the coverage percentage totals. If no include tag is given, then there's an implicit include that matches everything.

Parameters

Attribute	Description	Required
`module`	The module to include in the checks. You can use a '*' at the beginning or at the end of the parameter text as a wildcard (but not both). Modules not included will be ignored when processing the total coverage percentage.	One of `module` or `class` is required.
`class`	The fully-qualified class name to include in the checks. The class filter allows for wildcards ('') in the place of class names or package names (the parts dividing the '.' separators), or you can use a double-wildcard ('') do mean that any class in any sub-package will match. The wildcard ('') may be by itself, at the beginning, or at the end of a package name or class name.	One of `module` or `class` is required.

exclude

Much like a FileSet's exclude tag. This specifies a classname filter that will be ignored in the coverage percentage totals.

Parameters

Attribute	Description	Required
`module`	The module to exclude from the checks. You can use a '*' at the beginning or at the end of the parameter text as a wildcard (but not both). Modules not included will be ignored when processing the total coverage percentage.	One of `module` or `class` is required.
`class`	The fully-qualified class name to exclude from the checks. The class filter allows for wildcards ('') in the place of class names or package names (the parts dividing the '.' separators), or you can use a double-wildcard ('') do mean that any class in any sub-package will match. The wildcard ('') may be by itself, at the beginning, or at the end of a package name or class name.	One of `module` or `class` is required.

Parameters

Attribute	Description	Required
`logDir`	The name of the directory containing the coverage data, as specified in the grobo-instrument task.	Yes
`failonerror`	Boolean describing if an error in this task should cause the build to fail (default is `false`). This has particular importance with the `FailOn` sub-task.	No

Examples

<grobo-report logdir="coverage/log" >
    <xml destdir="coverage/reports" />
</grobo-report>

Generates one .xml file for each analysis module used while generating the class files, and one .xml file that combines all the analysis module data.

<grobo-report logdir="coverage/log">
    <simplestyle destdir="${dirs.test-output}" removeempty="true" />
    <sourcestyle destdir="${dirs.test-output}/source-report"
        removeempty="true" srcdir="src"
        title="Summary Coverage Report of My Code">
        
        <srcdir name="${dirs.temp}/generated-source-1" />
        <srcdir name="${dirs.temp}/generated-source-2" />
    </sourcestyle>
</grobo-report>

Generates two human-readable reports. The first (simplestyle) generates one HTML file in the ${dirs.test-output} directory for each analysis module XML report. The generated file will look something like this.

The second (sourcestyle) generates a directory hierarchy of framed HTML pages in the ${dirs.test-output}/source-report directory. It links the original Java source files into the HTML by looking in the directories src, ${dirs.temp}/generated-source-1, and ${dirs.temp}/generated-source-2 for the source files corresponding to the covered class files, in that order.

<grobo-report logdir="coverage/log" >
    <failon property="coverage-failed" percentage="80">
        <exclude module="bytecode" />
        
        <include class="net.sf.**" />
        <exclude class="net.sf.**.*Test" />

        <include class="org.apache.tools.ant.Proj*" />
        <include class="org.apache.tools.ant.taskdefs.*" />
    </failon>
</grobo-report>
<fail if="coverage-failed">
Code coverage was not sufficient: expected 80%, but found ${coverage-failed}%.
</fail>

Checks if the percent coverage on the qualified classes in the qualified modules was at or above 80%. If the percentage is at or above 80%, then the property coverage-failed is not set, and the build succeeds. If the percentage is below 80%, then the property coverage-failed is set, the task grob-report does not fail (the default value of the failonerror parameter is false), but the "if" condition on the fail task is fulfilled and the build fails there.

Since the failon report task only excludes the "bytecode" module, all other modules used by the grobo-instrument task will have their coverage numbers included in the tally. Implicitly, the report task includes all modules and excludes the ones given.

As for the included classes, that gets tricky. All classes under the "net.sf" package (and in that package) are included, except for classes that end with the text "Test". All classes in the "org.apache.tools.ant" package that start with the text "Proj" are included. All classes in the "org.apache.tools.ant.taskdefs" are included, but none of the classes in the sub-packages.

<grobo-report logdir="coverage/log" failonerror="true">
    <failon percentage="65.2">
        <include module="bytecode" />
    </failon>
    <failon percentage="70">
        <include module="linecount" />
    </failon>
</grobo-report>

Checks if the percent coverage on the qualified classes in the qualified modules was at or above 65.2% for the bytecode module, and at or above 70% for the linecount module. If the percentage counts are both met, then the build continues. However, if either check fails, then the grobo-report task fails with the error details; if both fail, then both reports details are given.

All Tasks


This space graciously provided by the SourceForge project	Copyright © 2002-2004 GroboUtils Project. All rights reserved.