<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<head>
    <name>grobo-report: GroboCoverage Ant Tasks</name>
    <doc-version>$Date: 2004/04/18 20:11:05 $</doc-version>
    <author>Matt Albrecht</author>
</head>
<body>

<P>
<link name="v2_antdoc">All Tasks</link>
</P>

<anttask name="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 (<code>safe</code>, <code>cache</code>, and
    <code>fast</code>) natively.  Other formats will need a
    <code>&lt;logFilter&gt;</code> tag to translate its format to the
    standard.
    <P>
    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.
    </P>
    </description>
    
    <ant-nested-element name="logFilter">
        <description>Translates the probe log format from the one used
        by the logger specified in the <code><link
        name="v2_antdoc_grobo-instrument">&lt;grobo-instrument&gt;</link></code>
        task to the standard format.  Currently, this only needs to be
        specified if you use the "single" logger.
        </description>
        <ant-parameter>
            <attribute>type</attribute>
            <description>the logger native format to translate from.
            Defaults to "none".  Alternate value is "single".</description>
            <required>No</required>
        </ant-parameter>
    </ant-nested-element>
    
    <ant-nested-element name="xml">
        <description>Simply copies the XML passed to all report
        types to disk.</description>
        <ant-parameter>
            <attribute>prefix</attribute>
            <description>The text to prefix all output XML files
            (defaults to <code>CoverageReport-</code>).</description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>suffix</attribute>
            <description>The text to suffix all output XML files
            (defaults to <code>.xml</code>).</description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>destDir</attribute>
            <description>The directory to place the XML report files.
            </description>
            <required>Yes</required>
        </ant-parameter>
    </ant-nested-element>
    
    <ant-nested-element name="xsl">
        <description>
        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 <code>param</code> tags.
        </description>
        <ant-nested-element name="param">
            <description>
            Used to pass a parameter to the underlying XSL stylesheet.
            The usage is exactly like the <code>param</code> structure
            for the <ant-link href="CoreTasks/style.html">style</ant-link>
            Ant task.
            </description>
            <ant-parameter>
                <attribute>name</attribute>
                <description>Name of the XSL parameter</description>
                <required>Yes</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>expression</attribute>
                <description>Text value to be placed into the param.</description>
                <required>Yes</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>if</attribute>
                <description>The param will only pass if this property is
                set.</description>
                <required>No</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>unless</attribute>
                <description>The param will only pass unless this property is
                set.</description>
                <required>No</required>
            </ant-parameter>
        </ant-nested-element>
        <ant-parameter>
            <attribute>style</attribute>
            <description>The XSL-T file.
            </description>
            <required>One of <code>style</code> or
            <code>styleURL</code> must be specified.</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>styleURL</attribute>
            <description>A URL pointing to the XSL-T file.
            </description>
            <required>One of <code>style</code> or
            <code>styleURL</code> must be specified.</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>prefix</attribute>
            <description>The text to prepend all output HTML file names.
            The output name will look like
            <code><i>prefix</i>ModuleName<i>suffix</i></code>.  Default
            prefix is <code>CoverageReport-</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>suffix</attribute>
            <description>The text to append to all output HTML file names.
            The output name will look like
            <code><i>prefix</i>ModuleName<i>suffix</i></code>.  Default
            prefix is <code>CoverageReport-</code>.  Default suffix is
            <code>.html</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>destdir</attribute>
            <description>The output directory to place the HTML files.
            Default directory is <code>.</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>removeEmpty</attribute>
            <description>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 <code>false</code>.
            </description>
            <required>No</required>
        </ant-parameter>
    </ant-nested-element>
    
    <ant-nested-element name="simplehtml">
        <description>
        Based on the <code>XSL</code> report task above.  This uses a built-in
        XSL-T stylesheet to generate one HTML file for each analysis
        module<special-text>, which look something like
        <link name="CoverageReport-LineCount">this</link></special-text>.
        <P>
        All of the attributes and nested elements are identical to the
        <code>XSL</code> style above, except that this will fail if either
        <code>style</code> or <code>styleURL</code> are specified.
        </P>
        <P>
        This report task is also aliased as <code>simple</code>.
        </P>
        </description>
    </ant-nested-element>
    
    <ant-nested-element name="sourcexsl">
        <description>
        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.
        <P>
        This report task takes <code>param</code> tags just as the
        <code>xsl</code> report task above.  All defined parameters will
        be passed to every stylesheet.
        </P>
        </description>
        <ant-nested-element name="rootstyle">
            <description>Defines an XSL stylesheet that runs against
            the base complex XML report, and puts its files into the
            root report output directory.
            </description>
            <ant-parameter>
                <attribute>file</attribute>
                <description>file location of the stylesheet</description>
                <required>One of <code>file</code> or <code>url</code>
                must be specified</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>url</attribute>
                <description>URL location of the stylesheet</description>
                <required>One of <code>file</code> or <code>url</code>
                must be specified</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>dest</attribute>
                <description>text appended to the root report output
                directory name for the output file name
                (be sure to include the leading '/')
                </description>
                <required>Yes</required>
            </ant-parameter>
        </ant-nested-element>
        <ant-nested-element name="file">
            <description>Defines a file that will be copied into the root report
            output directory.
            </description>
            <ant-parameter>
                <attribute>file</attribute>
                <description>location of the file</description>
                <required>One of <code>file</code> or <code>url</code>
                must be specified</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>url</attribute>
                <description>URL location of the file</description>
                <required>One of <code>file</code> or <code>url</code>
                must be specified</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>dest</attribute>
                <description>text appended to the root report output
                directory name for the output file name
                (be sure to include the leading '/')
                </description>
                <required>Yes</required>
            </ant-parameter>
        </ant-nested-element>
        <ant-nested-element name="packagestyle">
            <description>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.
            </description>
            <ant-parameter>
                <attribute>file</attribute>
                <description>file location of the stylesheet</description>
                <required>One of <code>file</code> or <code>url</code>
                must be specified</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>url</attribute>
                <description>URL location of the stylesheet</description>
                <required>One of <code>file</code> or <code>url</code>
                must be specified</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>dest</attribute>
                <description>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.</description>
                <required>Yes</required>
            </ant-parameter>
        </ant-nested-element>
        <ant-nested-element name="sourcestyle">
            <description>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.
            </description>
            <ant-parameter>
                <attribute>file</attribute>
                <description>file location of the stylesheet</description>
                <required>One of <code>file</code> or <code>url</code>
                must be specified</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>url</attribute>
                <description>URL location of the stylesheet</description>
                <required>One of <code>file</code> or <code>url</code>
                must be specified</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>dest</attribute>
                <description>The output file name will be in the form of
                <i>(root report output directory)</i><code>/</code><i>(package subdirectory</i><code>/</code><i>(java class name without package)</i>
                appended by the contents of this attribute.</description>
                <required>Yes</required>
            </ant-parameter>
        </ant-nested-element>
        
        <ant-parameter>
            <attribute>srcdir</attribute>
            <description>Directory containing the source files.
            </description>
            <required>Yes</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>destdir</attribute>
            <description>The output directory to place the HTML files.
            Default directory is <code>.</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>removeEmpty</attribute>
            <description>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 <code>false</code>.
            </description>
            <required>No</required>
        </ant-parameter>
    
        <ant-nested-element name="srcdir">
            <description>
            In addition to the <code>srcdir</code> attribute, you can include
            multiple source directories for searching.  The first directory
            containing the source file will be used in the report.
            </description>
            <ant-parameter>
                <attribute>name</attribute>
                <description>The name of the directory containing a
                source tree.
                </description>
                <required>Yes</required>
            </ant-parameter>
        </ant-nested-element>
    </ant-nested-element>
    
    <ant-nested-element name="sourcehtml">
        <description>
        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.
        <P>
        All of the attributes and nested elements are identical to the
        <code>sourcexsl</code> style above, except that it includes some
        helper parameters for the underlying XSL stylesheets.
        </P>
        <P>
        This report task is also aliased as <code>source</code>.
        </P>
        </description>
        <ant-parameter>
            <attribute>title</attribute>
            <description>The title text to be placed on the top of every
            HTML file.  Default is <code>Summary Coverage Report</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>footertext</attribute>
            <description>Text to be put at the bottom of every
            center frame's page (default is an advertisement for
            GroboUtils).</description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>footerhref</attribute>
            <description>Link to have the <code>footertext</code>
            point to (default is an advertisement for GroboUtils).</description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>stylesheet</attribute>
            <description>Stylesheet file to use in replacement of
            the default.</description>
            <required>No</required>
        </ant-parameter>
    </ant-nested-element>
    
    <ant-nested-element name="failOn">
        <description>
        Checks the coverage numbers to see if they meet or exceed a build
        requirement.  If the coverage numbers do not meet the specified
        <code>percentage</code>, then it's a failure.  A failure means that
        the <code>property</code> will be set to the actual coverage
        percentage (if <code>property</code> is specified), and the grobo-report
        task will fail after generating its reports if the grobo-report task's
        <code>failonerror</code> is turned on.  If the grobo-report task's
        <code>failonerror</code> is turned off, then the build file can
        fail later by checking if the <code>property</code> is set.
        </description>
        <ant-parameter>
            <attribute>property</attribute>
            <description>The property to set if the coverage number check
            fails.  If it fails, then the property will be set to the
            actual coverage percentage.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>percentage</attribute>
            <description>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).</description>
            <required>Yes</required>
        </ant-parameter>
        <ant-nested-element name="include">
            <description>
            Much like a FileSet's <code>include</code> tag.  This specifies
            a classname filter that will be included in the coverage
            percentage totals.  If no <code>include</code> tag is given,
            then there's an implicit <code>include</code> that matches
            everything.
            </description>
            <ant-parameter>
                <attribute>module</attribute>
                <description>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.
                </description>
                <required>One of <code>module</code> or <code>class</code>
                is required.</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>class</attribute>
                <description>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.
                </description>
                <required>One of <code>module</code> or <code>class</code>
                is required.</required>
            </ant-parameter>
        </ant-nested-element>
        <ant-nested-element name="exclude">
            <description>
            Much like a FileSet's <code>exclude</code> tag.  This specifies
            a classname filter that will be ignored in the coverage
            percentage totals.
            </description>
            <ant-parameter>
                <attribute>module</attribute>
                <description>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.
                </description>
                <required>One of <code>module</code> or <code>class</code>
                is required.</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>class</attribute>
                <description>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.
                </description>
                <required>One of <code>module</code> or <code>class</code>
                is required.</required>
            </ant-parameter>
        </ant-nested-element>
    </ant-nested-element>

    <ant-parameter>
        <attribute>logDir</attribute>
        <description>The name of the directory containing the coverage data,
        as specified in the <link name="v2_antdoc_grobo-instrument">
        grobo-instrument</link> task.
        </description>
        <required>Yes</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>failonerror</attribute>
        <description>Boolean describing if an error in this task should cause
        the build to fail (default is <tt>false</tt>).  This has particular
        importance with the <code>FailOn</code> sub-task.
        </description>
        <required>No</required>
    </ant-parameter>
    <ant-example>
        <source>
