jacocoPlugin.xml

<!--
  ~ Copyright 2013 the original author or authors.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~      http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<chapter id="jacoco_plugin">
    <title>The JaCoCo Plugin</title>
    <note>
        <para>
            The JaCoCo plugin is currently <link linkend="feature_lifecycle">incubating</link>. Please be aware that the DSL and other configuration may change in later Gradle versions.
        </para>
    </note>

    <para>The JaCoCo plugin provides code coverage metrics for Java code via integration with <ulink url="http://www.eclemma.org/jacoco/">JaCoCo</ulink>.
    </para>
    <section id="sec:jacoco_getting_started">
        <title>Getting Started</title>
        <para>To get started, apply the JaCoCo plugin to the project you want to calculate code coverage for.</para>
        <sample id="applyJacoco" dir="testing/jacoco/quickstart" title="Applying the JaCoCo plugin">
            <sourcefile file="build.gradle" snippet="apply-plugin"/>
        </sample>
        <para>
            If the Java plugin is also applied to your project, a new task named
            <literal>jacocoTestReport</literal>
            is created that depends on the
            <literal>test</literal>
            task.
            The report is available at
            <filename><replaceable>$buildDir</replaceable>/reports/jacoco/test</filename>. By default, a HTML report is generated.
        </para>
    </section>

    <section id="sec:configuring_the_jacoco_plugin">
        <title>Configuring the JaCoCo Plugin</title>
        <para>
            The JaCoCo plugin adds a project extension named <literal>jacoco</literal> of type <apilink class="org.gradle.testing.jacoco.plugins.JacocoPluginExtension"/>,
            which allows configuring defaults for JaCoCo usage in your build.
        </para>
        <sample id="configJacoco" dir="testing/jacoco/quickstart" title="Configuring JaCoCo plugin settings">
            <sourcefile file="build.gradle" snippet="jacoco-configuration"/>
        </sample>
        <table>
            <title>Gradle defaults for JaCoCo properties</title>
            <thead>
                <tr>
                    <td>Property</td>
                    <td>Gradle default</td>
                </tr>
            </thead>
            <tr>
                <td>reportsDir</td>
                <td>“<replaceable>$buildDir</replaceable>/reports/jacoco”
                </td>
            </tr>
        </table>
    </section>
    <section id="sec:jacoco_report_configuration">
        <title>JaCoCo Report configuration</title>
        <para>The
            <apilink class="org.gradle.testing.jacoco.tasks.JacocoReport"/>
            task can be used to generate code coverage reports in different formats.
            It implements the standard Gradle type <apilink class="org.gradle.api.reporting.Reporting"/> and exposes a report container of
            type <apilink class="org.gradle.testing.jacoco.tasks.JacocoReportsContainer" />.
        </para>
        <sample id="configJacocoReport" dir="testing/jacoco/quickstart" title="Configuring test task">
            <sourcefile file="build.gradle" snippet="report-configuration"/>
        </sample>
        <imageobject>
            <imagedata fileref="img/jacocoHtmlReport.png" width="903px" depth="277px"/>
        </imageobject>
    </section>

    <section id="sec:jacoco_report_violation_rules">
        <title>Enforcing code coverage metrics</title>
        <note>
            <para>
                This feature requires the use of JaCoCo version 0.6.3 or higher.
            </para>
        </note>
        <para>
            The <apilink class="org.gradle.testing.jacoco.tasks.JacocoCheck"/> task can be used to verify if code coverage
            metrics are met based on configured rules. Its API exposes two methods,
            <apilink class="org.gradle.testing.jacoco.tasks.JacocoCheck" method="violationRules(groovy.lang.Closure)"/> and
            <apilink class="org.gradle.testing.jacoco.tasks.JacocoCheck" method="violationRules(org.gradle.api.Action)"/>,
            the main entry point for configuring rules.
            Invoking any of those methods returns an instance of <apilink class="org.gradle.testing.jacoco.tasks.rules.JacocoViolationRulesContainer"/> providing
            extensive configuration options. The build fails if any of the configured rules are not met. JaCoCo only reports the first violated rule.
        </para>
        <para>
            Code coverage requirements can be specified for a project as a whole, for individual files, and for
            particular JaCoCo-specific types of coverage, e.g., lines covered or branches covered. The following example
            describes the syntax.
        </para>
        <sample id="configViolationRules" dir="testing/jacoco/quickstart" title="Configuring violation rules">
            <sourcefile file="build.gradle" snippet="violation-rules-configuration"/>
        </sample>
    </section>

    <section id="sec:jacoco_specific_task_configuration">
        <title>JaCoCo specific task configuration</title>
        <para>The JaCoCo plugin adds a
            <apilink class="org.gradle.testing.jacoco.plugins.JacocoTaskExtension"/>
            extension to all tasks of type
            <apilink class="org.gradle.api.tasks.testing.Test"/>.
            This extension allows the configuration of the JaCoCo specific properties of the test task.
        </para>
        <sample id="jacocotesttast" dir="testing/jacoco/quickstart" title="Configuring test task">
            <sourcefile file="build.gradle" snippet="testtask-configuration"/>
        </sample>
        <table>
            <title>Default values of the JaCoCo Task extension</title>
            <thead>
                <tr>
                    <td>Property</td>
                    <td>Gradle default</td>
                </tr>
            </thead>
            <tr>
                <td>enabled</td>
                <td>true</td>
            </tr>
            <tr>
                <td>destPath</td>
                <td><replaceable>$buildDir</replaceable>/jacoco
                </td>
            </tr>
            <tr>
                <td>append</td>
                <td>true</td>
            </tr>
            <tr>
                <td>includes</td>
                <td>[]</td>
            </tr>
            <tr>
                <td>excludes</td>
                <td>[]</td>
            </tr>
            <tr>
                <td>excludeClassLoaders</td>
                <td>[]</td>
            </tr>
            <tr>
                <td>includeNoLocationClasses</td>
                <td>false</td>
            </tr>
            <tr>
                <td>sessionId</td>
                <td>
                    <literal>auto-generated</literal>
                </td>
            </tr>
            <tr>
                <td>dumpOnExit</td>
                <td>
                    <literal>true</literal>
                </td>
            </tr>
            <tr>
                <td>output</td>
                <td>
                    <literal>Output.FILE</literal>
                </td>
            </tr>
            <tr>
                <td>address</td>
                <td>
                    <literal>-</literal>
                </td>
            </tr>
            <tr>
                <td>port</td>
                <td>
                    <literal>-</literal>
                </td>
            </tr>
            <tr>
                <td>classDumpPath</td>
                <td>
                    <literal>-</literal>
                </td>
            </tr>
            <tr>
                <td>jmx</td>
                <td>
                    <literal>false</literal>
                </td>
            </tr>
        </table>
        <para>While all tasks of type
            <apilink class="org.gradle.api.tasks.testing.Test"/>
            are automatically enhanced to provide coverage information when the <literal>java</literal> plugin has been applied,
            any task that implements <apilink class="org.gradle.process.JavaForkOptions"/> can be enhanced by the JaCoCo plugin.
            That is, any task that forks Java processes can be used to generate coverage information.
        </para>
        <para>
            For example you can configure your build to generate code coverage using the <literal>application</literal> plugin.
        </para>
        <sample id="jacoco-application-setup" dir="testing/jacoco/application" includeLocation="true" title="Using application plugin to generate code coverage data">
            <sourcefile file="build.gradle" snippet="application-configuration"/>
        </sample>
        <sample id="jacoco-application-output" dir="testing/jacoco/application" title="Coverage reports generated by applicationCodeCoverageReport">
            <layout after='run applicationCodeCoverageReport'>
                build/jacoco/run.exec
                build/reports/jacoco/applicationCodeCoverageReport/html/index.html
            </layout>
        </sample>
    </section>

    <section id="sec:jacoco_tasks">
        <title>Tasks</title>
        <para>For projects that also apply the Java Plugin, The JaCoCo plugin automatically adds the following tasks:</para>
        <table>
            <title>JaCoCo plugin - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>jacocoTestReport</literal>
                </td>
                <td>-</td>
                <td>
                    <apilink class="org.gradle.testing.jacoco.tasks.JacocoReport"/>
                </td>
                <td>Generates code coverage report for the test task.</td>
            </tr>
            <tr>
                <td>
                    <literal>jacocoTestCheck</literal>
                </td>
                <td>-</td>
                <td>
                    <apilink class="org.gradle.testing.jacoco.tasks.JacocoCheck"/>
                </td>
                <td>Verifies code coverage metrics based on specified rules for the test task.</td>
            </tr>
        </table>
    </section>

    <section id="sec:jacoco_dependency_management">
        <title>Dependency management</title>
        <para>The JaCoCo plugin adds the following dependency configurations:</para>
        <table>
            <title>JaCoCo plugin - dependency configurations</title>
            <thead>
                <tr>
                    <td>Name</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <filename>jacocoAnt</filename>
                </td>
                <td>The JaCoCo Ant library used for running the
                    <literal>JacocoReport</literal>
                    and
                    <literal>JacocoMerge</literal>
                    tasks.
                </td>
            </tr>
            <tr>
                <td>
                    <filename>jacocoAgent</filename>
                </td>
                <td>The JaCoCo agent library used for instrumenting the code under test.</td>
            </tr>
        </table>
    </section>

</chapter>