Jacoco. This tutorial describes the usage of the Jacoco, which can be used to check the code coverage of Java projects.

1. Jacoco

Jacoco is an open source project, which can be used to check production code for test code coverage. It creates reports and integrates well with IDEs like the Eclipse IDE. Integration is also available for other IDEs and continuous integration environments. So there are also Gradle, SonarQube and Jenkins plugins to make these code coverage checks outside the IDE and therefore globally available to the development team.

2. Installation

You can install Jacoco in the Eclipse IDE via the Eclipse Marketplace from Help  Eclipse Marketplace and search for EclEmma

eclipse marketplace

Alternatively, use the Help  Install New Software…​ menu entry. EclEmma is part of the latest Eclipse release update side:

http://download.eclipse.org/releases/latest]

Install all software components from this update site and restart your Eclipse IDE afterwards.

3. Using Jacoco in Eclipse

With EclEmma installed the context menu of a project also contains a Coverage As entry.

coverage as menu

And besides the debug button in the main toolbar will also be another button for running java code with code coverage analysis.

coverage as toolbar

Once a program is run with code coverage a Coverage View will show up in the Eclipse IDE.

coverage view

Usually the analysis shows up when the java application is shut down, but with the Dump Execution Data button in the Coverage View’s toolbar a dump of execution data can be created.

execution data dump

The tooling does not only show the coverage in the Coverage View, but also in the Java Editor itself. Tested code is highlighted in green and untested code is highlighted in red.

coverage in editor

4. Using Jacoco with Gradle

Using Jacoco in Gradle is straight forward. The jacoco plugin can be applied and by default places a report into $buildDir/reports/jacoco/test.

apply plugin: "jacoco"

Further options about the Jacoco plugin can be found here: JaCoCo User Guide

5. Using Jacoco with Maven

Jacoco can also be run during a Maven build. The results of the code coverage analysis can for example be reviewed as an HTML report, which usually can be found in the target/report folder of a built Maven project.

The current version of the jacoco-maven-plugin can be found here: http://mvnrepository.com/artifact/org.jacoco/jacoco-maven-plugin]jacoco-maven-plugin] on MavenCentral.

6. Exercise: Run Jacoco during a Maven build

6.1. Target

The target of this exercise is to run Jacoco during a maven build by using the jacoco-maven-plugin.

6.2. Creating a sample Maven project

Create a com.example.jacoco Maven project.

maven project wizard overview

Press Next to get to the first Maven Project Wizard Page.

maven project wizard default settings

Here the defaults should be sufficient so that the Next button can be pressed directly. On the next page the maven-archetype-quickstart can be selected.

maven project wizard quickstart archetype

The following parameters can be used for the project configuration:

maven project wizard config

When pressing finish a new maven project is created.

6.3. Applying the Jacoco plugin

The complete contents of the pom.xml file should look like this:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>com.example.jacoco</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <jdk.version>1.8</jdk.version>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.1</version>
                <configuration>
                    <source>${jdk.version}</source>
                    <target>${jdk.version}</target>
                    <encoding>${project.build.sourceEncoding}</encoding>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
                <version>0.7.6.201602180812</version>
                <executions>
                    <!-- Prepares the property pointing to the JaCoCo runtime agent which
                        is passed as VM argument when Maven the Surefire plugin is executed. -->
                    <execution>
                        <id>pre-unit-test</id>
                        <goals>
                            <goal>prepare-agent</goal>
                        </goals>
                        <configuration>
                            <!-- Sets the name of the property containing the settings for JaCoCo
                                runtime agent. -->
                            <propertyName>surefireArgLine</propertyName>
                        </configuration>
                    </execution>
                    <!-- Ensures that the code coverage report for unit tests is created
                        after unit tests have been run. -->
                    <execution>
                        <id>post-unit-test</id>
                        <phase>test</phase>
                        <goals>
                            <goal>report</goal>
                        </goals>
                        <configuration>
                            <!-- Sets the output directory for the code coverage report. -->
                            <outputDirectory>${project.reporting.outputDirectory}/jacoco-ut</outputDirectory>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <!-- Used for unit tests -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>2.19.1</version>
                <configuration>
                    <!-- Sets the VM argument line used when unit tests are run. -->
                    <argLine>${surefireArgLine}</argLine>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <dependencies>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.12</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>

6.4. Validate

Run the following command in the command line or via the M2E tooling:

mvn clean verify

Besides the normal Maven build a site folder will be created.

Inside this folder will be a jacoco-ut folder, which contains the test coverage analysis files.

The index.html can be opened in a browser in order to visually see the test coverage results.

jacoco report html

7. Jacoco Code Analysis Resources

8. vogella training and consulting support

Copyright © 2012-2019 vogella GmbH. Free use of the software examples is granted under the terms of the Eclipse Public License 2.0. This tutorial is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany license.