&lt;grobo-report logdir="coverage/log" &gt;
    &lt;xml destdir="coverage/reports" /&gt;
&lt;/grobo-report&gt;
        </source>
        <description>
        Generates one <tt>.xml</tt> file
        for each analysis module used while generating the class files, and
        one <tt>.xml</tt> file that combines all the analysis module data.
        </description>
    </ant-example>
    <ant-example>
        <source>
&lt;grobo-report logdir="coverage/log"&gt;
    &lt;simplestyle destdir="${dirs.test-output}" removeempty="true" /&gt;
    &lt;sourcestyle destdir="${dirs.test-output}/source-report"
        removeempty="true" srcdir="src"
        title="Summary Coverage Report of My Code"&gt;
        
        &lt;srcdir name="${dirs.temp}/generated-source-1" /&gt;
        &lt;srcdir name="${dirs.temp}/generated-source-2" /&gt;
    &lt;/sourcestyle&gt;
&lt;/grobo-report&gt;
        </source>
        <description>
        Generates two human-readable reports.
        The first (simplestyle) generates one HTML file in the
        <tt>${dirs.test-output}</tt> directory for each analysis module
        XML report.  <special-text>The generated file will
        look something like <link name="CoverageReport-LineCount">this</link>.
        </special-text>
        <p>
        The second (sourcestyle) generates a directory hierarchy of framed
        HTML pages in the <tt>${dirs.test-output}/source-report</tt>
        directory.  It links the original Java source files into the HTML
        by looking in the directories <code>src</code>,
        <code>${dirs.temp}/generated-source-1</code>, and
        <code>${dirs.temp}/generated-source-2</code> for the source files
        corresponding to the covered class files, in that order.
        </p>
        </description>
    </ant-example>
    <ant-example>
        <source>
&lt;grobo-report logdir="coverage/log" &gt;
    &lt;failon property="coverage-failed" percentage="80"&gt;
        &lt;exclude module="bytecode" /&gt;
        
        &lt;include class="net.sf.**" /&gt;
        &lt;exclude class="net.sf.**.*Test" /&gt;

        &lt;include class="org.apache.tools.ant.Proj*" /&gt;
        &lt;include class="org.apache.tools.ant.taskdefs.*" /&gt;
    &lt;/failon&gt;
&lt;/grobo-report&gt;
&lt;fail if="coverage-failed"&gt;
Code coverage was not sufficient: expected 80%, but found ${coverage-failed}%.
&lt;/fail&gt;
        </source>
        <description>
        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 <code>coverage-failed</code>
        is not set, and the build succeeds.  If the percentage is below
        80%, then the property <code>coverage-failed</code> is set,
        the task <code>grob-report</code> does not fail (the default
        value of the <code>failonerror</code> parameter is false), but the
        "if" condition on the <code>fail</code> task is fulfilled and the
        build fails there.
        <p>
        Since the <code>failon</code> report task only excludes the
        "bytecode" module, all other modules used by the
        <code>grobo-instrument</code> task will have their coverage
        numbers included in the tally.  Implicitly, the report task
        includes all modules and excludes the ones given.
        </p>
        <p>
        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.
        </p>
        </description>
    </ant-example>
    <ant-example>
        <source>
&lt;grobo-report logdir="coverage/log" failonerror="true"&gt;
    &lt;failon percentage="65.2"&gt;
        &lt;include module="bytecode" /&gt;
    &lt;/failon&gt;
    &lt;failon percentage="70"&gt;
        &lt;include module="linecount" /&gt;
    &lt;/failon&gt;
&lt;/grobo-report&gt;
        </source>
        <description>
        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 <code>grobo-report</code> task
        fails with the error details; if both fail, then both reports
        details are given.
        </description>
    </ant-example>
</anttask>

<P>
<link name="v2_antdoc">All Tasks</link>
</P>

</body>
</document>

